# motherduck-share-data
> Create, consume, or manage MotherDuck data shares, including audience grants, table filters, and refresh policy.
Create, consume, or manage MotherDuck data shares, including audience grants, table filters, and refresh policy.

[Workflow skill](/sql-reference/agent-skills/#workflow-skills) · [View source on GitHub](https://github.com/motherduckdb/agent-skills/tree/v3.0.0/skills/motherduck-share-data)

:::info

This page shows the skill's `SKILL.md`: the instructions a coding agent loads when a task matches the description above. To install every MotherDuck skill in Claude Code, Codex, Cursor, or Gemini CLI, see [Install MotherDuck Skills](/key-tasks/ai-and-motherduck/agent-skills/). To install only this skill with the [Skills CLI](https://github.com/vercel-labs/skills), run:

```bash
npx -y skills add motherduckdb/agent-skills --skill motherduck-share-data --yes --global
```

This skill relies on [`motherduck-connect`](/sql-reference/agent-skills/motherduck-connect/), [`motherduck-explore`](/sql-reference/agent-skills/motherduck-explore/), and [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/). Install those too, or install the full catalog.

:::

## Source of truth

- Prefer the current MotherDuck sharing docs and SQL reference first.
- If the MotherDuck MCP `ask_docs_question` feature is available, use it before falling back to public docs.
- Keep the sharing model aligned with the documented behavior:
  - zero-copy and metadata-only
  - a database is the share source, with optional table/view filtering through `INCLUDE_PATTERN`
  - optional secure views that filter rows, drop columns, or mask values for each consumer
  - read-only recipients
  - owner-controlled update and include-pattern policy

## Prerequisites

A working connection, the source database, and the intended audience. Reuse these from context; related skills are available for missing setup or SQL details.

## Default posture

- Prefer `ACCESS RESTRICTED` plus `GRANT READ ON SHARE ... TO ROLE ...` for governed internal distribution. Use `ACCESS ORGANIZATION` only when the caller deliberately wants its legacy organization-wide behavior.
- Use `INCLUDE_PATTERN` when every recipient of one share should see the same table/view subset. Create separate shares when audiences need different table subsets; when they differ only by rows, columns, or masked values, one share with secure views can serve them all.
- Use `UPDATE MANUAL` when the recipient needs a stable snapshot or versioned delivery.
- Use `ACCESS RESTRICTED` or `VISIBILITY HIDDEN` when distribution should stay tightly controlled.
- Confirm whether the recipient is an internal user, another organization, or public before choosing access and visibility.
- For write-heavy publishers, verify the DuckDB client version is one MotherDuck supports before relying on checkpoint or concurrent-write behavior during share-update workflows.
- `INCLUDE_PATTERN` selects whole tables and views; never describe it as row- or column-level security. It works on native MotherDuck and fully managed DuckLake sources.
- For row filtering, hidden columns, or masked values, add secure views to the share: `CREATE SHARE ... WITH SECURE VIEW REPLACES <table> AS (SELECT ...)` or `ALTER SHARE ... ADD [OR REPLACE] SECURE VIEW`. Key the policy on `current_email()` for people, `current_user` for service accounts, or `is_role_in_session('<role>')`. One share with secure views can replace a set of per-audience shares. They are plan-gated, and managing them in SQL needs a recent DuckDB client and a read-write token; check the current secure-views docs for both.
- Write secure views with explicit column lists, never `SELECT *` (including `SELECT * EXCLUDE` or `SELECT * REPLACE`): a new source column would otherwise leak to every consumer, and schema changes break the view. A table the share exposes without a replacing secure view stays fully readable. Combine `INCLUDE_PATTERN` (which tables) with secure views (which rows and columns) and keep macro schemas and mapping tables outside the pattern.
- MotherDuck secure views are share policies. DuckDB's own `CREATE SECURE VIEW` is only an optimizer barrier and restricts nothing.

## Workflow

1. Identify the exact database to publish and who should consume it.
2. Decide the audience, visible table/view subset, discoverability, and freshness requirements before writing SQL.
3. Preview and validate any include pattern against the live source catalog, then create the share with explicit access, visibility, update mode, and optional `INCLUDE_PATTERN`.
4. If access is restricted, grant users or roles explicitly. If the share is hidden or link-based, distribute the share URL directly.
5. Read the share back with `LIST SHARES` or `MD_INFORMATION_SCHEMA.OWNED_SHARES`; for filtered shares, verify the stored pattern and consumer-visible catalog. For secure views, run `SHOW SECURE VIEWS ON SHARE <name>` and attach the share as a consumer to check the result; identity functions evaluate as whoever runs the test.
6. Have recipients `ATTACH` the shared database and query it read-only.
7. Use `ALTER SHARE ... SET|RESET INCLUDE_PATTERN` for table/view scope changes and `ALTER SHARE ... ADD|DROP SECURE VIEW` for policy changes (not both in one statement). Avoid `CREATE OR REPLACE SHARE` on a share with secure views; it drops any view it does not restate. If the share uses `UPDATE MANUAL`, the owner runs `UPDATE SHARE` and consumers run `REFRESH DATABASE` when a new snapshot is ready.

For answer, review, or planning requests, return the sharing design and SQL without provisioning. For create, update, grant, or revoke requests, perform the requested in-scope operation and validate the resulting access; ask before public exposure, destructive revocation, or unrelated grants.

## References

Read only the reference sections needed for the current task.

- For who-gets-what design across teams, tenants, or environments, use [`motherduck-security-governance`](/sql-reference/agent-skills/motherduck-security-governance/) (`references/ACCESS_CONTROL_SETUPS.md`).
- Read [`references/SHARE_PLAYBOOK.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-share-data/references/SHARE_PLAYBOOK.md) for the full SQL playbook, role grants, include-pattern rules, secure views, access/update decisions, consumer workflow, and common failure modes.

## Related skills

Load related skills only for missing capabilities; reuse established context.

- [`motherduck-connect`](/sql-reference/agent-skills/motherduck-connect/) for MotherDuck authentication and connection setup
- [`motherduck-explore`](/sql-reference/agent-skills/motherduck-explore/) for discovering databases, tables, columns, and existing shares
- [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/) for validating share SQL and downstream queries
- [`motherduck-duckdb-sql`](/sql-reference/agent-skills/motherduck-duckdb-sql/) for DuckDB SQL syntax and lookup support
- [`motherduck-security-governance`](/sql-reference/agent-skills/motherduck-security-governance/) for role design and access-boundary review

## Files in this skill

The agent reads these files when the instructions above point to them.

- [`references/SHARE_PLAYBOOK.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-share-data/references/SHARE_PLAYBOOK.md)

## Docs this skill draws on

- [Sharing concepts and overview](https://motherduck.com/docs/key-tasks/sharing-data/sharing-overview/)
- [Table-level security](https://motherduck.com/docs/key-tasks/sharing-data/table-level-security/)
- [CREATE SHARE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/create-share/)
- [ALTER SHARE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/alter-share/)
- [UPDATE SHARE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/update-share/)
- [REFRESH DATABASE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/refresh-database/)
- [Row-level and column-level security with secure views](https://motherduck.com/docs/key-tasks/sharing-data/secure-views/)


---

## 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%2Fagent-skills%2Fmotherduck-share-data%2F&page_title=motherduck-share-data&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.
