---
sidebar_position: 1
title: CREATE SHARE
description: Create a share from a database to share data with other users
---

# CREATE SHARE

The `CREATE SHARE` statement creates a new share from a database. This command is used to share databases with other users. [Learn more about sharing in MotherDuck](/key-tasks/sharing-data/sharing-overview.md).

:::note
All shares are **read-only**. Only the creator of a database has write permissions.
:::

## Syntax

```sql
CREATE [ OR REPLACE ] SHARE [ IF NOT EXISTS ] [<share name>] [FROM <database name>] (
    [ACCESS ORGANIZATION | UNRESTRICTED | RESTRICTED],
    [VISIBILITY DISCOVERABLE | HIDDEN],
    [UPDATE MANUAL | AUTOMATIC]
);
```

If you attempt to create a share, yet a share with that name already exists, no new share will be created and the query will return an error.
The error will be silenced when you specify `IF NOT EXISTS`.

This statement returns a share URL of the form `md:_share/<source_database_name>/<share_token>`.

- If the share is **Hidden**, you must pass this URL to the **data consumer**, who will need to [`ATTACH`](attach.md) the share.
- If the share is **Discoverable**, passing the URL to the **data consumer** is optional.

### _OR REPLACE_ clause

When you use the `OR REPLACE` clause to create or replace a share named `foo`, the share's **URL changes**. This means that
any clients connected to the old share URL will be **disconnected within a few minutes**.

To continue using the share named `foo`, clients must **re-attach** to it using the **new URL** provided by the `CREATE SHARE`
command. The old share URL will no longer be valid.

### _ACCESS_ clause

You can configure scope of access of the share:

- `ACCESS ORGANIZATION` (default) - only members of your Organization can access the share.
- `ACCESS UNRESTRICTED` - all MotherDuck users in the same cloud region as the share creator can access the share.
- `ACCESS RESTRICTED` - the share owner will be the only user with access to the share initially.  Access for other users the share can be updated using the [`GRANT`](grant-access.md) and [`REVOKE`](revoke-access.md) commands.

If omitted, defaults to `ACCESS ORGANIZATION`.

:::note
Shares are **region-scoped** based on your Organization's cloud region. Each MotherDuck Organization is scoped to a single cloud region that must be chosen at Org creation when signing up.

MotherDuck is available on AWS in two regions:
- **US East (N. Virginia):** `us-east-1`
- **Europe (Frankfurt):** `eu-central-1`
:::

### _VISIBILITY_ clause

For Organization scoped shares **only**, you may choose to make them Discoverable:

- `VISIBILITY DISCOVERABLE` (default) - all members of your Organization will be able to list/find the share in the UI or SQL.
- `VISIBILITY HIDDEN` - the share can only be accessed directly by the share URL, and is not listed to other users. A Share can be hidden only if it has its `ACCESS` set to `RESTRICTED`.

If omitted, Organization-scoped and Restricted shares default to `VISIBILITY DISCOVERABLE`. Unrestricted shares can only be **Hidden**.

### _UPDATE_ clause

Shares can be automatically or manually updated by the share creator.

- `UPDATE MANUAL` (default) - shares are only updated using the [`UPDATE SHARE`](update-share.md) command.
- `UPDATE AUTOMATIC` - the share is automatically updated when the underlying database changes. Typically, changes on the underlying database will automatically be published to the share within at most 5 minutes, after writes have completed. Ongoing overlapping writes may prolong share updating.

If omitted, defaults to `UPDATE MANUAL`.

### Shorthand convention

- If the database name is omitted, a share will be created from the current/active database.
- If the share name is omitted, the share will be named after the source database.
- If both database and share names are omitted, the share will be named and created after the current/active database.

## Example usage

```sql
-- If ducks_share exists, it will be replaced with a new share.
--A new share URL is returned.
CREATE OR REPLACE SHARE ducks_share;
       
-- If ducks_share exists, nothing is done. Its existing share URL is returned.
--Otherwise, a new share is created and its share URL is returned. 
CREATE SHARE IF NOT EXISTS ducks_share;
```

```sql
USE mydb;
-- Using shorthand: Create a share named ''mydb'' from the current database ''mydb''.
-- Defaults: ACCESS ORGANIZATION, VISIBILITY DISCOVERABLE, UPDATE MANUAL
CREATE SHARE;

-- Using shorthand: Create a share named ''db2'' from the specified database ''db2''.
-- Defaults: ACCESS ORGANIZATION, VISIBILITY DISCOVERABLE, UPDATE MANUAL
CREATE SHARE FROM db2;

-- Explicitly create a share named ''birds_share'' from database ''birds''.
-- Set specific access, visibility, and update behavior.
CREATE SHARE birds_share FROM birds (
    ACCESS RESTRICTED,  -- Only the share owner has initial access 
    VISIBILITY HIDDEN,    -- Not listed; requires direct URL access
    UPDATE AUTOMATIC      -- Automatically updates with source DB changes
);
```

:::note
All shares created prior to June 6, 2024 are Unrestricted and Hidden. To make these legacy shares Organization-scoped and Discoverable, you can alter them in the UI or delete and create new shares.
:::