本页尚未翻译

本页内容仍为英文原文，源自官方文档 sql/ddl/secret。中文翻译正在分批进行中。

Secret

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

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

api_key
platform.`model-api-key`
analytics.`ml$vision`.`model-api-key`

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

CREATE SECRET platform.`model-api-key` TYPE = GENERIC_STRING SECRET_STRING = '<api-key>'
CREATE SECRET IF NOT EXISTS api_key TYPE = GENERIC_STRING SECRET_STRING = $$<api-key>$$

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:

db.execute_query(
    "CREATE SECRET platform.`model-api-key` TYPE = GENERIC_STRING SECRET_STRING = $1",
    parameters=["<api-key>"],
)

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

ALTER SECRET platform.`model-api-key` SET SECRET_STRING = '<api-key>'
ALTER SECRET IF EXISTS api_key SET SECRET_STRING = $$<api-key>$$

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

DROP SECRET platform.`model-api-key`
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.

注意

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

SHOW SECRETS
SHOW SECRETS IN platform
SHOW SECRETS IN analytics.`ml$vision`
SHOW SECRETS IN public
SHOW SECRETS IN platform WHERE name > 'model-api-key' 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

DESCRIBE SECRET platform.`model-api-key`
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

GRANT CREATE SECRET ON SCHEMA platform TO ROLE platform_admins
GRANT USAGE, UPDATE ON SECRET platform.`model-api-key` TO ROLE etl, rotation_service
REVOKE UPDATE ON SECRET platform.`model-api-key` 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 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

SecretCreate, rotate, list and drop the credential from the Python SDK and SQL.PrivilegesEvery object's privileges, and how grants resolve.