GUC Reference

All parameters live in the pg_vault_tde namespace. Parameters marked suset can be changed by a superuser at any time — at session level, or scoped to one database with ALTER DATABASE ... SET / one role with ALTER ROLE ... SET — and take effect for new connections with no server restart. Parameters marked postmaster require a full server restart (postgresql.conf or ALTER SYSTEM, then restart).

Parameters holding secrets (vault_token, vault_role_id, vault_secret_id, wallet_dev_mode_passphrase) are hidden from non-superusers in pg_settings and excluded from configuration file samples.

General

Parameter Type Default Context Description
enabled boolean on postmaster Master switch for AES-256-GCM encryption on encrypted_heap tables. Fixed at server startup — see the warning in Encrypted Tables and Indexes about why this can never be safely toggled on a database with existing encrypted data.
crypto_provider string '' postmaster OpenSSL 3.x provider name for hardware crypto offload. Empty (default) uses built-in AES-NI/ARM CE auto-dispatch; set to qatprovider for Intel QAT, fips for FIPS mode.
max_encrypted_relations integer 1024 postmaster Maximum number of independently-keyed encrypted_heap relations in the shared-memory DEK cache (range 64–65536). Increase if you have more than 1024 encrypted tables.
dek_cache_ttl integer 0 suset Per-backend DEK cache time-to-live in seconds (range 0–86400). 0 = no expiry. When set, each backend re-reads the DEK from shared memory after this interval, even without a rotation.
allow_plaintext_index boolean off suset When off (default), CREATE INDEX/CREATE UNIQUE INDEX with a non-tde_btree access method (btree, gin, gist, hash, brin) against an encrypted_heap table is rejected with ERROR. When on, allowed after a WARNING — the indexed value is then stored in plaintext on disk in that index. Does not affect PRIMARY KEY/UNIQUE table constraints, which always warn-and-allow regardless — see Encrypted Tables and Indexes.

KMS Provider Selection

Parameter Type Default Context Description
kms_provider string '' (unset — must be configured) suset Active KMS backend: vault, local, or pkcs11. The empty string is a valid, intentional value meaning “not yet configured” — there is no built-in default provider. Settable per-database.

HashiCorp Vault / OpenBao (kms_provider = 'vault')

All suset, superuser-only in pg_settings, settable per-database.

Parameter Type Default Description
vault_url string '' Vault/OpenBao base URL (e.g. https://vault.example.com:8200)
vault_namespace string '' Vault Enterprise namespace; leave empty for Community Edition
vault_auth_method string token Authentication method: token, approle, or kubernetes
vault_token string '' Auth token for the token method — hidden from pg_settings
vault_role_id string '' AppRole role_id — hidden from pg_settings
vault_secret_id string '' AppRole secret_id — hidden from pg_settings
vault_role_name string '' AppRole role name; when set, the used secret_id is destroyed after a successful login (single-use pattern)
vault_k8s_role string '' Kubernetes auth role name
vault_k8s_mount string kubernetes Kubernetes auth engine mount path
vault_transit_mount string transit Transit secrets engine mount path
vault_key_name string pg-tde-dek Transit key name used for DEK wrapping; override per-database to isolate tenant keys
vault_ca_cert string '' Path to CA bundle for Vault TLS verification
vault_timeout_ms integer 5000 Vault HTTP timeout in ms, range 0–300000 (0 = no timeout)

Background Worker (Vault Token Renewal)

Parameter Type Default Context Description
bgw_enabled boolean off suset Enables the background worker that periodically renews the Vault token — only useful with the approle/kubernetes auth methods. The worker is registered once, at postmaster startup: changing this GUC afterward (even via pg_reload_conf()) updates the stored value but does not start or stop the worker — a full restart is required for the change to take practical effect.
token_renewal_interval integer 3600 suset Token renewal interval in seconds, range 60–86400. Ignored if bgw_enabled = off.

Local Wallet (kms_provider = 'local')

Parameter Type Default Context Description
wallet_path string '' (resolves at runtime to /var/lib/pg_vault_tde/<DB_OID>/wallet.p12) suset Absolute path to the PKCS#12 wallet file. SHOW always returns the effective path, even when this is unset in postgresql.conf.
wallet_passphrase_env string '' suset Name of the environment variable holding the wallet passphrase — never the passphrase value itself
wallet_passphrase_file string '' suset Path to a file containing the passphrase; the file must be mode 0400 or 0600
wallet_passphrase_command string '' suset Shell command whose stdout is the passphrase (highest priority of the three ingestion methods; analogous to ssl_passphrase_command)
wallet_auto_open boolean on suset Auto-open the wallet during startup if a passphrase is available via one of the above; if off, opening is deferred until first access
dev_mode boolean off suset Enables development-only conveniences. Never set on in production.
wallet_dev_mode_passphrase string '' suset Inline plaintext passphrase, used only when dev_mode = on; emits a WARNING on every use — hidden from pg_settings

Passphrase source priority when more than one is configured: wallet_passphrase_command > wallet_passphrase_file > wallet_passphrase_env.

PKCS#11 / HSM (kms_provider = 'pkcs11')

All suset, superuser-only in pg_settings, settable per-database.

Parameter Type Default Description
pkcs11_library string '' Absolute path to the vendor’s PKCS#11 module (.so), e.g. /usr/lib/softhsm/libsofthsm2.so
pkcs11_token_label string '' Token label for slot discovery; preferred over pkcs11_slot_id
pkcs11_slot_id integer -1 Explicit slot ID, used only when pkcs11_token_label is empty (-1 = unset); range -1–INT_MAX
pkcs11_pin_env string PG_TDE_PKCS11_PIN Name of the environment variable holding the token user PIN — never the PIN itself
pkcs11_key_label string pg_vault_tde_kek CKA_LABEL of the AES-256 KEK object on the token

TOAST and Logical Replication

Parameter Type Default Context Description
toast_encryption boolean on suset Encrypts TOAST chunks for encrypted_heap tables using the parent relation’s DEK. Set off only for debugging or migration — see Encrypted Tables and Indexes.
toast_custom_rmgr boolean off postmaster Enables the custom WAL resource manager that lets encrypted TOAST chunks be published over logical replication. Requires pg_vault_tde in shared_preload_libraries (already true) and a full restart — see Logical Replication.

See Also