Skip to main content
Early access Enterprise SQL runs in LanceDB Enterprise. A Secret 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 -:
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

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

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

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

Returns two non-null string columns: namespace_path, a compact JSON array of parent namespace components ([] for root), and name, the unqualified object name. Omitting IN lists all authorized namespaces in the current database; IN team$ml selects that exact path without a database qualifier; IN public selects the current database’s root. Listings require the relevant database and namespace USAGE privileges. Secret listings contain no values or Secret metadata. Page through results using LIMIT n [FROM '<page-token>']. Read the opaque lancedb.next_page_token from the Arrow result schema metadata and pass it back unchanged with the same object type and scope. Stop when no token is returned; a short or empty page can still carry a continuation. See catalog listing pagination.

DESCRIBE SECRET

Returns one row: A missing Secret is an error. Requires USAGE on the Secret.

GRANT and REVOKE

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

What to read next

Secret

Create, rotate, list and drop the credential from the Python SDK and SQL.

Privileges

Every object’s privileges, and how grants resolve.