# 3 - Sharing Your Database
> Learn how to share your databases and collaborate with your team
In this section, you'll learn how to share your databases with colleagues and collaborate effectively using MotherDuck's sharing features.

👈 **[Go back to Part 2: Loading Your Dataset](../part-2)**

## Creating and sharing your data

Let's create a table with sample data in your playground database, then share it with others. The `docs_playground` database is automatically created when you connect, so you can start experimenting right away!

First, let's populate your playground database with some currency exchange data:

#### SQL example

Database: `docs_playground`

```sql
CREATE TABLE docs_playground.currency_rates AS
SELECT
   'USD' as currency_code,
   'US Dollar' as currency_name,
   1.0 as rate_to_usd,
   '2024-01-15' as rate_date
UNION ALL
SELECT 'EUR', 'Euro', 0.85, '2024-01-15'
UNION ALL
SELECT 'GBP', 'British Pound', 0.75, '2024-01-15'
UNION ALL
SELECT 'JPY', 'Japanese Yen', 110.0, '2024-01-15';
```

## Sharing your database

With your database and sample data in place, you can share this dataset with others. MotherDuck shares create a point-in-time snapshot of your database that can be accessed by specified users or groups.

When creating a Share, the most important parameters control **access scope**, **visibility**, and **update behavior**. Use `ACCESS RESTRICTED` with a role grant so access follows the preset-role hierarchy. `VISIBILITY DISCOVERABLE` makes the Share appear for users who have access, and `UPDATE MANUAL` creates a static snapshot that doesn't auto-update.

To share with your whole organization, create a restricted Share and grant READ to the Explorer role. Builder and Admin inherit the grant.

### SQL

#### SQL example

Database: `docs_playground`

```sql
CREATE SHARE IF NOT EXISTS currency_data_share FROM docs_playground (
    ACCESS RESTRICTED,
    VISIBILITY DISCOVERABLE
);
```

Then grant the Explorer role READ access:

```sql
GRANT READ ON SHARE currency_data_share TO ROLE explorer;
```

### MotherDuck UI

You can also create shares through the MotherDuck UI by clicking the dropdown menu next to your database and selecting the share option. This will open a window to configure your share settings.

![share 1](./img/screenshot_tutorial_share_1_2.png)
![share 2](./img/screenshot_tutorial_share_2_2.png)

Once you grant the Share to Explorer, Explorer, Builder, and Admin users can view it in the MotherDuck UI under "Shared with me".

Learn more about [sharing in MotherDuck](../../key-tasks/sharing-data/sharing-within-org.md).

## Understanding share configuration

When creating shares, you can control three key aspects: **who can access** the data, **how users discover** the share, and **when the data updates**. Each parameter has specific options that determine the sharing behavior.

### ACCESS - who can access the share

- **`ACCESS ORGANIZATION`** (default, planned for deprecation): Equivalent to granting READ to the Explorer role
- **`ACCESS UNRESTRICTED`**: All MotherDuck users in the same cloud region as your Organization can access the share
- **`ACCESS RESTRICTED`**: Only the Share owner has initial access; grant additional access to users or roles with `GRANT`

### VISIBILITY - how users discover the share

- **`VISIBILITY DISCOVERABLE`** (default): The share appears in your organization's "Shared with me" section for easy discovery
- **`VISIBILITY HIDDEN`**: Share can only be accessed through a direct URL; not listed in any user interface

:::info Important Visibility Rules
- Organization and Restricted shares default to `DISCOVERABLE`
- Unrestricted shares can only be `HIDDEN`
- Hidden shares can only be used with `ACCESS RESTRICTED`
:::

### UPDATE - when share data updates

- **`UPDATE MANUAL`** (default): Share content only updates when you run `UPDATE SHARE` command
- **`UPDATE AUTOMATIC`**: Share automatically reflects database changes within ~5 minutes

### Example share configurations

#### SQL example

Database: `docs_playground`

```sql
-- Share with every preset role
CREATE SHARE IF NOT EXISTS team_currency_analysis FROM docs_playground (
    ACCESS RESTRICTED,
    VISIBILITY DISCOVERABLE,
    UPDATE MANUAL
);
```

Grant the Share to the Explorer role so every preset role receives access:

```sql
GRANT READ ON SHARE team_currency_analysis TO ROLE explorer;
```

#### SQL example

Database: `docs_playground`

```sql
-- Restricted share for selective access
CREATE SHARE IF NOT EXISTS private_analysis FROM docs_playground (
    ACCESS RESTRICTED,
    VISIBILITY HIDDEN,
    UPDATE AUTOMATIC
);
```

## Querying shared data

After creating a share, authorized users can access the shared database in two ways: by using the share URL directly or by attaching it as a database alias:

```sql
-- Attach a shared database
ATTACH 'md:_share/docs_playground/b556630d-74f1-435c-9459-cfb87d349cb3' AS shared_currency;

-- Query the shared data
SELECT * FROM shared_currency.currency_rates
WHERE rate_to_usd < 1.0
ORDER BY rate_to_usd DESC;
```

## Managing Shares

You can also manage your existing shares:

#### SQL example

Database: `docs_playground`

```sql
SELECT name, source_db_name, access, visibility FROM MD_INFORMATION_SCHEMA.OWNED_SHARES WHERE name LIKE '%currency%';
```

## Going further

Now that you've mastered the basics, here are some next steps to explore:

- Learn about [MotherDuck's Dual Execution](/key-tasks/running-hybrid-queries/) feature
- Connect to your favorite BI tools: [Tableau](../../integrations/bi-tools/tableau/index.mdx), [Power BI](../../integrations/bi-tools/powerbi/index.mdx) and learn more about [read scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/)
- Set up data pipelines with [dbt](../../integrations/transformation/dbt.md)
- Look at our [supported integrations](/integrations) to integrate with your data stack.


---

## 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=%2Fgetting-started%2Fe2e-tutorial%2Fpart-3%2F&page_title=3%20-%20Sharing%20Your%20Database&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.