# GRANT READ ON DIVE


> Choose which users, roles, or your whole organization can open a Dive, and list or revoke that access.

Gives users, roles, or your whole organization access to open a [Dive](/key-tasks/dives). `REVOKE READ ON DIVE` removes access, and `SHOW GRANTS ON DIVE` lists it. These statements are the SQL equivalent of the [Share dialog](/key-tasks/dives/#choose-who-can-open-a-dive) in the MotherDuck UI.

:::note
A Dive's owner can always open it and can grant or revoke `read` on it. Organization Admins can grant, revoke, and list `read` on any Dive in the organization.
:::

## Syntax

```sql
GRANT READ ON DIVE '<dive_id>' TO { USER <username> | ROLE <role_name> | ORGANIZATION } [, ...];

REVOKE READ ON DIVE '<dive_id>' FROM { USER <username> | ROLE <role_name> | ORGANIZATION } [, ...];

SHOW GRANTS ON DIVE '<dive_id>';
```

## Parameters

| Parameter | Description |
|---|---|
| `<dive_id>` | The Dive's ID, as a single-quoted string. Dive titles aren't accepted. Find IDs with `SELECT id, title FROM MD_LIST_DIVES();`, which lists only Dives you own. To include Dives shared with you, use `MD_LIST_DIVES(include_org_shares := true)`. Admins can copy the ID of a Dive they can't open from the **All, including unshared** view on the Dives page, using **Copy Dive ID** in its row menu. |
| `USER <username>` | A MotherDuck username, not an email address. Double-quote names that contain special characters, such as `@`. |
| `ROLE <role_name>` | A [role](/concepts/security-and-access/roles-and-access-control/), including the preset `admin`, `builder`, and `explorer` roles. The grant reaches the role's members, including people who join the role later, and anyone holding a role that inherits it. Preset roles nest: Admin is a member of Builder, and Builder of Explorer, so `ROLE explorer` also reaches every Builder and Admin. |
| `ORGANIZATION` | Everyone in your organization, including people who join later and service accounts. |

`READ` is the only permission a Dive supports. Grantees must be typed: a bare name without `USER` or `ROLE` is a syntax error.

## What a `read` grant allows

A grantee can open the Dive and interact with it. The grant covers the Dive itself, not what it reads or runs:

- **Data:** the Dive's queries run with the viewer's own access. A viewer who can't read a database or share the Dive queries sees errors or empty results. Share the data separately, for example with [`share_dive_data`](/sql-reference/mcp/dives/share-dive-data) or a [share granted to the same role](/key-tasks/managing-organizations/managing-roles/#grant-data-access-to-a-role).
- **Flights:** a `read` grant doesn't let a viewer run the Dive's [Flights](/key-tasks/dives/run-flights-from-dives). Each Flight needs its own [`GRANT RUN ON FLIGHT`](/sql-reference/motherduck-sql-reference/flights/grant-run-on-flight).

Revoking `read` on a Dive leaves the viewer's access to its data and Flights unchanged.

## Behavior

- **Dives start private.** A Dive has no grants when it's created, so only its owner can open it. Older Dives keep their original grants, which usually include an `ORGANIZATION` grant. Revoke it to make an older Dive private to its owner.
- **One statement, all or nothing.** If any grantee doesn't exist, the statement fails and nothing is granted.
- **Idempotent.** Granting an existing grant or revoking an absent one succeeds and changes nothing.
- **Case-insensitive names.** Usernames, role names, and keywords match regardless of case.
- **Grants follow the Dive.** Deleting a Dive deletes its grants.

## Output of `SHOW GRANTS ON DIVE`

| Column | Description |
|---|---|
| `grantee_name` | The username or role name. For an organization grant, the organization's name. |
| `grantee_type` | `user`, `role`, or `organization`. |
| `privilege` | `read`. |

Anyone who can open the Dive can list its grants. Only the owner and organization Admins see grantee names. Others get `NULL` in `grantee_name`, as does an owner using a read-only token. For a Dive you can't open, the statement fails with the same error as for a Dive that doesn't exist.

Rows are sorted by `grantee_type`, then `grantee_name`. The same rows are available as a table function, [`MD_LIST_DIVE_GRANTEES`](/sql-reference/motherduck-sql-reference/dives/md-list-dive-grantees), which you can use in joins and subqueries.

## Examples

Make a Dive private by removing the organization grant:

```sql
REVOKE READ ON DIVE '80000000-0000-4000-8000-000000000001' FROM ORGANIZATION;
```

Share it with the `finance` role and one user:

```sql
GRANT READ ON DIVE '80000000-0000-4000-8000-000000000001' TO ROLE finance, USER duck;
```

List who can open the Dive:

```sql
SHOW GRANTS ON DIVE '80000000-0000-4000-8000-000000000001';
```

```text
┌──────────────┬──────────────┬───────────┐
│ grantee_name │ grantee_type │ privilege │
├──────────────┼──────────────┼───────────┤
│ finance      │ role         │ read      │
│ duck         │ user         │ read      │
└──────────────┴──────────────┴───────────┘
```

Share it with everyone in the organization again:

```sql
GRANT READ ON DIVE '80000000-0000-4000-8000-000000000001' TO ORGANIZATION;
```

## Errors

| Error | Cause |
|---|---|
| `Dive id must be a UUID, got '<value>'` | The statement names the Dive rather than its ID. |
| `Could not find Dive` | No Dive with that ID exists in your organization, or you don't own it and aren't an Admin. |
| `Permission '<name>' is not supported on a Dive` | A permission other than `READ`, such as `RUN`. |
| `expected USER <name>, ROLE <name> or ORGANIZATION, got <name>` | A grantee without `USER` or `ROLE` in front of it. |
| `Unable to find user <name>` or `Unable to find role <name>` | The grantee doesn't exist. Usernames aren't email addresses. |
| `Read-only credentials cannot change grants` | The connection uses a read-only token. |

## Related

- [Choose who can open a Dive](/key-tasks/dives/#choose-who-can-open-a-dive): the same access in the MotherDuck UI.
- [`MD_LIST_DIVE_GRANTEES`](/sql-reference/motherduck-sql-reference/dives/md-list-dive-grantees): the grants as a table function.
- [`grant_access` MCP tool](/sql-reference/mcp/flights/grant-access): the AI-agent equivalent.
- [`GRANT RUN ON FLIGHT`](/sql-reference/motherduck-sql-reference/flights/grant-run-on-flight): let viewers run a Dive's Flights.
- [Roles and access control](/concepts/security-and-access/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%2Fdives%2Fgrant-read-on-dive%2F&page_title=GRANT%20READ%20ON%20DIVE&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.