This is the multi-page printable view of this section. .
File Locations
- 1: config_file
- 2: data_directory
- 3: extension_destdir
- 4: external_pid_file
- 5: hba_file
- 6: hosts_file
- 7: ident_file
Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.
1 - config_file
Fact — official short description: “Sets the server’s main configuration file.”
Identity
Type,- Upstream pg_settings type
Context,- Requires a server restart
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- not set
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG9.0–19 Beta 3 | — | — | not set |
How it works
Sets the server’s main configuration file. The value is fixed when the server starts, so changing it requires a restart.
PostgreSQL determines this path before reading the main configuration, so config_file itself can only be supplied on the postgres command line. Includes are resolved by the chosen configuration, while data_directory may point somewhere else.
Monitor and change config_file together with allow_alter_system, data_directory, hba_file. Validate on the relevant server role and real workload, then use its postmaster context to choose session change, reload, or restart; a historical boot default is not the current effective value.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | config_file is deployment topology, not workload tuning. Use an absolute path, least privilege, and atomic configuration rollout; verify access as the postgres service account before restart/reload. |
| OLAP | Follow the OLTP rule, and for separate mounts also verify boot ordering, backup coverage, and path consistency on failover nodes. |
| Small nodes | The default co-located layout is simplest. Split paths only for a concrete backup, packaging, or permission-isolation benefit. |
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 | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 unmodified; OLAP: PG9.0–19 Beta 3 unmodified; CRIT: PG9.0–19 Beta 3 unmodified; TINY: PG9.0–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Missing directory traversal, read, or write permission for the service account.
- Confusing restart requirements for a path with reload behavior of the selected file contents.
- Omitting the path on a failover node or from backup inventory.
- Using a relative path that depends on an unstable working directory.
Related parameters
allow_alter_system · data_directory · hba_file · ident_file · external_pid_file · extension_destdir
References
2 - data_directory
Fact — official short description: “Sets the server’s data directory.”
Identity
Type,- Upstream pg_settings type
Context,- Requires a server restart
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- not set
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG9.0–19 Beta 3 | — | — | not set |
How it works
Sets the server’s data directory. The value is fixed when the server starts, so changing it requires a restart.
This selects the cluster storage directory and overrides -D or PGDATA for data placement, but it does not relocate the already selected configuration files. Moving a cluster requires a coordinated shutdown and filesystem operation; changing only the string cannot move data.
Monitor and change data_directory together with allow_alter_system, config_file, hba_file. Validate on the relevant server role and real workload, then use its postmaster context to choose session change, reload, or restart; a historical boot default is not the current effective value.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | data_directory is deployment topology, not workload tuning. Use an absolute path, least privilege, and atomic configuration rollout; verify access as the postgres service account before restart/reload. |
| OLAP | Follow the OLTP rule, and for separate mounts also verify boot ordering, backup coverage, and path consistency on failover nodes. |
| Small nodes | The default co-located layout is simplest. Split paths only for a concrete backup, packaging, or permission-isolation benefit. |
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 | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 unmodified; OLAP: PG9.0–19 Beta 3 unmodified; CRIT: PG9.0–19 Beta 3 unmodified; TINY: PG9.0–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Missing directory traversal, read, or write permission for the service account.
- Confusing restart requirements for a path with reload behavior of the selected file contents.
- Omitting the path on a failover node or from backup inventory.
- Using a relative path that depends on an unstable working directory.
Related parameters
allow_alter_system · config_file · hba_file · ident_file · external_pid_file · extension_destdir
References
3 - extension_destdir
Fact — measured pg_settings description: “Path to prepend for extension loading.”
Identity
Type,- Measured downstream pg_settings type
Context,- Settable at runtime by a superuser
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Measured downstream classification
Latest boot value,- empty string
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG9.5 |
| Present in | PG9.5–17 |
| Removed in | PG18 |
| Introduction commit | Debian/PGDG downstream patch — Debian-specific extension_destdir patch used for extension build-time testing |
| Commit date | — |
| Discussion | downstream documentation |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG9.5–17 | "" |
— | empty string |
How it works
The version matrix proves that extension_destdir is exposed by the measured Debian/PGDG binaries from PG9.5 through PG17. An exhaustive upstream GUC-source pickaxe has no introduction commit because the name comes from Debian’s extension_destdir package patch, not the PostgreSQL source tree.
The patch prepends a DESTDIR-like staging root when the server locates extension control and SQL files and the modules behind functions. Debian’s pg_virtualenv uses it to test a package before its files are installed in their final system paths; it was explicitly a packaging and build-time facility, not a general production extension search path.
From PostgreSQL 18, use the upstream extension_control_path for control and SQL files together with dynamic_library_path for shared libraries, or install the extension in standard locations. Remove extension_destdir from every config file, ALTER SYSTEM layer, role/database setting, and generated template before starting the newer server.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | Treat this as downstream migration debt, not a tuning control. Package extensions in supported locations, test extension_control_path and dynamic_library_path under the service account, and remove the obsolete key before the PostgreSQL 18 upgrade. |
| OLAP | Apply the same migration to ETL and analytical extension stacks, including worker processes and standbys. Rehearse CREATE EXTENSION, ALTER EXTENSION UPDATE, restore, and failover with the final filesystem layout. |
| Small nodes | Prefer standard package locations. A one-node system gains little from recreating a Debian build-time staging mechanism, while an unknown GUC can prevent a modern server from starting. |
Pigsty
Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG17; 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 | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.5–17 unmodified; OLAP: PG9.5–17 unmodified; CRIT: PG9.5–17 unmodified; TINY: PG9.5–17 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Calling extension_destdir an upstream PostgreSQL parameter or assigning it an upstream introduction commit.
- Continuing to emit the downstream name on PostgreSQL 18 or later, where the measured packages no longer recognize it.
- Migrating extension control files but forgetting the shared-library half of the path design.
- Testing as a build user while the database service account cannot read the final directories, files, or parent paths.
Related parameters
extension_control_path · dynamic_library_path · shared_preload_libraries · session_preload_libraries · config_file
References
4 - external_pid_file
Fact — official short description: “Writes the postmaster PID to the specified file.”
Identity
Type,- Upstream pg_settings type
Context,- Requires a server restart
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- not set
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG9.0–19 Beta 3 | — | — | not set |
How it works
Writes the postmaster PID to the specified file. The value is fixed when the server starts, so changing it requires a restart.
At startup PostgreSQL writes the postmaster PID to this additional path for external service tooling. postmaster.pid in the data directory remains authoritative for server internals, and the external file must not be used as the sole proof that a process is the intended cluster.
Monitor and change external_pid_file together with allow_alter_system, config_file, data_directory. Validate on the relevant server role and real workload, then use its postmaster context to choose session change, reload, or restart; a historical boot default is not the current effective value.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | external_pid_file is deployment topology, not workload tuning. Use an absolute path, least privilege, and atomic configuration rollout; verify access as the postgres service account before restart/reload. |
| OLAP | Follow the OLTP rule, and for separate mounts also verify boot ordering, backup coverage, and path consistency on failover nodes. |
| Small nodes | The default co-located layout is simplest. Split paths only for a concrete backup, packaging, or permission-isolation benefit. |
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 | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 unmodified; OLAP: PG9.0–19 Beta 3 unmodified; CRIT: PG9.0–19 Beta 3 unmodified; TINY: PG9.0–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Missing directory traversal, read, or write permission for the service account.
- Confusing restart requirements for a path with reload behavior of the selected file contents.
- Omitting the path on a failover node or from backup inventory.
- Using a relative path that depends on an unstable working directory.
Related parameters
allow_alter_system · config_file · data_directory · hba_file · ident_file · extension_destdir
References
5 - hba_file
Fact — official short description: “Sets the server’s “hba” configuration file.”
Identity
Type,- Upstream pg_settings type
Context,- Requires a server restart
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- not set
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG9.0–19 Beta 3 | — | — | not set |
How it works
Sets the server’s “hba” configuration file. The value is fixed when the server starts, so changing it requires a restart.
This path selects pg_hba.conf. The path setting is fixed at startup, while edits to the selected file take effect after reload and should be checked with pg_hba_file_rules before relying on them.
Monitor and change hba_file together with allow_alter_system, config_file, data_directory. Validate on the relevant server role and real workload, then use its postmaster context to choose session change, reload, or restart; a historical boot default is not the current effective value.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | hba_file is deployment topology, not workload tuning. Use an absolute path, least privilege, and atomic configuration rollout; verify access as the postgres service account before restart/reload. |
| OLAP | Follow the OLTP rule, and for separate mounts also verify boot ordering, backup coverage, and path consistency on failover nodes. |
| Small nodes | The default co-located layout is simplest. Split paths only for a concrete backup, packaging, or permission-isolation benefit. |
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 | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 unmodified; OLAP: PG9.0–19 Beta 3 unmodified; CRIT: PG9.0–19 Beta 3 unmodified; TINY: PG9.0–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Missing directory traversal, read, or write permission for the service account.
- Confusing restart requirements for a path with reload behavior of the selected file contents.
- Omitting the path on a failover node or from backup inventory.
- Using a relative path that depends on an unstable working directory.
Related parameters
allow_alter_system · config_file · data_directory · ident_file · external_pid_file · extension_destdir
References
6 - hosts_file
Fact — official short description: “Sets the server’s “hosts” configuration file.”
Identity
Type,- Upstream pg_settings type
Context,- Requires a server restart
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- not set
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG19 Beta 3 |
| Present in | PG19 Beta 3 |
| Removed in | No |
| Introduction commit | 4f433025f666 — ssl: Serverside SNI support for libpq |
| Commit date | 2026-03-18 |
| Discussion | thread 1 |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG19 Beta 3 | — | — | not set |
How it works
PostgreSQL describes hosts_file as follows: “Sets the server’s “hosts” configuration file.” The value is fixed when the server starts, so changing it requires a controlled restart. The atlas measures it in PG19 Beta 3; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.
The path identifies pg_hosts.conf, the server-side SNI mapping file introduced in PostgreSQL 19. When ssl_sni is enabled, hostname, /no_sni/, and wildcard entries select certificate, key, optional CA, and optional passphrase commands; an empty or missing file falls back to the ordinary postgresql.conf TLS files.
Read it together with ssl_sni, ssl_cert_file, ssl_key_file, ssl_ca_file. Check SHOW and pg_settings on the target server, verify the source and pending_restart fields, and compare workload, logs, and resource metrics before and after any change.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | Roll out through staged clients, validate certificate selection and expiry warnings, and monitor authentication failures. Keep a tested fallback and treat file permissions and secret rotation as part of the same change. |
| OLAP | Apply the same security policy to batch drivers and long-lived ETL connections. Test clients that omit SNI, credential-expiry automation, reload behavior, and certificate-chain compatibility. |
| Small nodes | Prefer a simple, documented TLS and credential policy. Do not enable multi-certificate routing without a test for every hostname and fallback path, and never weaken verification to hide configuration mistakes. |
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 | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG19 Beta 3 unmodified; OLAP: PG19 Beta 3 unmodified; CRIT: PG19 Beta 3 unmodified; TINY: PG19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Treating the measured boot_val for hosts_file as proof of the effective value on an initialized or managed cluster.
- Applying a change as though it were immediate while pg_settings reports postmaster context.
- Changing this setting in isolation without checking the linked limits, observability, and rollback path.
- Depending on beta behavior in production without retesting the PostgreSQL 19 final release.
Related parameters
ssl_sni · ssl_cert_file · ssl_key_file · ssl_ca_file · hba_file
References
7 - ident_file
Fact — official short description: “Sets the server’s “ident” configuration file.”
Identity
Type,- Upstream pg_settings type
Context,- Requires a server restart
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- not set
Lifecycle
| Fact | Value |
|---|---|
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |
Default history
| Versions | Raw boot_val |
Unit | Human value |
|---|---|---|---|
| PG9.0–19 Beta 3 | — | — | not set |
How it works
Sets the server’s “ident” configuration file. The value is fixed when the server starts, so changing it requires a restart.
This path selects pg_ident.conf, whose maps translate authenticated operating-system or certificate names to database roles. The path is fixed at startup; contents are re-read on reload and only matter to authentication methods that name a map.
Monitor and change ident_file together with allow_alter_system, config_file, data_directory. Validate on the relevant server role and real workload, then use its postmaster context to choose session change, reload, or restart; a historical boot default is not the current effective value.
Tuning advice
Advice. These are workload-specific starting points and must be validated with measurements.
| Workload | Guidance |
|---|---|
| OLTP | ident_file is deployment topology, not workload tuning. Use an absolute path, least privilege, and atomic configuration rollout; verify access as the postgres service account before restart/reload. |
| OLAP | Follow the OLTP rule, and for separate mounts also verify boot ordering, backup coverage, and path consistency on failover nodes. |
| Small nodes | The default co-located layout is simplest. Split paths only for a concrete backup, packaging, or permission-isolation benefit. |
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 | — | — |
Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 unmodified; OLAP: PG9.0–19 Beta 3 unmodified; CRIT: PG9.0–19 Beta 3 unmodified; TINY: PG9.0–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.
Common pitfalls
- Missing directory traversal, read, or write permission for the service account.
- Confusing restart requirements for a path with reload behavior of the selected file contents.
- Omitting the path on a failover node or from backup inventory.
- Using a relative path that depends on an unstable working directory.
Related parameters
allow_alter_system · config_file · data_directory · hba_file · external_pid_file · extension_destdir