Secrets manager（密钥管理器）为所有使用密钥的后端提供了一个统一的用户界面。密钥可以设定作用域，因此不同的存储前缀可以使用不同的密钥，例如，这允许在单个查询中连接来自不同组织的数据。密钥也可以持久化，这样就不需要在每次启动 DuckDB 时都重新指定它们。

警告：持久化密钥以未加密的二进制格式存储在磁盘上。

密钥类型

密钥是有类型的，其类型标识了它们所对应的服务。大多数密钥并未包含在 DuckDB 的默认配置中，而是由扩展程序进行注册。目前支持以下密钥类型：

对于每种类型，都有一个或多个“密钥提供程序”（secret providers），用于指定密钥的创建方式。密钥还可以有一个可选的作用域，即密钥所适用的文件路径前缀。当为某个路径获取密钥时，系统会将密钥作用域与该路径进行比较，并返回与该路径匹配的密钥。如果存在多个匹配的密钥，则选择最长前缀的那个。

创建密钥

可以使用 CREATE SECRET SQL 语句来创建密钥。密钥可以是临时的或持久化的。默认使用临时密钥——它们存储在内存中，生命周期与 DuckDB 实例相同，这与之前的设置方式类似。持久化密钥以未加密的二进制格式存储在 ~/.duckdb/stored_secrets 目录中。当 DuckDB 启动时，会自动从该目录读取并加载持久化密钥。

密钥提供程序

要创建密钥，需要使用一个密钥提供程序。密钥提供程序是生成密钥的机制。为了说明这一点，对于 S3、GCS、R2 和 AZURE 密钥类型，DuckDB 目前支持两种提供程序：CONFIG 和 credential_chain。CONFIG 提供程序要求用户将所有配置信息传入 CREATE SECRET 语句，而 credential_chain 提供程序会自动尝试获取凭据。如果不指定密钥提供程序，则默认使用 CONFIG。有关使用不同提供程序创建密钥的更多详细信息，请查看 httpfs 和 azure 的相关页面。

临时密钥

要创建一个用于访问 S3 的临时无作用域密钥，现在可以使用以下命令：

CREATE SECRET my_secret (
    TYPE s3,
    KEY_ID 'my_secret_key',
    SECRET 'my_secret_value',
    REGION 'my_region'
);

请注意，这里隐含使用了默认的 CONFIG 密钥提供程序。

持久化密钥

为了在不同的 DuckDB 数据库实例之间持久化密钥，现在可以使用 CREATE PERSISTENT SECRET 命令，例如：

CREATE PERSISTENT SECRET my_persistent_secret (
    TYPE s3,
    KEY_ID 'my_secret_key',
    SECRET 'my_secret_value'
);

默认情况下，这将把密钥（未加密）写入 ~/.duckdb/stored_secrets 目录。要更改密钥目录，请执行：

SET secret_directory = 'path/to/my_secrets_dir';

请注意，设置 home_directory 配置选项的值对密钥的存储位置没有影响。

删除密钥

可以使用 DROP SECRET 语句删除密钥，例如：

DROP PERSISTENT SECRET my_persistent_secret;

为同一服务类型创建多个密钥

如果某种服务类型存在两个密钥，则可以使用作用域来决定使用哪一个。例如：

CREATE SECRET secret1 (
    TYPE s3,
    KEY_ID 'my_secret_key1',
    SECRET 'my_secret_value1',
    SCOPE 's3://my-bucket'
);

CREATE SECRET secret2 (
    TYPE s3,
    KEY_ID 'my_secret_key2',
    SECRET 'my_secret_value2',
    SCOPE 's3://my-other-bucket'
);

现在，如果用户查询 s3://⟨my-other-bucket⟩/something，系统会自动为该请求选择 secret2。要查看当前正在使用的密钥，可以使用 which_secret 标量函数，它接受路径和密钥类型作为参数：

FROM which_secret('s3://my-other-bucket/file.parquet', 's3');

列出密钥

可以使用内置的表生成函数来列出密钥，例如使用 duckdb_secrets() 表函数：

FROM duckdb_secrets();

敏感信息将被脱敏处理。