# 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 {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `string` | Upstream pg_settings type |
| Context | `sighup` | Takes effect after configuration reload |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Connections and Authentication / SSL | Upstream classification |
| Latest boot value | `""` | empty string |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG11 |
| Present in | PG11–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`8a3d9425290f`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=8a3d9425290ff5f6434990349886afae9e1c6008) — Add ssl_passphrase_command setting |
| Commit date | 2018-02-26 |
| Discussion | — |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG11–19 Beta 3 | `""` | — | empty string |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.full-width}

## Pigsty {#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 | — | — |
{.full-width}

> [!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 {#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.

## Related parameters {#related-parameters}

[`ssl`](/parameters/ssl/) · [`ssl_cert_file`](/parameters/ssl-cert-file/) · [`ssl_key_file`](/parameters/ssl-key-file/) · [`ssl_ca_file`](/parameters/ssl-ca-file/) · [`ssl_crl_file`](/parameters/ssl-crl-file/) · [`ssl_min_protocol_version`](/parameters/ssl-min-protocol-version/)

## References {#references}

- [PostgreSQL 19 Beta 3 — ssl_passphrase_command](https://www.postgresql.org/docs/19/runtime-config-connection.html#GUC-SSL-PASSPHRASE-COMMAND)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)