# GRANT READ ON SHARE


> Give users access to a restricted share.

**Requires permission:** Manage all organization Shares — included by default in the Admin preset role. A custom role qualifies when it inherits a role that includes the permission. Only the share owner can grant access to a Share. Organization Admins can view a Share's grants (SHOW GRANTS ON SHARE) but cannot grant access to Shares they do not own. See [Roles and access control](/concepts/roles-and-access-control/#what-each-role-can-do).

:::note
Only the owner of a Share can run `GRANT READ ON SHARE`. Organization Admins can view existing grants with `SHOW GRANTS ON SHARE`, but running `GRANT` against a Share owned by another account fails with `Catalog Error: Database share <name> not found`. In a multi-service-account (hypertenancy) setup, authenticate as the Share's owner to manage its grants.
:::

For restricted Shares, use the `GRANT` command to give access to individual users or to a [role](/concepts/roles-and-access-control/). After being granted access, a user still needs to run an `ATTACH` command to query the shared database.

## Syntax

```sql
GRANT READ ON SHARE <share name> TO { USER <username> | ROLE <role name> } [, ...];
```

A bare grantee name without `USER` or `ROLE` is treated as a user.

## Example usage

```sql
-- Give the user 'duck' access to the share 'birds'.
GRANT READ ON SHARE birds TO USER duck;

-- Give two users access to the share 'taxis'.
GRANT READ ON SHARE taxis TO USER user_1, USER user_2;

-- Give every user with the 'finance' role access.
GRANT READ ON SHARE birds TO ROLE finance;

-- Grant to a mix of users and roles in one statement.
GRANT READ ON SHARE taxis TO USER user_1, USER user_2, ROLE finance;

-- Grant organization-wide access by granting to the Explorer role.
GRANT READ ON SHARE birds TO ROLE explorer;
```

If a username contains special characters, such as '@', it must be enclosed in double quotes (`"`).

Granting to a role gives access to every current and future user with that role. Because preset roles are concentric, granting to the Explorer role also reaches Builder and Admin. See [how data access grants flow](/concepts/roles-and-access-control/#how-data-access-grants-flow).

## Complete workflow example

Below is a complete workflow showing how to share a database with a restricted audience and how recipients can access it. We will first create a share and grant access to specific users. Then, we will show how recipients can attach and query the shared database. For more information on each step, refer to the [CREATE SHARE](create-share.md), [LIST SHARES](list-shares.md), and [ATTACH](attach.md) documentation.

### 1. Owner creates a share and grants access

```sql
-- Owner: create a restricted share of database 'analytics'
-- Using CREATE OR REPLACE allows updating the share if it already exists.
-- ACCESS RESTRICTED is required to use GRANT/REVOKE.
CREATE OR REPLACE SHARE analytics_share FROM analytics (ACCESS RESTRICTED);

-- Owner: Grant access to specific users.
-- If a username contains special characters like '@', enclose it in double quotes.
GRANT READ ON SHARE analytics_share TO user_1, "user_2@example-com";

-- Owner retrieves the share URL to provide to recipients.
-- The URL uniquely identifies the share.
LIST SHARES;
-- Example output contains URL like: md:_share/analytics/0a9a026ec5a55946a9de39851087ed81

-- Owner shares the full URL (e.g., 'md:_share/analytics/0a9a026ec5a55946a9de39851087ed81') with the granted users.
```

### 2. Recipient attaches and queries the shared database

```sql
-- Recipient: attach the shared database using the full URL provided by the owner.
-- Using the full URL prevents naming conflicts.
ATTACH 'md:_share/analytics/0a9a026ec5a55946a9de39851087ed81' AS analytics_data;

-- Recipient: switch to the attached database
USE analytics_data;

-- Recipient: query the shared database
SELECT * FROM customer_metrics LIMIT 10;
```

When the share is attached, it creates a read-only reference to the shared database that doesn't consume additional storage for the recipient. Recipients can query the data but cannot modify it.

## Related

- [REVOKE READ ON SHARE](/sql-reference/motherduck-sql-reference/revoke-access/)
- [SHOW grants](/sql-reference/motherduck-sql-reference/access-control/show-grants/) to audit who can read a Share
- [Roles and access control](/concepts/roles-and-access-control/)


---

## 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%2Fgrant-access%2F&page_title=GRANT%20READ%20ON%20SHARE&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.