ssl_passphrase_command

ssl_passphrase_command is the PostgreSQL setting that defines the command to obtain passphrases for SSL.

Note

Fact — official short description: “Command to obtain passphrases for SSL.”

Identity

Type , Valuestring: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueConnections and Authentication / SSL: Upstream classification
Latest boot value , Value"": empty string

Lifecycle

Fact	Value
First observed	PG11
Present in	PG11–19 Beta 3
Removed in	No
Introduction commit	`8a3d9425290f` — Add ssl_passphrase_command setting
Commit date	2018-02-26
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG11–19 Beta 3	`""`	—	empty string

How it works

ssl_passphrase_command is an external helper invoked when PostgreSQL must decrypt an SSL file such as an encrypted private key. The helper must write the passphrase to standard output and exit with status zero; PostgreSQL strips one trailing newline from the output.

Within the configured command, %p is replaced by a prompt string that can contain whitespace and therefore must be quoted safely; %% emits a literal percent. The command runs as the PostgreSQL service account, and its environment, path, arguments, output, and error logging must not expose the secret.

It has SIGHUP context, but whether an encrypted key can be replaced during reload also depends on ssl_passphrase_command_supports_reload. A noninteractive keychain/file helper can support reload; a TTY prompt is normally suitable only for controlled startup, and Windows has additional reload requirements.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
OLTP	Use an absolute-path, minimal, noninteractive helper backed by a protected keychain or file descriptor. Test exact stdout, exit status, %p quoting, timeout/failure, startup, reload, and failover-node availability without logging the passphrase.
OLAP	Use the identical helper and secret source on analytical nodes; workload class does not change the private-key trust requirement. Test unattended restart before scheduling certificate rotation.
Small nodes	Prefer the simplest auditable helper that can restart unattended. If a TTY prompt is retained, document that reload cannot replace an encrypted key unless supports_reload is safely enabled.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG11–19 Beta 3 unmodified; OLAP: PG11–19 Beta 3 unmodified; CRIT: PG11–19 Beta 3 unmodified; TINY: PG11–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Printing anything except the passphrase to standard output or returning a nonzero status.
Failing to quote %p even though the substituted prompt can contain whitespace, or forgetting that %% is required for a literal percent.
Exposing the passphrase through command arguments, process listings, environment variables, shell tracing, stderr, or server logs.
Deploying a helper that works interactively on one primary but fails during unattended restart, reload, or failover.

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version