# CREATE SHARE > Create a Share from a database and grant access to users or roles. 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 ] [] [FROM ] ( [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//`. - 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) - equivalent to granting READ to the Explorer role, so every preset role 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 or roles can be granted using the [`GRANT`](grant-access.md) and [`REVOKE`](revoke-access.md) commands. If omitted, defaults to `ACCESS ORGANIZATION`. :::warning `ACCESS ORGANIZATION` is planned for deprecation in favor of role-based access control. It is equivalent to granting READ on the share to the Explorer role. To share with your whole organization, create a restricted share and run `GRANT READ ON SHARE TO ROLE explorer`. See [Roles and access control](/concepts/roles-and-access-control/). ::: :::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 six regions: - **US East (N. Virginia):** `us-east-1` - **US West (Oregon):** `us-west-2` - **Europe (Frankfurt):** `eu-central-1` - **Europe (Dublin):** `eu-west-1` - **Asia Pacific (Tokyo):** `ap-northeast-1` - **Asia Pacific (Sydney):** `ap-southeast-2` ::: ### _VISIBILITY_ clause For Organization-scoped and Restricted Shares, you may choose to make them Discoverable: - `VISIBILITY DISCOVERABLE` (default) - organization members with access can list or 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; -- Create a restricted Share and grant it to every preset role. CREATE SHARE birds_share FROM birds ( ACCESS RESTRICTED, VISIBILITY DISCOVERABLE, UPDATE AUTOMATIC ); GRANT READ ON SHARE birds_share TO ROLE explorer; ``` :::note All Shares created prior to June 6, 2024 are Unrestricted and Hidden. To restrict a legacy Share to your organization, recreate it with `ACCESS RESTRICTED`, make it Discoverable, and grant READ to the Explorer role. ::: --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmotherduck-sql-reference%2Fcreate-share%2F&page_title=CREATE%20SHARE&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.