Search Shortcut cmd + k | ctrl + k

secret_vault

Encrypted local storage for persistent secrets: a drop-in SecretStorage (local_encrypted) that writes AES-256-GCM ciphertext instead of plaintext, with keyring/passphrase/env key providers, migration, rotation, and one-time-envelope export/import

Maintainer(s): robert-guangzhou, xiehuiqiang

Compatibility Matrix

This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

Platform 1.4.4 1.4.5 1.5.5 1.5.6 2.0.0
Linux AMD64
Linux ARM64
macOS AMD64
macOS ARM64
Windows AMD64
Windows ARM64
WebAssembly

Installing and Loading

INSTALL secret_vault FROM community;
LOAD secret_vault;

Example

INSTALL secret_vault FROM community;
LOAD secret_vault;

-- choose where the encryption key lives (keyring | passphrase | env)
SET secret_vault_provider = 'env';        -- e.g. SECRET_VAULT_KEY injected by your scheduler

-- persistent secrets are now written encrypted (DSVLT + AES-256-GCM)
CREATE PERSISTENT SECRET my_s3 IN local_encrypted (
    TYPE s3, KEY_ID 'AKIA...', SECRET 'shhh', REGION 'us-east-1');

SELECT name, storage, secret_string FROM duckdb_secrets();
-- my_s3 | local_encrypted | ... secret=redacted ...

About secret_vault

DuckDB stores persistent secrets on disk in unencrypted binary form (~/.duckdb/stored_secrets). secret_vault registers an alternative storage, local_encrypted, that writes every secret as AES-256-GCM ciphertext with a per-file random nonce and an AEAD tag bound to the secret name (rename/tamper fails loudly). Files keep 600 permissions; the key never touches disk:

  • keyring (default): a random 256-bit master key in the OS keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service), generated on first use.
  • passphrase: Argon2id (64 MiB, t=3) with a per-file random salt.
  • env: a base64 32-byte key injected per run for schedulers/CI.

Also ships secret_vault_status(), secret_vault_migrate() (plaintext local_file secrets -> encrypted, conflict-safe), secret_vault_rotate() (re-encrypt everything under a new provider/key), and one-time encrypted envelopes (secret_vault_export/import) to move secrets between instances without ever putting a key in the environment: the envelope is sealed under a single-use 256-bit transport code (base32, entered via stdin), and the importing instance re-encrypts with its own local key. Works with any secret type (s3, mysql, postgres, nats_rw, …) because it encrypts DuckDB's own serialization blob.

Threat model, key-generation guide and dev/repin docs live in the repo's docs/ directory.

Added Functions

function_name function_type description comment examples
secret_vault_export table NULL NULL  
secret_vault_import table NULL NULL  
secret_vault_migrate table NULL NULL  
secret_vault_reload table NULL NULL  
secret_vault_rotate table NULL NULL  
secret_vault_status table NULL NULL  
secret_vault_version scalar NULL NULL  

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings

name description input_type scope aliases typed_value
secret_vault_directory Directory for local_encrypted secret files (changeable only while storage is empty) VARCHAR GLOBAL [] /home/runner/.duckdb/stored_secrets_vault
secret_vault_provider Key provider for the local_encrypted secret storage: keyring | passphrase | env VARCHAR GLOBAL [] keyring
temp_directory Set the directory to which temporary files are written. VARCHAR GLOBAL [] post.db.tmp
© 2026 DuckDB Foundation, Amsterdam NL
DuckDB Home Code of Conduct Trademark Use Blog