# 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, and `VISIBILITY DISCOVERABLE` makes the Share appear for users who have access. The update-behavior default is `UPDATE AUTOMATIC` (the Share reflects database changes automatically). On DuckDB clients 1.5.4 and lower it defaults to `UPDATE MANUAL` (the Share is a static snapshot until you run `UPDATE SHARE`).

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 AUTOMATIC`**: Share automatically reflects database changes within ~5 minutes
- **`UPDATE MANUAL`**: Share content only updates when you run `UPDATE SHARE` command

The default is `UPDATE AUTOMATIC`. On DuckDB clients 1.5.4 and lower the default is `UPDATE MANUAL`. Specify the mode explicitly for consistent behavior across versions.

### 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

You've created a table and shared it with your team. In the next part, you'll visualize this data and keep it fresh automatically. If you'd rather explore on your own, here are some directions:

- Create a [Dive](/key-tasks/dives/) from your data: interactive visualizations you build with natural language
- Talk to your data from an AI client with the [MotherDuck MCP Server](../mcp-getting-started.md)
- Automate ingestion and transformation with [Flights](/key-tasks/flights/), scheduled Python that runs next to your data
- Connect BI tools through the [Postgres endpoint](../interfaces/postgres-endpoint.md)

👉 **[Continue to Part 4: Visualizing and Automating →](../part-4)**


---

## 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.