---
sidebar_position: 3
title: Sharing data with specific users
description: Grant read access to specific users for multi-tenant applications and collaboration.
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import useBaseUrl from '@docusaurus/useBaseUrl';

MotherDuck lets you securely share data with specific users. Common scenarios include:
- Building data applications, in which each tenant should only have access to their own data.
- Sharing sensitive data within your Organization.
- Sharing data outside of your 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`
:::

Sharing data with individuals is easy. MotherDuck supports two approaches:
- Creating a share with **Restricted** access, limiting access to a list of specified users within your organization (known as an "ACL" or "Access Control List").
- Creating a **Hidden** share and providing individuals with the share URL.

## Creating a share with restricted access (ACL)
**Overview**
1. **Data provider** creates a share with **Restricted** access.
2. **Data provider** _(share owner)_ specifies which **data consumers** _(users)_ can read from the share.
3. **Data consumer** **attaches** the share.
4. **Data provider** periodically updates the share to push new data to **data consumers**.

Anyone within your organization that is _not_ included in the list will **not** be able to access the share, even if they have a share link.

<Tabs>
<TabItem value="UI" label="UI">
Click on the "trident" next to the database you'd like to share. Select "Share".

<img src={useBaseUrl('/img/key-tasks/sharing-data/share_acl_ui.png')} alt="trident" width="50%" />

1. Optionally name the share.
2. Under "Who has access" choose "Specified users with the share link".  Search for and add the users within your Organization that should have access to read the share.
3. Choose whether the share should be [automatically updated or not](../sharing-overview/#updating-shared-data). Default is `MANUAL`.
3. Create the share.
4. For the specified users, the share will appear in their UI under 'Shared with me' and can be attached.

</TabItem>

<TabItem value="SQL" label="SQL">
```sql
use birds;
CREATE SHARE birds FROM birds
    (ACCESS RESTRICTED); -- This query creates a share accessible only by organization users specified with GRANT commands
GRANT READ ON SHARE birds TO duck1, duck2; -- Gives the users with usernames 'duck1' and 'duck2' access to the share 'birds'
```

**Data consumer** must `ATTACH` the restricted share before querying the share. See [consuming restricted shares](./#consuming-restricted-shares).

</TabItem>
</Tabs>

:::note
Restricted shares default to **Discoverable** visibility for users who have been granted access to the share. (Learn more about ["Discoverable shares"](../sharing-overview/#discoverable-shares)).
:::

### Consuming restricted shares

The **data consumers** in your Organization with access to the restricted share can use the UI or SQL to **attach** the share and start querying it.

<Tabs>

<TabItem value="UI" label="UI">
1. Select the restricted share you want to attach under "Shared with me"
2. Click "attach" and optionally name the resulting database.
3. You can query the resulting database.

</TabItem>

<TabItem value="SQL" label="SQL">
Run the `ATTACH` command to attach the share as a queryable database. This is a zero-cost metadata-only operation.

```sql
ATTACH md:_share/birds/e9ads7-dfr32-41b4-a230-bsadgfdg32tfa; -- Creates a zero-copy clone database called birds
```

Learn more about [ATTACH](/sql-reference/motherduck-sql-reference/attach.md).

</TabItem>
</Tabs>

### Modifying share access

**Data providers** _(share owners)_ can modify which users within your Organization have access to the share.

<Tabs>

<TabItem value="UI" label="UI">
1. Find the target share in the "Shares I've created" section of the Object Explorer, and choose the 'Alter' option from the context menu.  
2. From here, you can add and remove users with access to the share.
3. You may also alter the share to use a different **access** scope. Learn more about [share access scopes](../sharing-overview/#organization-shares).

For more details on how to configure access controls for restricted shares, see the [`GRANT READ ON SHARE` reference page](/sql-reference/motherduck-sql-reference/grant-access/).

</TabItem>

<TabItem value="SQL" label="SQL">

<!-- markdownlint-disable MD040 -->
```sql
GRANT READ ON SHARE birds TO duck3; -- Gives the user with username 'duck3' access to the share 'birds'

REVOKE READ ON SHARE birds FROM penguin; -- Revokes access to the share 'birds' from the user with username 'penguin'
```
<!-- markdownlint-enable MD040 -->

For more details on configuring access controls for restricted shares, see the [`GRANT READ ON SHARE` reference page](/sql-reference/motherduck-sql-reference/grant-access/).

</TabItem>
</Tabs>


## Creating hidden shares
**Overview**

1. **Data provider** creates the share URL and passes this URL to the **data consumer**.
2. **Data consumer** **attaches** the share.
3. **Data provider** periodically updates the share to push new data to **data consumers**.


To share a database, first create a Hidden share. No actual data is copied and no additional costs are incurred in this process.

<Tabs>
<TabItem value="UI" label="UI">
Click on the "trident" next to the database you'd like to share. Select "share".

<img src={useBaseUrl('/img/key-tasks/sharing-data/ui-share3.png')} alt="trident" width="50%" />

1. Optionally name the share.
2. To share the data with MotherDuck users inside or outside of your Organization, choose the "Anyone with the share link" option.  This will enable anyone with the share link in the same cloud region to attach and query the share, including users outside your Organization.
3. Create the share.
4. Copy the resulting **ATTACH** command to your clipboard and send it to your **data consumers**.

</TabItem>

<TabItem value="SQL" label="SQL">
```sql
use birds;
CREATE SHARE birds FROM birds
    (ACCESS UNRESTRICTED , VISIBILITY HIDDEN); -- This query creates a Hidden share accessible by anyone with the share link in the same cloud region, including users outside your Organization
> md:_share/birds/e9ads7-dfr32-41b4-a230-bsadgfdg32tfa
```

Save the returned share URL and pass it to **data consumers**.

</TabItem>
</Tabs>

### Consuming hidden shares

The **data consumer** in your Organization can use SQL to attach the share and start querying it!

<Tabs>

<TabItem value="SQL" label="SQL">
Run the `ATTACH` command to attach the share as a queryable database. This is a zero-cost metadata-only operation.

```sql
ATTACH md:_share/birds/e9ads7-dfr32-41b4-a230-bsadgfdg32tfa; -- Creates a zero-copy clone database called birds
```

Learn more about [ATTACH](/sql-reference/motherduck-sql-reference/attach.md).

</TabItem>
</Tabs>

## Updating shared data

If during creation of the share, the **data provider** chose to have the share updated automatically, the share will be updated periodically.
If the share was created with `MANUAL` updates, the **data provider** needs to manually update the share.

```sql
UPDATE SHARE birds; 
```

Learn more about [UPDATE SHARE](/sql-reference/motherduck-sql-reference/update-share.md) and [data replication timing and checkpoints](./updating-shares.md).