> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret

> CREATE, ALTER, DROP, SHOW and DESCRIBE SECRET, and granting privileges on Secrets.

Early access Enterprise [SQL runs in LanceDB Enterprise.](https://docs.lancedb.com/sql.md)

A [Secret](https://docs.lancedb.com/management/secret.md) is a named credential that Functions bind by
reference. These statements store, rotate, list, describe and drop Secrets.

A Secret is addressed like a table: `[db.][namespace.]name`. An unqualified
name uses the session's database and namespace. A nested namespace is one
backtick-quoted name with `$` between its components, and `public` is the
database's root namespace. A Secret name may contain letters, digits, `_`, `.`
and `-`, so quote one that contains `.` or `-`:

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
api_key
platform.`openai-prod`
analytics.`ml$vision`.`openai-prod`
```

`CREATE`, `ALTER` and `DROP` return one row of `operation`, `name` and
`status`. Without `IF [NOT] EXISTS`, a taken name (for `CREATE`) or a missing
Secret (for `ALTER` and `DROP`) is an error rather than a status.

## CREATE SECRET

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
CREATE SECRET platform.`openai-prod` TYPE = GENERIC_STRING SECRET_STRING = 'sk-...'
CREATE SECRET IF NOT EXISTS api_key TYPE = GENERIC_STRING SECRET_STRING = $$sk-...$$
```

Stores a new Secret. `TYPE = GENERIC_STRING` is required; it is currently the
only supported type. The value may be single-quoted or dollar-quoted, or a
bound `$1` parameter -- the same choice `ALTER SECRET` offers below -- so the
value never has to appear in the SQL text itself:

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
db.execute_query(
    "CREATE SECRET platform.`openai-prod` TYPE = GENERIC_STRING SECRET_STRING = $1",
    parameters=["sk-..."],
)
```

Requires `CREATE SECRET` on the namespace; the caller becomes the Secret's
owner.

The status is `created`, or `already_exists` with `IF NOT EXISTS`. It never
overwrites an existing Secret; use `ALTER SECRET`.

## ALTER SECRET

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
ALTER SECRET platform.`openai-prod` SET SECRET_STRING = 'sk-...'
ALTER SECRET IF EXISTS api_key SET SECRET_STRING = $$sk-...$$
```

Replaces the Secret's value -- `SECRET_STRING` takes the same single-quoted,
dollar-quoted, or bound `$1` parameter forms `CREATE SECRET` does. Every
Function bound to it gets the latest value the next time a job starts -- a
job already running, and its retries, keep the value they captured at their
own start -- without a new Function version. Requires `UPDATE` on the
Secret.

The status is `altered`, or `not_found` with `IF EXISTS`.

## DROP SECRET

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
DROP SECRET platform.`openai-prod`
DROP SECRET IF EXISTS api_key
```

Deletes the Secret and every grant on it. Functions bound to it fail at their
next job, naming the Secret. Requires `OWNERSHIP` on the Secret.

The status is `dropped`, or `not_found` with `IF EXISTS`.

> [!WARNING]
>
> `DROP SECRET` cannot be undone. A new Secret created under the same name is
> picked up by every Function still bound to that name.

## SHOW SECRETS

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
SHOW SECRETS
SHOW SECRETS IN platform
SHOW SECRETS IN analytics.`ml$vision`
SHOW SECRETS IN public
SHOW SECRETS IN platform WHERE name > 'openai-prod' LIMIT 50
```

Lists the Secret names in one namespace as a sorted `name` column. Without
`IN`, it lists the session's namespace; `IN public` lists the root. `WHERE
name > '<cursor>'` pages past the last name already seen, and `LIMIT`
bounds the page size; `WHERE` must compare `name` with `>`. Requires
`USAGE` on the database and the namespace.

## DESCRIBE SECRET

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
DESCRIBE SECRET platform.`openai-prod`
DESC SECRET api_key
```

Returns one row:

| Column | Type | Meaning |
| - | - | - |
| `name` | string | The Secret's name |
| `created_at_millis` | int64 | When it was created, in milliseconds since the Unix epoch |
| `updated_at_millis` | int64 | When its value was last set. Watch this change to confirm a rotation landed. |
| `history` | list of struct `{generation: uint64, at_millis: int64}` | Creation and each rotation since, oldest first, up to the most recent 100 |

A missing Secret is an error. Requires `USAGE` on the Secret.

## GRANT and REVOKE

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
GRANT CREATE SECRET ON SCHEMA platform TO ROLE platform_admins
GRANT USAGE, UPDATE ON SECRET platform.`openai-prod` TO ROLE etl, rotation_service
REVOKE UPDATE ON SECRET platform.`openai-prod` FROM ROLE etl
```

`CREATE SECRET` on the containing `SCHEMA` creates one; `OWNERSHIP`, `USAGE`
(bind it to a Function) and `UPDATE` (rotate it) apply to the Secret itself.
See [GRANT and REVOKE](https://docs.lancedb.com/sql/ddl/grant.md) for the full statement grammar, every
target type, and the shared mechanics -- grantee forms, no-op rules, and the
status a statement returns -- which apply the same way to a Secret as to
any other object.

## The value stays out of output

A Secret's value never appears in a statement's result, an error message,
`EXPLAIN` output, or the query log. The query log masks everything after the
name in `CREATE SECRET`, and everything after `SET` in `ALTER SECRET`.

> [!NOTE]
>
> SQL has no syntax for binding a Secret to a Function. Register Functions that
> bind Secrets through the Python SDK; see
> [Vend a Secret to a Function](https://docs.lancedb.com/curation/vend-secret.md).

## What to read next

> [card] [Secret](https://docs.lancedb.com/management/secret.md)
>
> Create, rotate, list and drop the credential from the Python SDK and SQL.

> [card] [Privileges](https://docs.lancedb.com/governance/privileges.md#sql)
>
> Every object's privileges, and how grants resolve.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.