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