Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Parameters

Complete dossiers for all 447 core PostgreSQL configuration parameters observed from 9.0 through 19 Beta 3.

This section contains all 447 core GUCs in the measured PostgreSQL 9.0–19 Beta 3 union: 419 remain in 19 Beta 3, 28 were removed during the interval, and 240 first appear after 9.0. Every dossier includes identity, lifecycle, default history, mechanism, tuning advice, Pigsty values, pitfalls, related entries, and sources.

Categories

Category Parameters
Client Connection Defaults 47
Connections and Authentication 45
Customized Options 1
Developer Options 27
Error Handling 4
File Locations 7
Lock Management 5
Preset Options 24
Query Tuning 55
Replication 33
Reporting and Logging 47
Resource Usage 51
Statistics 14
Vacuuming 34
Version and Platform Compatibility 12
Write-Ahead Log 41

Boot defaults that changed

These parameters changed boot_val or unit during PostgreSQL 9.0–19 Beta 3:

TimeZone · autovacuum_vacuum_cost_delay · checkpoint_completion_target · default_toast_compression · effective_cache_size · effective_io_concurrency · extra_float_digits · hash_mem_multiplier · hot_standby · jit · krb_server_keyfile · log_autovacuum_min_duration · log_checkpoints · log_connections · log_directory · log_line_prefix · log_lock_waits · log_timezone · maintenance_io_concurrency · maintenance_work_mem · max_locks_per_transaction · max_parallel_workers_per_gather · max_replication_slots · max_wal_senders · max_wal_size · min_wal_size · password_encryption · search_path · server_version · server_version_num · shared_buffers · ssl_ciphers · ssl_min_protocol_version · standard_conforming_strings · timezone_abbreviations · track_activity_query_size · transaction_isolation · vacuum_buffer_usage_limit · vacuum_cost_page_miss · wal_buffers · wal_level · wal_segment_size · wal_sender_delay · work_mem

Removed parameters

These parameters left pg_settings before PostgreSQL 19 Beta 3 and retain historical dossiers:

checkpoint_segments · custom_variable_classes · db_user_namespace · default_with_oids · escape_string_warning · extension_destdir · force_parallel_mode · io_workers · krb_srvname · lc_collate · lc_ctype · min_parallel_relation_size · old_snapshot_threshold · operator_precedence_warning · promote_trigger_file · replacement_sort_tuples · replication_timeout · silent_mode · sql_inheritance · ssl_ecdh_curve · ssl_renegotiation_limit · stats_temp_directory · trace_recovery_messages · unix_socket_directory · vacuum_cleanup_index_scale_factor · vacuum_defer_cleanup_age · wal_keep_segments · wal_sender_delay

1 - Client Connection Defaults

Complete dossiers for 47 core PostgreSQL settings in Client Connection Defaults.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

1.1 - DateStyle

DateStyle is the PostgreSQL setting that defines the display format for date and time values.
Note

Fact — official short description: “Sets the display format for date and time values.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value ValueISO, MDY
ISO, MDY

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 ISO, MDY — ISO, MDY

How it works

DateStyle sets the display format for date and time values. Also controls interpretation of ambiguous date inputs. The value has two independent parts: an output style and a DMY/MDY/YMD field order; the latter also resolves ambiguous input.

DateStyle is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat DateStyle as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin DateStyle for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing DateStyle.

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

  • Changing DateStyle in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Parsing an ambiguous value such as 01/02/03 under an unexpected MDY/DMY order.

Related parameters

IntervalStyle · TimeZone · lc_time · timezone_abbreviations · log_timezone

References

1.2 - IntervalStyle

IntervalStyle is the PostgreSQL setting that defines the display format for interval values.
Note

Fact — official short description: “Sets the display format for interval values.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuepostgres, postgres_verbose, sql_standard, iso_8601
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value Valuepostgres
postgres

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 postgres — postgres

How it works

IntervalStyle sets the display format for interval values. Its four modes target PostgreSQL compatibility, verbose output, SQL-standard literals, or ISO 8601; it can also change how ambiguous interval input is read.

IntervalStyle is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat IntervalStyle as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin IntervalStyle for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing IntervalStyle.

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

  • Changing IntervalStyle in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing IntervalStyle globally without a rollback plan and a client or operational compatibility test.

Related parameters

DateStyle · TimeZone · lc_time · timezone_abbreviations · log_timezone

References

1.3 - TimeZone

TimeZone is the PostgreSQL setting that defines the time zone for displaying and interpreting time stamps.
Note

Fact — official short description: “Sets the time zone for displaying and interpreting time stamps.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value ValueGMT
GMT

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 UNKNOWN — UNKNOWN
PG9.1 — — not set
PG9.2–19 Beta 3 GMT — GMT

How it works

TimeZone sets the time zone for displaying and interpreting time stamps. It affects timestamptz rendering and timestamp input lacking an explicit zone, while the stored instant remains independent of the display zone.

TimeZone is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat TimeZone as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin TimeZone for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing TimeZone.

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

  • Changing TimeZone in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Comparing rendered timestamps without preserving the original instant and explicit zone context.

Related parameters

DateStyle · IntervalStyle · lc_time · timezone_abbreviations · log_timezone

References

1.4 - bytea_output

bytea_output is the PostgreSQL setting that defines the output format for bytea.
Note

Fact — official short description: “Sets the output format for bytea.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueescape, hex
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valuehex
hex

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 hex — hex

How it works

bytea_output sets the output format for bytea. The choice affects textual output only: bytea input accepts both hex and escape syntax regardless of this setting.

bytea_output is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat bytea_output as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin bytea_output for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing bytea_output.

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

  • Changing bytea_output in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing bytea_output globally without a rollback plan and a client or operational compatibility test.

Related parameters

extra_float_digits · xmlbinary · xmloption · client_encoding · DateStyle

References

1.5 - check_function_bodies

check_function_bodies is the PostgreSQL setting that controls whether PostgreSQL checks routine bodies during CREATE FUNCTION and CREATE PROCEDURE.
Note

Fact — official short description: “Check routine bodies during CREATE FUNCTION and CREATE PROCEDURE.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

check_function_bodies checks routine bodies during CREATE FUNCTION and CREATE PROCEDURE. Turning it off suppresses creation-time validation, which is useful for dump restores and forward references but defers errors until execution.

check_function_bodies is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It supplies a default only when SQL omits an explicit choice, so schema migrations, object-level options, privileges, and later ALTER operations can override or outlive it.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep check_function_bodies on for ordinary migrations so invalid routine bodies fail early. Disable it only inside a controlled dump restore or forward-reference sequence and restore it immediately.
OLAP Analytical routines need the same creation-time validation; bulk deployment is not a reason to hide syntax or dependency errors.
Small nodes Leave it on. Validation cost occurs at routine creation and is preferable to discovering a broken function during production execution.

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

  • Changing check_function_bodies in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Expecting a changed default to rewrite existing objects or override explicit DDL clauses.
  • Ignoring tablespace privileges, installed access methods or compression support, and restore portability.
  • Changing check_function_bodies globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_table_access_method · default_tablespace · temp_tablespaces · default_toast_compression · maintenance_work_mem

References

1.6 - client_encoding

client_encoding is the PostgreSQL setting that defines the client’s character set encoding.
Note

Fact — official short description: “Sets the client’s character set encoding.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value ValueSQL_ASCII
SQL_ASCII

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 SQL_ASCII — SQL_ASCII

How it works

client_encoding sets the client’s character set encoding. PostgreSQL converts text between this encoding and the database encoding when a supported conversion exists; SQL_ASCII disables useful validation rather than identifying a real character set.

client_encoding is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat client_encoding as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin client_encoding for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing client_encoding.

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

  • Changing client_encoding in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Using SQL_ASCII as if it were an encoding and allowing invalid byte sequences to cross the client boundary.

Related parameters

lc_messages · lc_monetary · lc_numeric · lc_time · default_text_search_config

References

1.7 - client_min_messages

client_min_messages is the PostgreSQL setting that defines the message levels that are sent to the client.
Note

Fact — official short description: “Sets the message levels that are sent to the client.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuedebug5, debug4, debug3, debug2, debug1, log, notice, warning, error
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valuenotice
notice

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 notice — notice

How it works

client_min_messages sets the message levels that are sent to the client. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. The threshold governs messages returned to the client, not messages written to the server log, and INFO is delivered regardless of the chosen threshold.

client_min_messages is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It affects the client protocol’s diagnostic stream, while log_min_messages and log_min_error_statement independently control server-side records; INFO remains a special always-sent level.

Tuning advice

Tip

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

Workload Guidance
OLTP Set client_min_messages from the application’s diagnostic contract. Keep actionable warnings visible and change the threshold per role or session rather than muting an entire cluster.
OLAP Analytical and interactive users may prefer NOTICE output, but batch pipelines should explicitly choose the messages they can parse without treating notices as result rows.
Small nodes Leave the default NOTICE unless client chatter is measured as a problem; suppressing messages does not materially increase server capacity.

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

  • Changing client_min_messages in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Copying severity expectations from log_min_messages even though the client ordering treats LOG differently and always sends INFO.
  • Suppressing warnings globally and hiding deprecations or operational guidance that applications should surface.
  • Changing client_min_messages globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_min_messages · log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate · log_transaction_sample_rate

References

1.8 - createrole_self_grant

createrole_self_grant is the PostgreSQL setting that defines whether a CREATEROLE user automatically grants the role to themselves, and with which options.
Note

Fact — official short description: “Sets whether a CREATEROLE user automatically grants the role to themselves, and with which options.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit e5b8a4c098ad — Add new GUC createrole_self_grant.
Commit date 2023-01-10
Discussion thread 1

Default history

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

How it works

createrole_self_grant sets whether a CREATEROLE user automatically grants the role to themselves, and with which options. An empty string disables automatic self grants. The accepted options are set, inherit, or both; it automates a grant the creating CREATEROLE user could issue with ADMIN OPTION and does not affect superusers.

createrole_self_grant is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Because session state can survive in pooled connections, role defaults, SET privilege, RESET behavior, and application checkout hooks are part of the control’s effective boundary.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat createrole_self_grant as a correctness or security control, not a throughput knob. Grant SET authority narrowly and establish it from trusted role or application policy.
OLAP Use a dedicated analytical role if createrole_self_grant must differ, and verify that exports, triggers, policies, and name resolution still preserve data correctness.
Small nodes Keep createrole_self_grant at its safe default unless a documented repair or compatibility workflow requires otherwise; record and automatically restore temporary changes.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing createrole_self_grant in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Granting broad SET rights to a control that can change correctness, policy enforcement, or name resolution.
  • Failing to reset a security-sensitive session value before a pooled connection is reused by another request.
  • Changing createrole_self_grant globally without a rollback plan and a client or operational compatibility test.

Related parameters

search_path · row_security · session_replication_role · event_triggers · restrict_nonsystem_relation_kind

References

1.9 - default_table_access_method

default_table_access_method is the PostgreSQL setting that defines the default table access method for new tables.
Note

Fact — official short description: “Sets the default table access method for new tables.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueheap
heap

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 8586bf7ed888 — tableam: introduce table AM infrastructure.
Commit date 2019-03-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 heap — heap

How it works

default_table_access_method sets the default table access method for new tables. It is consulted only when CREATE TABLE, CREATE MATERIALIZED VIEW, or SELECT INTO does not name an access method; existing relations are unchanged.

default_table_access_method is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It supplies a default only when SQL omits an explicit choice, so schema migrations, object-level options, privileges, and later ALTER operations can override or outlive it.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep heap unless a production-ready alternative access method has been tested for concurrency, WAL, backup, replication, upgrades, and tooling; name the choice explicitly in critical DDL.
OLAP Benchmark an alternative with representative scans, loads, updates, and maintenance, then scope it to dedicated objects rather than changing the default prematurely.
Small nodes Use heap. An alternative access method adds operational dependencies and is not a generic remedy for limited hardware.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing default_table_access_method in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Expecting a changed default to rewrite existing objects or override explicit DDL clauses.
  • Ignoring tablespace privileges, installed access methods or compression support, and restore portability.
  • Changing default_table_access_method globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_tablespace · temp_tablespaces · default_toast_compression · check_function_bodies · maintenance_work_mem

References

1.10 - default_tablespace

default_tablespace is the PostgreSQL setting that defines the default tablespace to create tables and indexes in.
Note

Fact — official short description: “Sets the default tablespace to create tables and indexes in.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

default_tablespace sets the default tablespace to create tables and indexes in. An empty string means use the database’s default tablespace. It selects the destination for new persistent tables and indexes, not temporary objects or CREATE DATABASE; an invalid configured name falls back to the database default in some contexts.

default_tablespace is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It supplies a default only when SQL omits an explicit choice, so schema migrations, object-level options, privileges, and later ALTER operations can override or outlive it.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep default_tablespace aligned with schema-management policy and make important storage choices explicit in migrations. Benchmark any physical-layout change with production-shaped writes.
OLAP Use default_tablespace deliberately for bulk objects and spill-heavy jobs, checking I/O placement, compression support, and operational tooling before adoption.
Small nodes Prefer the upstream default for default_tablespace unless the node has a verified alternate storage path or restore requirement; simplicity reduces recovery surprises.

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

  • Changing default_tablespace in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Expecting a changed default to rewrite existing objects or override explicit DDL clauses.
  • Ignoring tablespace privileges, installed access methods or compression support, and restore portability.
  • Changing default_tablespace globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_table_access_method · temp_tablespaces · default_toast_compression · check_function_bodies · maintenance_work_mem

References

1.11 - default_text_search_config

default_text_search_config is the PostgreSQL setting that defines default text search configuration.
Note

Fact — official short description: “Sets default text search configuration.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value Valuepg_catalog.simple
pg_catalog.simple

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 pg_catalog.simple — pg_catalog.simple

How it works

default_text_search_config sets default text search configuration. Text-search functions use it only when the caller omits an explicit configuration; initdb may choose a locale-matching value instead of the built-in simple configuration.

default_text_search_config is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Set default_text_search_config per language domain and application role, or pass the configuration explicitly in durable queries. Verify dictionaries and packages on every replica.
OLAP Pin the configuration in reproducible indexing and reporting jobs so locale changes do not silently alter tokenization or ranking.
Small nodes Use pg_catalog.simple or the initdb-selected locale configuration unless language-aware search is required; extra dictionaries add maintenance, not free quality.

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

  • Changing default_text_search_config in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing default_text_search_config globally without a rollback plan and a client or operational compatibility test.

Related parameters

client_encoding · lc_messages · lc_monetary · lc_numeric · lc_time

References

1.12 - default_toast_compression

default_toast_compression is the PostgreSQL setting that defines the default compression method for compressible values.
Note

Fact — official short description: “Sets the default compression method for compressible values.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuepglz, lz4
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valuelz4
lz4

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit bbe0a81db69b — Allow configurable LZ4 TOAST compression.
Commit date 2021-03-19
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–18 pglz — pglz
PG19 Beta 3 lz4 — lz4

How it works

default_toast_compression sets the default compression method for compressible values. It chooses pglz or, when compiled in, lz4 for newly written compressible values; a column COMPRESSION clause overrides the session default.

default_toast_compression is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It supplies a default only when SQL omits an explicit choice, so schema migrations, object-level options, privileges, and later ALTER operations can override or outlive it.

Tuning advice

Tip

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

Workload Guidance
OLTP Benchmark pglz versus lz4 with representative wide values, update rates, CPU, WAL, and storage. Prefer explicit column COMPRESSION for important schemas over a surprising session default.
OLAP LZ4 can favor faster compression and decompression when the build supports it, but measure actual compressibility and scan behavior before changing new-write policy.
Small nodes Keep pglz unless CPU-versus-space measurements and package support justify lz4; changing the default does not recompress existing values.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing default_toast_compression in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Expecting a changed default to rewrite existing objects or override explicit DDL clauses.
  • Ignoring tablespace privileges, installed access methods or compression support, and restore portability.
  • Changing default_toast_compression globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_table_access_method · default_tablespace · temp_tablespaces · check_function_bodies · maintenance_work_mem

References

1.13 - default_transaction_deferrable

default_transaction_deferrable is the PostgreSQL setting that defines the default deferrable status of new transactions.
Note

Fact — official short description: “Sets the default deferrable status of new transactions.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit dafaa3efb75c — Implement genuine serializable isolation level.
Commit date 2011-02-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 off — off

How it works

default_transaction_deferrable sets the default deferrable status of new transactions. The default matters only for read-only serializable transactions, which may wait for a safe snapshot and then avoid serialization failures.

default_transaction_deferrable is a USER-context setting and can be assigned per role, database, or session; its value is copied when a new transaction starts, so it does not rewrite a transaction already in progress.

The default_* variables seed the corresponding transaction_* state. Isolation, read-only status, deferrability, retries, and snapshot lifetime must be designed together.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose default_transaction_deferrable for correctness semantics first. Keep the common OLTP path explicit, then override only transactions whose consistency contract justifies different blocking or retry behavior.
OLAP For reporting, consider a read-only transaction and an isolation choice that matches snapshot requirements; use deferrability only with read-only serializable work.
Small nodes Do not change default_transaction_deferrable as a generic speed tweak. Higher isolation or long snapshots can amplify contention and vacuum pressure on a small node.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing default_transaction_deferrable in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Changing transaction semantics as a performance experiment and silently weakening an application’s consistency contract.
  • Letting a pooled session retain transaction-related state because checkout or rollback/reset handling is incomplete.
  • Changing default_transaction_deferrable globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_transaction_isolation · transaction_isolation · default_transaction_read_only · transaction_read_only · transaction_deferrable

References

1.14 - default_transaction_isolation

default_transaction_isolation is the PostgreSQL setting that defines the transaction isolation level of each new transaction.
Note

Fact — official short description: “Sets the transaction isolation level of each new transaction.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueserializable, repeatable read, read committed, read uncommitted
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueread committed
read committed

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 read committed — read committed

How it works

default_transaction_isolation sets the transaction isolation level of each new transaction. PostgreSQL copies this value into transaction_isolation when each transaction begins; it changes consistency semantics, not merely performance.

default_transaction_isolation is a USER-context setting and can be assigned per role, database, or session; its value is copied when a new transaction starts, so it does not rewrite a transaction already in progress.

The default_* variables seed the corresponding transaction_* state. Isolation, read-only status, deferrability, retries, and snapshot lifetime must be designed together.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose default_transaction_isolation for correctness semantics first. Keep the common OLTP path explicit, then override only transactions whose consistency contract justifies different blocking or retry behavior.
OLAP For reporting, consider a read-only transaction and an isolation choice that matches snapshot requirements; use deferrability only with read-only serializable work.
Small nodes Do not change default_transaction_isolation as a generic speed tweak. Higher isolation or long snapshots can amplify contention and vacuum pressure on a small node.

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

  • Changing default_transaction_isolation in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Changing transaction semantics as a performance experiment and silently weakening an application’s consistency contract.
  • Letting a pooled session retain transaction-related state because checkout or rollback/reset handling is incomplete.
  • Changing default_transaction_isolation globally without a rollback plan and a client or operational compatibility test.

Related parameters

transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable · transaction_deferrable

References

1.15 - default_transaction_read_only

default_transaction_read_only is the PostgreSQL setting that defines the default read-only status of new transactions.
Note

Fact — official short description: “Sets the default read-only status of new transactions.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

default_transaction_read_only sets the default read-only status of new transactions. Each transaction inherits this default, but read-only mode still permits temporary-table changes and does not substitute for standby or privilege enforcement.

default_transaction_read_only is a USER-context setting and can be assigned per role, database, or session; its value is copied when a new transaction starts, so it does not rewrite a transaction already in progress.

The default_* variables seed the corresponding transaction_* state. Isolation, read-only status, deferrability, retries, and snapshot lifetime must be designed together.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose default_transaction_read_only for correctness semantics first. Keep the common OLTP path explicit, then override only transactions whose consistency contract justifies different blocking or retry behavior.
OLAP For reporting, consider a read-only transaction and an isolation choice that matches snapshot requirements; use deferrability only with read-only serializable work.
Small nodes Do not change default_transaction_read_only as a generic speed tweak. Higher isolation or long snapshots can amplify contention and vacuum pressure on a small node.

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

  • Changing default_transaction_read_only in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Changing transaction semantics as a performance experiment and silently weakening an application’s consistency contract.
  • Letting a pooled session retain transaction-related state because checkout or rollback/reset handling is incomplete.
  • Changing default_transaction_read_only globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_transaction_isolation · transaction_isolation · transaction_read_only · default_transaction_deferrable · transaction_deferrable

References

1.16 - dynamic_library_path

dynamic_library_path is the PostgreSQL setting that defines the path for dynamically loadable modules.
Note

Fact — official short description: “Sets the path for dynamically loadable modules.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Other Defaults
Upstream classification
Latest boot value Value$libdir
$libdir

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 $libdir — $libdir

How it works

dynamic_library_path sets the path for dynamically loadable modules. If a dynamically loadable module needs to be opened and the specified name does not have a directory component (i.e., the name does not contain a slash), the system will search this path for the specified file. The search is used only for module names without a directory component; $libdir points at PostgreSQL’s version-specific library directory.

dynamic_library_path is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module’s own GUCs.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep dynamic_library_path restricted to administrator-controlled, version-matched directories and retain $libdir. Use absolute module paths only when deployment and rollback manage them explicitly.
OLAP Add a search directory only for a reviewed analytical extension package present identically on every failover target.
Small nodes Keep $libdir. Expanding the native-code search path provides no capacity gain and increases packaging and trust risk.

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

  • Changing dynamic_library_path in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Naming a missing or ABI-incompatible module and causing connection failure or a server that cannot start.
  • Treating a search or preload path as harmless even though it defines which native code the server trusts.
  • Changing dynamic_library_path globally without a rollback plan and a client or operational compatibility test.

Related parameters

shared_preload_libraries · session_preload_libraries · local_preload_libraries · jit_provider · extension_control_path

References

1.17 - event_triggers

event_triggers is the PostgreSQL setting that controls whether PostgreSQL enables event triggers.
Note

Fact — official short description: “Enables event triggers.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 7750fefdb2b8 — Add GUC for temporarily disabling event triggers
Commit date 2023-09-25
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 on — on

How it works

event_triggers enables event triggers. When enabled, event triggers will fire for all applicable statements. The switch disables all event triggers as an emergency repair aid; it is not a selective trigger policy and requires elevated SET privilege.

event_triggers is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Because session state can survive in pooled connections, role defaults, SET privilege, RESET behavior, and application checkout hooks are part of the control’s effective boundary.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune event_triggers or leave it off as normal operation. Disable it only in a controlled repair session, identify the faulty trigger, and restore it immediately.
OLAP Keep event triggers enabled unless a documented bulk-load procedure has reviewed every lost audit or DDL side effect.
Small nodes Leave the default on; disabling event triggers saves no meaningful resources and can silently bypass controls.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing event_triggers in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Granting broad SET rights to a control that can change correctness, policy enforcement, or name resolution.
  • Failing to reset a security-sensitive session value before a pooled connection is reused by another request.
  • Changing event_triggers globally without a rollback plan and a client or operational compatibility test.

Related parameters

search_path · row_security · session_replication_role · restrict_nonsystem_relation_kind · createrole_self_grant

References

1.18 - extension_control_path

extension_control_path is the PostgreSQL setting that defines the path for extension control files.
Note

Fact — official short description: “Sets the path for extension control files.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Other Defaults
Upstream classification
Latest boot value Value$system
$system

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 4f7f7b037585 — extension_control_path
Commit date 2025-03-19
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 $system — $system

How it works

extension_control_path sets the path for extension control files. The remaining extension script and secondary control files are then loaded from the same directory where the primary control file was found. PostgreSQL searches this path for an extension’s primary control file, then loads its scripts and secondary control files from the directory where that primary file was found.

extension_control_path is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module’s own GUCs.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep $system first and add only administrator-controlled extension repositories whose control files, scripts, native libraries, upgrades, and rollback are versioned together.
OLAP Use a separate path only to distribute a reviewed extension catalog consistently across primary and standby packages; test CREATE EXTENSION and every upgrade edge.
Small nodes Keep $system. Extra control-file roots do not improve capacity and make extension provenance and disaster recovery harder to audit.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing extension_control_path in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Naming a missing or ABI-incompatible module and causing connection failure or a server that cannot start.
  • Treating a search or preload path as harmless even though it defines which native code the server trusts.
  • Changing extension_control_path globally without a rollback plan and a client or operational compatibility test.

Related parameters

shared_preload_libraries · session_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider

References

1.19 - extra_float_digits

extra_float_digits is the PostgreSQL setting that defines the number of digits displayed for floating-point values.
Note

Fact — official short description: “Sets the number of digits displayed for floating-point values.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value-15 – 3
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value Value1
1

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–11 0 — 0
PG12–19 Beta 3 1 — 1

How it works

extra_float_digits sets the number of digits displayed for floating-point values. This affects real, double precision, and geometric data types. A zero or negative parameter value is added to the standard number of digits (FLT_DIG or DBL_DIG as appropriate). Any value greater than zero selects precise output mode. Since PostgreSQL 12, positive values select shortest-precise output; zero and negative values request rounded legacy output and can lose round-trip fidelity.

extra_float_digits is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat extra_float_digits as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin extra_float_digits for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing extra_float_digits.

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

  • Changing extra_float_digits in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Carrying pre-12 assumptions forward even though positive values now select shortest-precise output.

Related parameters

bytea_output · xmlbinary · xmloption · client_encoding · DateStyle

References

1.20 - gin_fuzzy_search_limit

gin_fuzzy_search_limit is the PostgreSQL setting that defines the maximum allowed result for exact search by GIN.
Note

Fact — official short description: “Sets the maximum allowed result for exact search by GIN.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Other Defaults
Upstream classification
Latest boot value Value0
0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 — 0

How it works

gin_fuzzy_search_limit sets the maximum allowed result for exact search by GIN. 0 means no limit. A positive limit makes broad GIN searches return a randomly chosen subset of matches, trading completeness for bounded work; zero preserves exact results.

gin_fuzzy_search_limit is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

GIN behavior also depends on per-index storage parameters, work or maintenance memory, autovacuum, and the shape of indexed values and predicates.

Tuning advice

Tip

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

Workload Guidance
OLTP Change gin_fuzzy_search_limit only after measuring the affected GIN maintenance or search path. Prefer an index-level override when one index, rather than the whole cluster, is exceptional.
OLAP For batch loads or broad searches, test gin_fuzzy_search_limit against ingestion latency, cleanup spikes, result completeness, and maintenance windows.
Small nodes Do not raise gin_fuzzy_search_limit merely because the default is reached; bound memory and I/O bursts, and keep exact-query semantics unless approximation is explicitly acceptable.

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

  • Changing gin_fuzzy_search_limit in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Applying a cluster-wide GIN value to fix one exceptional index instead of using its storage parameters.
  • Ignoring cleanup latency, I/O bursts, autovacuum interaction, or result completeness while tuning.
  • Enabling a positive limit without telling callers that exact searches may return an incomplete random subset.

Related parameters

gin_pending_list_limit · maintenance_work_mem · work_mem · vacuum_cleanup_index_scale_factor · autovacuum_work_mem

References

1.21 - gin_pending_list_limit

gin_pending_list_limit is the PostgreSQL setting that defines the maximum size of the pending list for GIN index.
Note

Fact — official short description: “Sets the maximum size of the pending list for GIN index.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValuekB
Raw unit
Range Value64 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value4096
4 MiB

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit c291503b1c82 — Rename pending_list_cleanup_size to gin_pending_list_limit.
Commit date 2014-11-13
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–19 Beta 3 4096 kB 4 MiB

How it works

gin_pending_list_limit sets the maximum size of the pending list for GIN index. With a GIN index’s fastupdate enabled, crossing this limit triggers bulk migration from the pending list into the main index; per-index storage parameters can override it.

gin_pending_list_limit is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

GIN behavior also depends on per-index storage parameters, work or maintenance memory, autovacuum, and the shape of indexed values and predicates.

Tuning advice

Tip

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

Workload Guidance
OLTP Change gin_pending_list_limit only after measuring the affected GIN maintenance or search path. Prefer an index-level override when one index, rather than the whole cluster, is exceptional.
OLAP For batch loads or broad searches, test gin_pending_list_limit against ingestion latency, cleanup spikes, result completeness, and maintenance windows.
Small nodes Do not raise gin_pending_list_limit merely because the default is reached; bound memory and I/O bursts, and keep exact-query semantics unless approximation is explicitly acceptable.

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: PG9.5–19 Beta 3 unmodified; OLAP: PG9.5–19 Beta 3 unmodified; CRIT: PG9.5–19 Beta 3 unmodified; TINY: PG9.5–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing gin_pending_list_limit in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Applying a cluster-wide GIN value to fix one exceptional index instead of using its storage parameters.
  • Ignoring cleanup latency, I/O bursts, autovacuum interaction, or result completeness while tuning.
  • Changing gin_pending_list_limit globally without a rollback plan and a client or operational compatibility test.

Related parameters

gin_fuzzy_search_limit · maintenance_work_mem · work_mem · vacuum_cleanup_index_scale_factor · autovacuum_work_mem

References

1.22 - icu_validation_level

icu_validation_level is the PostgreSQL setting that defines the log level for reporting invalid ICU locale strings.
Note

Fact — official short description: “Log level for reporting invalid ICU locale strings.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuedisabled, debug5, debug4, debug3, debug2, debug1, log, notice, warning, error
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value Valuewarning
warning

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 1671f990dd66 — Validate ICU locales.
Commit date 2023-03-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 warning — warning

How it works

icu_validation_level sets the log level for reporting invalid ICU locale strings. The setting changes how invalid ICU locale identifiers are reported, including the option to suppress reporting or escalate it to an error.

icu_validation_level is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep icu_validation_level at WARNING so malformed locale identifiers are visible. Raise it to ERROR only in a migration gate that has already cleaned existing inputs.
OLAP Use the same validation policy for analytical object creation; lowering the level can let inconsistent locale metadata spread into reproducible jobs.
Small nodes Do not tune it for capacity. Preserve WARNING unless a controlled compatibility issue requires temporary lower-severity reporting.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing icu_validation_level in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing icu_validation_level globally without a rollback plan and a client or operational compatibility test.

Related parameters

client_encoding · lc_messages · lc_monetary · lc_numeric · lc_time · default_text_search_config

References

1.23 - idle_in_transaction_session_timeout

idle_in_transaction_session_timeout is the PostgreSQL setting that defines the maximum allowed idle time between queries, when in a transaction.
Note

Fact — official short description: “Sets the maximum allowed idle time between queries, when in a transaction.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value0
0 ms

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit c6dda1f48e57 — Add idle_in_transaction_session_timeout.
Commit date 2016-03-16
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 0 ms 0 ms

How it works

idle_in_transaction_session_timeout sets the maximum allowed idle time between queries, when in a transaction. 0 disables the timeout. It terminates sessions idle inside an open transaction, releasing locks and old snapshots that can block vacuum cleanup and cause bloat.

idle_in_transaction_session_timeout is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Tuning advice

Tip

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

Workload Guidance
OLTP Set idle_in_transaction_session_timeout from the service latency and failure budget, preferably per role or application. Test retries and cancellation paths before enforcing a cluster-wide value.
OLAP Analytical work usually needs a larger or job-specific idle_in_transaction_session_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.
Small nodes Use a conservative finite idle_in_transaction_session_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception.

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 10min different 10min
OLAP 0 same as boot 0
CRIT 1min different 1min
TINY 10min different 10min
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.6–19 Beta 3 = 10min (dcs); OLAP: PG9.6–19 Beta 3 = 0 (dcs); CRIT: PG9.6–19 Beta 3 = 1min (dcs); TINY: PG9.6–19 Beta 3 = 10min (dcs). Advice, pending human review — Editorial inference: The templates bound abandoned open transactions, use a stricter limit for CRIT, and leave OLAP unlimited for deliberately long analytical transactions; each workload still needs pooler and retry review.

Common pitfalls

  • Changing idle_in_transaction_session_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Forgetting that zero usually disables the timeout or delegates behavior to the operating system.
  • Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.
  • Changing idle_in_transaction_session_timeout globally without a rollback plan and a client or operational compatibility test.

Related parameters

statement_timeout · lock_timeout · transaction_timeout · idle_session_timeout · deadlock_timeout

References

1.24 - idle_session_timeout

idle_session_timeout is the PostgreSQL setting that defines the maximum allowed idle time between queries, when not in a transaction.
Note

Fact — official short description: “Sets the maximum allowed idle time between queries, when not in a transaction.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value0
0 ms

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 9877374bef76 — Add idle_session_timeout.
Commit date 2021-01-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 0 ms 0 ms

How it works

idle_session_timeout sets the maximum allowed idle time between queries, when not in a transaction. 0 disables the timeout. It closes sessions idle outside a transaction; such sessions are usually cheap, and poolers may react badly to unexpected server-side closure.

idle_session_timeout is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Tuning advice

Tip

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

Workload Guidance
OLTP Set idle_session_timeout from the service latency and failure budget, preferably per role or application. Test retries and cancellation paths before enforcing a cluster-wide value.
OLAP Analytical work usually needs a larger or job-specific idle_session_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.
Small nodes Use a conservative finite idle_session_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing idle_session_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Forgetting that zero usually disables the timeout or delegates behavior to the operating system.
  • Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.
  • Changing idle_session_timeout globally without a rollback plan and a client or operational compatibility test.

Related parameters

statement_timeout · lock_timeout · transaction_timeout · idle_in_transaction_session_timeout · deadlock_timeout

References

1.25 - jit_provider

jit_provider is the PostgreSQL setting that selects the JIT provider.
Note

Fact — official short description: “JIT provider to use.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Shared Library Preloading
Upstream classification
Latest boot value Valuellvmjit
llvmjit

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 432bb9e04da4 — Basic JIT provider and error handling infrastructure.
Commit date 2018-03-21
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 llvmjit — llvmjit

How it works

jit_provider selects the JIT provider. The named provider supplies PostgreSQL’s JIT implementation and must be binary-compatible; changing the provider requires a server restart.

jit_provider is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module’s own GUCs.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not switch jit_provider as routine tuning. Keep llvmjit when packaged and supported, and control whether JIT runs with jit and its cost thresholds.
OLAP Evaluate a provider only with representative compilation time, execution speed, memory, package compatibility, and restart testing; provider choice is secondary to JIT thresholds.
Small nodes Keep the packaged provider and usually control JIT use rather than replace its implementation; a missing provider can break startup or JIT execution.

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

  • Expecting a reload or SET to activate jit_provider, although it requires a controlled server restart.
  • Naming a missing or ABI-incompatible module and causing connection failure or a server that cannot start.
  • Treating a search or preload path as harmless even though it defines which native code the server trusts.
  • Changing jit_provider globally without a rollback plan and a client or operational compatibility test.

Related parameters

shared_preload_libraries · session_preload_libraries · local_preload_libraries · dynamic_library_path · extension_control_path

References

1.26 - lc_messages

lc_messages is the PostgreSQL setting that defines the language in which messages are displayed.
Note

Fact — official short description: “Sets the language in which messages are displayed.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

lc_messages sets the language in which messages are displayed. An empty string means use the operating system setting. The accepted locale names and available translations are operating-system and build dependent; an empty value inherits the server environment.

lc_messages is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat lc_messages as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin lc_messages for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing lc_messages.

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

  • Changing lc_messages in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing lc_messages globally without a rollback plan and a client or operational compatibility test.

Related parameters

client_encoding · lc_monetary · lc_numeric · lc_time · default_text_search_config

References

1.27 - lc_monetary

lc_monetary is the PostgreSQL setting that defines the locale for formatting monetary amounts.
Note

Fact — official short description: “Sets the locale for formatting monetary amounts.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value ValueC
C

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 C — C

How it works

lc_monetary sets the locale for formatting monetary amounts. An empty string means use the operating system setting. It affects monetary formatting functions such as to_char, not the numeric value stored in a money or numeric column.

lc_monetary is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat lc_monetary as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin lc_monetary for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing lc_monetary.

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

  • Changing lc_monetary in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing lc_monetary globally without a rollback plan and a client or operational compatibility test.

Related parameters

client_encoding · lc_messages · lc_numeric · lc_time · default_text_search_config

References

1.28 - lc_numeric

lc_numeric is the PostgreSQL setting that defines the locale for formatting numbers.
Note

Fact — official short description: “Sets the locale for formatting numbers.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value ValueC
C

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 C — C

How it works

lc_numeric sets the locale for formatting numbers. An empty string means use the operating system setting. It affects locale-sensitive numeric formatting such as decimal and grouping symbols, but ordinary SQL numeric literals retain SQL syntax.

lc_numeric is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat lc_numeric as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin lc_numeric for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing lc_numeric.

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

  • Changing lc_numeric in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing lc_numeric globally without a rollback plan and a client or operational compatibility test.

Related parameters

client_encoding · lc_messages · lc_monetary · lc_time · default_text_search_config

References

1.29 - lc_time

lc_time is the PostgreSQL setting that defines the locale for formatting date and time values.
Note

Fact — official short description: “Sets the locale for formatting date and time values.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value ValueC
C

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 C — C

How it works

lc_time sets the locale for formatting date and time values. An empty string means use the operating system setting. It controls locale-sensitive names and layouts used by formatting functions; DateStyle and TimeZone remain separate controls.

lc_time is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat lc_time as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin lc_time for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing lc_time.

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

  • Changing lc_time in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing lc_time globally without a rollback plan and a client or operational compatibility test.

Related parameters

DateStyle · IntervalStyle · TimeZone · timezone_abbreviations · log_timezone

References

1.30 - local_preload_libraries

local_preload_libraries is the PostgreSQL setting that lists unprivileged shared libraries to preload into each backend.
Note

Fact — official short description: “Lists unprivileged shared libraries to preload into each backend.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Shared Library Preloading
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

local_preload_libraries lists unprivileged shared libraries to preload into each backend. Unprivileged users may name only libraries installed in PostgreSQL’s plugins subdirectory, making package placement part of the security boundary.

Although local_preload_libraries is configurable without a server restart, its library list is acted on only when a new backend starts; changing it inside an established connection does not unload or retroactively load modules.

Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module’s own GUCs.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune local_preload_libraries generically. Load or expose only modules required by a reviewed feature, verify binary compatibility, and rehearse failure recovery before rollout.
OLAP Use local_preload_libraries for a measured extension or JIT requirement, accounting for backend startup, resident memory, and behavior under connection pooling.
Small nodes Keep local_preload_libraries minimal. A missing or incompatible module can reject connections or prevent startup, and every preloaded library consumes scarce address space or memory.

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

  • Changing local_preload_libraries in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Naming a missing or ABI-incompatible module and causing connection failure or a server that cannot start.
  • Treating a search or preload path as harmless even though it defines which native code the server trusts.
  • Changing local_preload_libraries globally without a rollback plan and a client or operational compatibility test.

Related parameters

shared_preload_libraries · session_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

References

1.31 - lock_timeout

lock_timeout is the PostgreSQL setting that defines the maximum allowed duration of any wait for a lock.
Note

Fact — official short description: “Sets the maximum allowed duration of any wait for a lock.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value0
0 ms

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit d43837d03067 — Add lock_timeout configuration parameter.
Commit date 2013-03-16
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 0 ms 0 ms

How it works

lock_timeout sets the maximum allowed duration of any wait for a lock. 0 disables the timeout. The timer applies separately to each lock acquisition, not to total statement runtime; a statement_timeout at the same or lower value will fire first.

lock_timeout is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Tuning advice

Tip

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

Workload Guidance
OLTP Set lock_timeout from the service latency and failure budget, preferably per role or application. Test retries and cancellation paths before enforcing a cluster-wide value.
OLAP Analytical work usually needs a larger or job-specific lock_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.
Small nodes Use a conservative finite lock_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception.

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: PG9.3–19 Beta 3 unmodified; OLAP: PG9.3–19 Beta 3 unmodified; CRIT: PG9.3–19 Beta 3 unmodified; TINY: PG9.3–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing lock_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Forgetting that zero usually disables the timeout or delegates behavior to the operating system.
  • Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.
  • Changing lock_timeout globally without a rollback plan and a client or operational compatibility test.

Related parameters

statement_timeout · transaction_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

References

1.32 - restrict_nonsystem_relation_kind

restrict_nonsystem_relation_kind is the PostgreSQL setting that prohibits access to non-system relations of specified kinds.
Note

Fact — official short description: “Prohibits access to non-system relations of specified kinds.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 79c7a7e29695 — Restrict accesses to non-system views and foreign tables during pg_dump.
Commit date 2024-08-05
Discussion —

Default history

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

How it works

restrict_nonsystem_relation_kind prohibits access to non-system relations of specified kinds. The supported kinds are view and foreign-table; PostgreSQL uses the restriction as a safety boundary for specialized sessions, not as general SQL authorization.

restrict_nonsystem_relation_kind is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Because session state can survive in pooled connections, role defaults, SET privilege, RESET behavior, and application checkout hooks are part of the control’s effective boundary.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune restrict_nonsystem_relation_kind as a general security policy. Leave it empty unless a PostgreSQL subsystem or tightly scoped maintenance workflow explicitly requires the restriction.
OLAP Do not use it to sandbox arbitrary analytical users; enforce access with privileges, schemas, and row-level policies.
Small nodes Keep the default empty. Enabling relation-kind bans has no capacity benefit and can break ordinary queries unexpectedly.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing restrict_nonsystem_relation_kind in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Granting broad SET rights to a control that can change correctness, policy enforcement, or name resolution.
  • Failing to reset a security-sensitive session value before a pooled connection is reused by another request.
  • Changing restrict_nonsystem_relation_kind globally without a rollback plan and a client or operational compatibility test.

Related parameters

search_path · row_security · session_replication_role · event_triggers · createrole_self_grant

References

1.33 - row_security

row_security is the PostgreSQL setting that controls whether PostgreSQL enables row security.
Note

Fact — official short description: “Enables row security.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 491c029dbc42 — Row-Level Security Policies (RLS)
Commit date 2014-09-19
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–19 Beta 3 on — on

How it works

row_security enables row security. When enabled, row security will be applied to all users. Off does not bypass policies for ordinary roles: it raises an error where a policy would apply, which lets tools such as pg_dump avoid silently incomplete results.

row_security is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Because session state can survive in pooled connections, role defaults, SET privilege, RESET behavior, and application checkout hooks are part of the control’s effective boundary.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat row_security as a correctness or security control, not a throughput knob. Grant SET authority narrowly and establish it from trusted role or application policy.
OLAP Use a dedicated analytical role if row_security must differ, and verify that exports, triggers, policies, and name resolution still preserve data correctness.
Small nodes Keep row_security at its safe default unless a documented repair or compatibility workflow requires otherwise; record and automatically restore temporary changes.

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: PG9.5–19 Beta 3 unmodified; OLAP: PG9.5–19 Beta 3 unmodified; CRIT: PG9.5–19 Beta 3 unmodified; TINY: PG9.5–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing row_security in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Granting broad SET rights to a control that can change correctness, policy enforcement, or name resolution.
  • Failing to reset a security-sensitive session value before a pooled connection is reused by another request.
  • Setting off expecting a bypass, although ordinary roles receive an error when a policy would apply.

Related parameters

search_path · session_replication_role · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

References

1.34 - search_path

search_path is the PostgreSQL setting that defines the schema search order for names that are not schema-qualified.
Note

Fact — official short description: “Sets the schema search order for names that are not schema-qualified.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value"$user", public
“$user”, public

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.4 "$user",public — “$user”,public
PG9.5–19 Beta 3 "$user", public — “$user”, public

How it works

search_path sets the schema search order for names that are not schema-qualified. It controls both lookup and the target schema for unqualified CREATE; pg_catalog and the temporary schema have special implicit search rules.

search_path is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Because session state can survive in pooled connections, role defaults, SET privilege, RESET behavior, and application checkout hooks are part of the control’s effective boundary.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat search_path as a correctness or security control, not a throughput knob. Grant SET authority narrowly and establish it from trusted role or application policy.
OLAP Use a dedicated analytical role if search_path must differ, and verify that exports, triggers, policies, and name resolution still preserve data correctness.
Small nodes Keep search_path at its safe default unless a documented repair or compatibility workflow requires otherwise; record and automatically restore temporary changes.

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

  • Changing search_path in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Granting broad SET rights to a control that can change correctness, policy enforcement, or name resolution.
  • Failing to reset a security-sensitive session value before a pooled connection is reused by another request.
  • Placing a schema writable by an untrusted role before trusted schemas and enabling object-shadowing attacks.

Related parameters

row_security · session_replication_role · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

References

1.35 - session_preload_libraries

session_preload_libraries is the PostgreSQL setting that lists shared libraries to preload into each backend.
Note

Fact — official short description: “Lists shared libraries to preload into each backend.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Shared Library Preloading
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit 070518ddab2c — Add session_preload_libraries configuration parameter
Commit date 2013-06-12
Discussion —

Default history

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

How it works

session_preload_libraries lists shared libraries to preload into each backend. The list is loaded into each new matching backend and may be set only by a superuser or an appropriately privileged role; a missing library rejects the connection.

Although session_preload_libraries is configurable without a server restart, its library list is acted on only when a new backend starts; changing it inside an established connection does not unload or retroactively load modules.

Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module’s own GUCs.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune session_preload_libraries generically. Load or expose only modules required by a reviewed feature, verify binary compatibility, and rehearse failure recovery before rollout.
OLAP Use session_preload_libraries for a measured extension or JIT requirement, accounting for backend startup, resident memory, and behavior under connection pooling.
Small nodes Keep session_preload_libraries minimal. A missing or incompatible module can reject connections or prevent startup, and every preloaded library consumes scarce address space or memory.

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: PG9.4–19 Beta 3 unmodified; OLAP: PG9.4–19 Beta 3 unmodified; CRIT: PG9.4–19 Beta 3 unmodified; TINY: PG9.4–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing session_preload_libraries in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Naming a missing or ABI-incompatible module and causing connection failure or a server that cannot start.
  • Treating a search or preload path as harmless even though it defines which native code the server trusts.
  • Changing session_preload_libraries globally without a rollback plan and a client or operational compatibility test.

Related parameters

shared_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

References

1.36 - session_replication_role

session_replication_role is the PostgreSQL setting that defines the session’s behavior for triggers and rewrite rules.
Note

Fact — official short description: “Sets the session’s behavior for triggers and rewrite rules.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueorigin, replica, local
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueorigin
origin

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 origin — origin

How it works

session_replication_role sets the session’s behavior for triggers and rewrite rules. replica suppresses ordinary triggers and rules, including foreign-key enforcement, and changing the value discards cached plans.

session_replication_role is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Because session state can survive in pooled connections, role defaults, SET privilege, RESET behavior, and application checkout hooks are part of the control’s effective boundary.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune session_replication_role. Only a controlled replication or repair process should set replica, and it must independently guarantee constraints and restore origin.
OLAP Keep origin for analytical sessions; suppressing triggers does not accelerate reads and creates severe risk if the session writes.
Small nodes Leave origin. The setting is not a small-node optimization and can bypass foreign keys.

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

  • Changing session_replication_role in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Granting broad SET rights to a control that can change correctness, policy enforcement, or name resolution.
  • Failing to reset a security-sensitive session value before a pooled connection is reused by another request.
  • Forgetting that replica mode suppresses foreign-key triggers as well as application triggers.

Related parameters

search_path · row_security · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

References

1.37 - shared_preload_libraries

shared_preload_libraries is the PostgreSQL setting that lists shared libraries to preload into server.
Note

Fact — official short description: “Lists shared libraries to preload into server.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Shared Library Preloading
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

shared_preload_libraries lists shared libraries to preload into server. Libraries load once in the postmaster before shared memory is finalized, enabling hooks and shared state unavailable to later LOAD; one missing library prevents server startup.

shared_preload_libraries is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module’s own GUCs.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune shared_preload_libraries generically. Load or expose only modules required by a reviewed feature, verify binary compatibility, and rehearse failure recovery before rollout.
OLAP Use shared_preload_libraries for a measured extension or JIT requirement, accounting for backend startup, resident memory, and behavior under connection pooling.
Small nodes Keep shared_preload_libraries minimal. A missing or incompatible module can reject connections or prevent startup, and every preloaded library consumes scarce address space or memory.

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 pg_stat_statements, auto_explain different '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
OLAP pg_stat_statements, auto_explain different '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
CRIT pg_stat_statements, auto_explain different '{{ pg_libs | default("$libdir/passwordcheck, pg_stat_statements, auto_explain") }}'
TINY pg_stat_statements, auto_explain different '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs); OLAP: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs); CRIT: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs); TINY: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs). Advice, pending human review — Editorial inference: pg_stat_statements and auto_explain provide fleet-wide query statistics and targeted slow-plan evidence, accepting restart-time loading and shared overhead.

Common pitfalls

  • Expecting a reload or SET to activate shared_preload_libraries, although it requires a controlled server restart.
  • Naming a missing or ABI-incompatible module and causing connection failure or a server that cannot start.
  • Treating a search or preload path as harmless even though it defines which native code the server trusts.
  • Changing shared_preload_libraries globally without a rollback plan and a client or operational compatibility test.

Related parameters

session_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

References

1.38 - statement_timeout

statement_timeout is the PostgreSQL setting that defines the maximum allowed duration of any statement.
Note

Fact — official short description: “Sets the maximum allowed duration of any statement.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value0
0 ms

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 ms 0 ms

How it works

statement_timeout sets the maximum allowed duration of any statement. 0 disables the timeout. The timer starts when a command arrives; in modern releases each statement in a simple-query string is timed separately, while extended-protocol timing follows Parse/Bind/Execute through Sync.

statement_timeout is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Tuning advice

Tip

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

Workload Guidance
OLTP Set statement_timeout from the service latency and failure budget, preferably per role or application. Test retries and cancellation paths before enforcing a cluster-wide value.
OLAP Analytical work usually needs a larger or job-specific statement_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.
Small nodes Use a conservative finite statement_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception.

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

  • Changing statement_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Forgetting that zero usually disables the timeout or delegates behavior to the operating system.
  • Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.
  • Setting one global value that kills legitimate maintenance and analytical work along with runaway requests.

Related parameters

lock_timeout · transaction_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

References

1.39 - temp_tablespaces

temp_tablespaces is the PostgreSQL setting that defines the tablespace(s) to use for temporary tables and sort files.
Note

Fact — official short description: “Sets the tablespace(s) to use for temporary tables and sort files.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

temp_tablespaces sets the tablespace(s) to use for temporary tables and sort files. An empty string means use the database’s default tablespace. PostgreSQL uses the list for temporary relations and executor spill files, choosing among multiple entries to distribute work; permissions and existence are checked by context.

temp_tablespaces is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It supplies a default only when SQL omits an explicit choice, so schema migrations, object-level options, privileges, and later ALTER operations can override or outlive it.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep temp_tablespaces aligned with schema-management policy and make important storage choices explicit in migrations. Benchmark any physical-layout change with production-shaped writes.
OLAP Use temp_tablespaces deliberately for bulk objects and spill-heavy jobs, checking I/O placement, compression support, and operational tooling before adoption.
Small nodes Prefer the upstream default for temp_tablespaces unless the node has a verified alternate storage path or restore requirement; simplicity reduces recovery surprises.

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

  • Changing temp_tablespaces in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Expecting a changed default to rewrite existing objects or override explicit DDL clauses.
  • Ignoring tablespace privileges, installed access methods or compression support, and restore portability.
  • Changing temp_tablespaces globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_table_access_method · default_tablespace · default_toast_compression · check_function_bodies · maintenance_work_mem

References

1.40 - timezone_abbreviations

timezone_abbreviations is the PostgreSQL setting that selects a file of time zone abbreviations.
Note

Fact — official short description: “Selects a file of time zone abbreviations.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Locale and Formatting
Upstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 UNKNOWN — UNKNOWN
PG9.1–19 Beta 3 — — not set

How it works

timezone_abbreviations selects a file of time zone abbreviations. The selected set changes accepted datetime input tokens and can make the same abbreviation resolve differently by region.

timezone_abbreviations is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat timezone_abbreviations as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin timezone_abbreviations for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing timezone_abbreviations.

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

  • Changing timezone_abbreviations in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Accepting a region-specific abbreviation set that gives familiar tokens a different UTC offset.

Related parameters

DateStyle · IntervalStyle · TimeZone · lc_time · log_timezone

References

1.41 - transaction_deferrable

transaction_deferrable is the PostgreSQL setting that controls whether PostgreSQL should defer a read-only serializable transaction until it can be executed with no possible serialization failures.
Note

Fact — official short description: “Whether to defer a read-only serializable transaction until it can be executed with no possible serialization failures.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit dafaa3efb75c — Implement genuine serializable isolation level.
Commit date 2011-02-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 off — off

How it works

transaction_deferrable controls whether PostgreSQL should defer a read-only serializable transaction until it can be executed with no possible serialization failures. It reflects the current transaction and is meaningful only for a read-only serializable transaction before the snapshot is acquired.

transaction_deferrable is session-settable but represents the current transaction; PostgreSQL restricts changes after the transaction has acquired a snapshot or performed conflicting work.

The default_* variables seed the corresponding transaction_* state. Isolation, read-only status, deferrability, retries, and snapshot lifetime must be designed together.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose transaction_deferrable for correctness semantics first. Keep the common OLTP path explicit, then override only transactions whose consistency contract justifies different blocking or retry behavior.
OLAP For reporting, consider a read-only transaction and an isolation choice that matches snapshot requirements; use deferrability only with read-only serializable work.
Small nodes Do not change transaction_deferrable as a generic speed tweak. Higher isolation or long snapshots can amplify contention and vacuum pressure on a small node.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing transaction_deferrable in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Changing transaction semantics as a performance experiment and silently weakening an application’s consistency contract.
  • Letting a pooled session retain transaction-related state because checkout or rollback/reset handling is incomplete.
  • Changing transaction_deferrable globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_transaction_isolation · transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable

References

1.42 - transaction_isolation

transaction_isolation is the PostgreSQL setting that defines the current transaction’s isolation level.
Note

Fact — official short description: “Sets the current transaction’s isolation level.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueserializable, repeatable read, read committed, read uncommitted
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueread committed
read committed

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 — — not set
PG9.1–11 default — default
PG12–19 Beta 3 read committed — read committed

How it works

transaction_isolation sets the current transaction’s isolation level. It reflects the current transaction, begins from default_transaction_isolation, and cannot be freely raised after the transaction has performed work.

transaction_isolation is session-settable but represents the current transaction; PostgreSQL restricts changes after the transaction has acquired a snapshot or performed conflicting work.

The default_* variables seed the corresponding transaction_* state. Isolation, read-only status, deferrability, retries, and snapshot lifetime must be designed together.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose transaction_isolation for correctness semantics first. Keep the common OLTP path explicit, then override only transactions whose consistency contract justifies different blocking or retry behavior.
OLAP For reporting, consider a read-only transaction and an isolation choice that matches snapshot requirements; use deferrability only with read-only serializable work.
Small nodes Do not change transaction_isolation as a generic speed tweak. Higher isolation or long snapshots can amplify contention and vacuum pressure on a small node.

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

  • Changing transaction_isolation in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Changing transaction semantics as a performance experiment and silently weakening an application’s consistency contract.
  • Letting a pooled session retain transaction-related state because checkout or rollback/reset handling is incomplete.
  • Changing transaction_isolation globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable · transaction_deferrable

References

1.43 - transaction_read_only

transaction_read_only is the PostgreSQL setting that defines the current transaction’s read-only status.
Note

Fact — official short description: “Sets the current transaction’s read-only status.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

transaction_read_only sets the current transaction’s read-only status. It reflects the current transaction, begins from default_transaction_read_only, and must be set before operations that conflict with read-only mode.

transaction_read_only is session-settable but represents the current transaction; PostgreSQL restricts changes after the transaction has acquired a snapshot or performed conflicting work.

The default_* variables seed the corresponding transaction_* state. Isolation, read-only status, deferrability, retries, and snapshot lifetime must be designed together.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose transaction_read_only for correctness semantics first. Keep the common OLTP path explicit, then override only transactions whose consistency contract justifies different blocking or retry behavior.
OLAP For reporting, consider a read-only transaction and an isolation choice that matches snapshot requirements; use deferrability only with read-only serializable work.
Small nodes Do not change transaction_read_only as a generic speed tweak. Higher isolation or long snapshots can amplify contention and vacuum pressure on a small node.

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

  • Changing transaction_read_only in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Changing transaction semantics as a performance experiment and silently weakening an application’s consistency contract.
  • Letting a pooled session retain transaction-related state because checkout or rollback/reset handling is incomplete.
  • Changing transaction_read_only globally without a rollback plan and a client or operational compatibility test.

Related parameters

default_transaction_isolation · transaction_isolation · default_transaction_read_only · default_transaction_deferrable · transaction_deferrable

References

1.44 - transaction_timeout

transaction_timeout is the PostgreSQL setting that defines the maximum allowed duration of any transaction within a session (not a prepared transaction).
Note

Fact — official short description: “Sets the maximum allowed duration of any transaction within a session (not a prepared transaction).”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value0
0 ms

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 51efe38cb92f — Introduce transaction_timeout
Commit date 2024-02-15
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 0 ms 0 ms

How it works

transaction_timeout sets the maximum allowed duration of any transaction within a session (not a prepared transaction). 0 disables the timeout. It terminates the session rather than merely canceling one statement, excludes prepared transactions, and makes longer idle-in-transaction or statement timeouts ineffective when set lower.

transaction_timeout is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Tuning advice

Tip

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

Workload Guidance
OLTP Set transaction_timeout from the service latency and failure budget, preferably per role or application. Test retries and cancellation paths before enforcing a cluster-wide value.
OLAP Analytical work usually needs a larger or job-specific transaction_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.
Small nodes Use a conservative finite transaction_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing transaction_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Forgetting that zero usually disables the timeout or delegates behavior to the operating system.
  • Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.
  • Expecting it to resolve prepared transactions, which are explicitly excluded.

Related parameters

statement_timeout · lock_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

References

1.45 - vacuum_cleanup_index_scale_factor

vacuum_cleanup_index_scale_factor is the PostgreSQL setting that defines the number of tuple inserts prior to index cleanup as a fraction of reltuples.
Note

Fact — official short description: “Number of tuple inserts prior to index cleanup as a fraction of reltuples.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1e+10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Value0.1
0.1

Lifecycle

Fact Value
First observed PG11
Present in PG11–13
Removed in PG14
Introduction commit 857f9c36cda5 — Skip full index scan during cleanup of B-tree indexes when possible
Commit date 2018-04-04
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–13 0.1 — 0.1

How it works

vacuum_cleanup_index_scale_factor sets the number of tuple inserts prior to index cleanup as a fraction of reltuples. The PostgreSQL 11–13 knob delayed index cleanup after inserts; it was removed in PostgreSQL 14 when the index-cleanup decision model changed.

vacuum_cleanup_index_scale_factor is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The legacy decision applied to B-tree cleanup scans and interacted with VACUUM statistics, inserted tuples, reusable index pages, and autovacuum scheduling; it was not a GIN control.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune vacuum_cleanup_index_scale_factor for a current server: PostgreSQL removed it in 14. On PostgreSQL 11–13, change it only for a measured index-cleanup problem and plan the upgrade behavior.
OLAP For legacy bulk-load systems, measure actual index maintenance rather than carrying this removed knob forward as configuration folklore.
Small nodes Leave the legacy default and upgrade; a removed parameter is not a durable way to manage small-node vacuum cost.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG13; 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–13 unmodified; OLAP: PG11–13 unmodified; CRIT: PG11–13 unmodified; TINY: PG11–13 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing vacuum_cleanup_index_scale_factor in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Applying an old B-tree cleanup heuristic without measuring index scans, reusable pages, and VACUUM behavior on the exact release.
  • Confusing a removed session default with current autovacuum thresholds or per-table storage parameters.
  • Keeping an unknown-parameter line during a PostgreSQL 14+ upgrade.

Related parameters

autovacuum · autovacuum_vacuum_scale_factor · vacuum_cost_limit · vacuum_cost_delay · maintenance_work_mem · autovacuum_work_mem

References

1.46 - xmlbinary

xmlbinary is the PostgreSQL setting that defines how binary values are to be encoded in XML.
Note

Fact — official short description: “Sets how binary values are to be encoded in XML.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuebase64, hex
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valuebase64
base64

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 base64 — base64

How it works

xmlbinary sets how binary values are to be encoded in XML. It affects bytea-to-XML conversion by XML construction functions; both base64 and hex preserve all bytes, but hex output is larger.

xmlbinary is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat xmlbinary as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin xmlbinary for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing xmlbinary.

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

  • Changing xmlbinary in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing xmlbinary globally without a rollback plan and a client or operational compatibility test.

Related parameters

bytea_output · extra_float_digits · xmloption · client_encoding · DateStyle

References

1.47 - xmloption

xmloption is the PostgreSQL setting that defines whether XML data in implicit parsing and serialization operations is to be considered as documents or content fragments.
Note

Fact — official short description: “Sets whether XML data in implicit parsing and serialization operations is to be considered as documents or content fragments.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuecontent, document
— for non-enum types
Category ValueClient Connection Defaults / Statement Behavior
Upstream classification
Latest boot value Valuecontent
content

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 content — content

How it works

xmloption sets whether XML data in implicit parsing and serialization operations is to be considered as documents or content fragments. CONTENT permits XML fragments while DOCUMENT requires a single well-formed XML document, changing implicit casts and serialization behavior.

xmloption is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes representation, parsing, or locale behavior at the client boundary rather than physical storage. Coordinate it with the other locale and formatting settings and with driver-native binary or typed protocols.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat xmloption as an application contract, not a performance knob. Standardize it per role or connection pool and keep wire formats explicit where clients parse text.
OLAP Pin xmloption for export, reporting, and reproducible analytical jobs; prefer explicit SQL formatting when a file or API has a durable schema.
Small nodes Keep the upstream or locale-derived value unless a client requires another one. A smaller server gains no capacity from changing xmloption.

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

  • Changing xmloption in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Assuming a presentation setting changes stored values or server-side type semantics.
  • Changing a role or database default without testing text-parsing clients, exports, and pooled sessions.
  • Changing xmloption globally without a rollback plan and a client or operational compatibility test.

Related parameters

bytea_output · extra_float_digits · xmlbinary · client_encoding · DateStyle

References

2 - Connections and Authentication

Complete dossiers for 45 core PostgreSQL settings in Connections and Authentication.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

2.1 - authentication_timeout

authentication_timeout is the PostgreSQL setting that defines the maximum allowed time to complete client authentication.
Note

Fact — official short description: “Sets the maximum allowed time to complete client authentication.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value1 – 600
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Authentication
Upstream classification
Latest boot value Value60
1 min

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 60 s 1 min

How it works

authentication_timeout sets the maximum allowed time to complete client authentication. The timer covers the authentication exchange before a normal backend session is established, limiting slots consumed by stalled or malicious handshakes.

authentication_timeout is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The final authentication path combines this setting with pg_hba.conf, role attributes, credential material, client capabilities, and sometimes operating-system identity services.

Tuning advice

Tip

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

Workload Guidance
OLTP Set authentication_timeout from the authentication architecture and security policy, not workload throughput. Test every driver, identity mapping, failover path, and credential-rotation procedure.
OLAP Apply the same security baseline to analytical access; isolate any legacy client exception to a dedicated role and a dated migration plan.
Small nodes Prefer the current secure default for authentication_timeout. Avoid weakening authentication to save marginal CPU on a small node; reduce connection churn with pooling instead.

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

  • Editing authentication_timeout without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing one authentication setting without testing pg_hba.conf ordering, existing secrets, mappings, and every client library.
  • Weakening identity policy to solve connection churn or CPU cost that should be addressed with pooling and capacity planning.
  • Changing authentication_timeout globally without a rollback plan and a client or operational compatibility test.

Related parameters

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval

References

2.2 - bonjour

bonjour is the PostgreSQL setting that controls whether PostgreSQL enables advertising the server via Bonjour.
Note

Fact — official short description: “Enables advertising the server via Bonjour.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

bonjour enables advertising the server via Bonjour. It publishes a discoverable service through mDNS only on builds and platforms with Bonjour support; it does not open a listener or alter pg_hba.conf.

bonjour is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Bonjour advertisement depends on platform support and publishes the listener as metadata; listen_addresses, port, pg_hba.conf, TLS, and firewalls still define actual reachability and trust.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable bonjour only when clients deliberately use Bonjour/mDNS on a trusted local network. Treat it as discovery metadata, never as authentication or a highly available service registry.
OLAP Analytical workload shape does not justify different bonjour behavior; use the same reviewed discovery policy and stable service identity.
Small nodes Leave bonjour off or empty unless local zero-configuration discovery is an explicit requirement; it does not improve database capacity.

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

  • Expecting a reload or SET to activate bonjour, although it requires a controlled server restart.
  • Treating an mDNS advertisement as an access-control, authentication, or high-availability mechanism.
  • Publishing an unexpected service name or endpoint on an untrusted broadcast domain.
  • Changing bonjour globally without a rollback plan and a client or operational compatibility test.

Related parameters

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

References

2.3 - bonjour_name

bonjour_name is the PostgreSQL setting that defines the Bonjour service name.
Note

Fact — official short description: “Sets the Bonjour service name.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

bonjour_name sets the Bonjour service name. An empty string means use the computer name. An empty value derives the advertised service name from the computer name, and the setting matters only when Bonjour advertisement is enabled.

bonjour_name is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Bonjour advertisement depends on platform support and publishes the listener as metadata; listen_addresses, port, pg_hba.conf, TLS, and firewalls still define actual reachability and trust.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable bonjour_name only when clients deliberately use Bonjour/mDNS on a trusted local network. Treat it as discovery metadata, never as authentication or a highly available service registry.
OLAP Analytical workload shape does not justify different bonjour_name behavior; use the same reviewed discovery policy and stable service identity.
Small nodes Leave bonjour_name off or empty unless local zero-configuration discovery is an explicit requirement; it does not improve database capacity.

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

  • Expecting a reload or SET to activate bonjour_name, although it requires a controlled server restart.
  • Treating an mDNS advertisement as an access-control, authentication, or high-availability mechanism.
  • Publishing an unexpected service name or endpoint on an untrusted broadcast domain.
  • Changing bonjour_name globally without a rollback plan and a client or operational compatibility test.

Related parameters

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

References

2.4 - client_connection_check_interval

client_connection_check_interval is the PostgreSQL setting that defines the time interval between checks for disconnection while running queries.
Note

Fact — official short description: “Sets the time interval between checks for disconnection while running queries.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / TCP Settings
Upstream classification
Latest boot value Value0
0 ms

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit c30f54ad732c — Detect POLLHUP/POLLRDHUP while running queries.
Commit date 2021-04-03
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 0 ms 0 ms

How it works

client_connection_check_interval sets the time interval between checks for disconnection while running queries. 0 disables connection checks. A nonzero interval lets long-running queries notice a dead client before their next socket write; operating-system support determines whether checks are effective.

client_connection_check_interval is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Tuning advice

Tip

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

Workload Guidance
OLTP Use a nonzero client_connection_check_interval only when abandoning work after client loss materially saves capacity and the platform supports the check. Measure the polling overhead at the chosen interval.
OLAP Long analytical queries can benefit from periodic disconnect detection because they may otherwise run after a client disappears; the interval does not cap a healthy query’s runtime.
Small nodes Leave zero unless orphaned long queries are observed. If enabled, choose an interval that detects waste without adding excessive checks to active queries.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing client_connection_check_interval in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Forgetting that zero usually disables the timeout or delegates behavior to the operating system.
  • Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.
  • Changing client_connection_check_interval globally without a rollback plan and a client or operational compatibility test.

Related parameters

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · authentication_timeout

References

2.5 - db_user_namespace

db_user_namespace is the PostgreSQL setting that controls whether PostgreSQL enables per-database user names.
Note

Fact — official short description: “Enables per-database user names.”

Identity

Type Valuebool
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 / Authentication
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–16
Removed in PG17
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–16 off — off

How it works

db_user_namespace enables per-database user names. This legacy feature represented users internally as user@database and was removed in PostgreSQL 17; it is not a modern tenant-isolation mechanism.

db_user_namespace is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The final authentication path combines this setting with pg_hba.conf, role attributes, credential material, client capabilities, and sometimes operating-system identity services.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not adopt or tune db_user_namespace: it was a legacy compatibility feature and is absent from PostgreSQL 17+. Migrate to ordinary cluster-wide roles with explicit authorization.
OLAP Do not build analytical tenancy on db_user_namespace. Use roles, schemas, databases, and row-level security according to the required boundary.
Small nodes Leave db_user_namespace off on old releases and remove dependencies before upgrading; it provides no useful small-node optimization.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG16; 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: PG9.0–16 unmodified; OLAP: PG9.0–16 unmodified; CRIT: PG9.0–16 unmodified; TINY: PG9.0–16 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing db_user_namespace without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing one authentication setting without testing pg_hba.conf ordering, existing secrets, mappings, and every client library.
  • Weakening identity policy to solve connection churn or CPU cost that should be addressed with pooling and capacity planning.
  • Changing db_user_namespace globally without a rollback plan and a client or operational compatibility test.

Related parameters

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

References

2.6 - gss_accept_delegation

gss_accept_delegation is the PostgreSQL setting that defines whether GSSAPI delegation should be accepted from the client.
Note

Fact — official short description: “Sets whether GSSAPI delegation should be accepted from the client.”

Identity

Type Valuebool
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 / Authentication
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 9c0a0e2ed92a — rename “gss_accept_deleg” to “gss_accept_delegation”.
Commit date 2023-05-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 off — off

How it works

gss_accept_delegation sets whether GSSAPI delegation should be accepted from the client. Accepting delegated credentials lets server-side code act with the client’s GSS identity, so it expands trust beyond ordinary authentication.

gss_accept_delegation is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The final authentication path combines this setting with pg_hba.conf, role attributes, credential material, client capabilities, and sometimes operating-system identity services.

Tuning advice

Tip

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

Workload Guidance
OLTP Set gss_accept_delegation from the authentication architecture and security policy, not workload throughput. Test every driver, identity mapping, failover path, and credential-rotation procedure.
OLAP Apply the same security baseline to analytical access; isolate any legacy client exception to a dedicated role and a dated migration plan.
Small nodes Prefer the current secure default for gss_accept_delegation. Avoid weakening authentication to save marginal CPU on a small node; reduce connection churn with pooling instead.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing gss_accept_delegation without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing one authentication setting without testing pg_hba.conf ordering, existing secrets, mappings, and every client library.
  • Weakening identity policy to solve connection churn or CPU cost that should be addressed with pooling and capacity planning.
  • Changing gss_accept_delegation globally without a rollback plan and a client or operational compatibility test.

Related parameters

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

References

2.7 - krb_caseins_users

krb_caseins_users is the PostgreSQL setting that defines whether Kerberos and GSSAPI user names should be treated as case-insensitive.
Note

Fact — official short description: “Sets whether Kerberos and GSSAPI user names should be treated as case-insensitive.”

Identity

Type Valuebool
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 / Authentication
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

krb_caseins_users sets whether Kerberos and GSSAPI user names should be treated as case-insensitive. It affects comparison of authenticated Kerberos/GSS names with database role names; case folding can merge identities that an existing mapping treated as distinct.

krb_caseins_users is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The final authentication path combines this setting with pg_hba.conf, role attributes, credential material, client capabilities, and sometimes operating-system identity services.

Tuning advice

Tip

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

Workload Guidance
OLTP Set krb_caseins_users from the authentication architecture and security policy, not workload throughput. Test every driver, identity mapping, failover path, and credential-rotation procedure.
OLAP Apply the same security baseline to analytical access; isolate any legacy client exception to a dedicated role and a dated migration plan.
Small nodes Prefer the current secure default for krb_caseins_users. Avoid weakening authentication to save marginal CPU on a small node; reduce connection churn with pooling instead.

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

  • Editing krb_caseins_users without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing one authentication setting without testing pg_hba.conf ordering, existing secrets, mappings, and every client library.
  • Weakening identity policy to solve connection churn or CPU cost that should be addressed with pooling and capacity planning.
  • Changing krb_caseins_users globally without a rollback plan and a client or operational compatibility test.

Related parameters

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

References

2.8 - krb_server_keyfile

krb_server_keyfile is the PostgreSQL setting that defines the location of the Kerberos server key file.
Note

Fact — official short description: “Sets the location of the Kerberos server key file.”

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 / Authentication
Upstream classification
Latest boot value ValueFILE:/etc/postgresql-common/krb5.keytab
FILE:/etc/postgresql-common/krb5.keytab

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 "" — empty string
PG9.1–19 Beta 3 FILE:/etc/postgresql-common/krb5.keytab — FILE:/etc/postgresql-common/krb5.keytab

How it works

krb_server_keyfile sets the location of the Kerberos server key file. The file contains service keys used by GSSAPI authentication; operating-system ownership and keytab rotation are part of the effective configuration.

krb_server_keyfile is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The final authentication path combines this setting with pg_hba.conf, role attributes, credential material, client capabilities, and sometimes operating-system identity services.

Tuning advice

Tip

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

Workload Guidance
OLTP Set krb_server_keyfile from the authentication architecture and security policy, not workload throughput. Test every driver, identity mapping, failover path, and credential-rotation procedure.
OLAP Apply the same security baseline to analytical access; isolate any legacy client exception to a dedicated role and a dated migration plan.
Small nodes Prefer the current secure default for krb_server_keyfile. Avoid weakening authentication to save marginal CPU on a small node; reduce connection churn with pooling instead.

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

  • Editing krb_server_keyfile without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing one authentication setting without testing pg_hba.conf ordering, existing secrets, mappings, and every client library.
  • Weakening identity policy to solve connection churn or CPU cost that should be addressed with pooling and capacity planning.
  • Changing krb_server_keyfile globally without a rollback plan and a client or operational compatibility test.

Related parameters

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries

References

2.9 - krb_srvname

krb_srvname — Sets the name of the Kerberos service. Observed in PG9.0–9.3; its last measured boot default is postgres in PG9.3, with sighup context. It was removed in PG9.4.
Note

Fact — official short description: “Sets the name of the Kerberos service.”

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 / Security and Authentication
Upstream classification
Latest boot value Valuepostgres
postgres

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.3
Removed in PG9.4
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.3 postgres — postgres

How it works

PostgreSQL describes krb_srvname as follows: “Sets the name of the Kerberos service.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG9.0–9.3; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

This historical authentication setting selected the Kerberos service principal name used by the server. It disappeared after PostgreSQL 9.3; current deployments should derive their GSS/Kerberos design from pg_hba.conf, the keytab selected by krb_server_keyfile, DNS, and the client service-name options rather than carrying this obsolete server GUC forward.

Read it together with krb_server_keyfile, hba_file, ssl, password_encryption. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.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: PG9.0–9.3 unmodified; OLAP: PG9.0–9.3 unmodified; CRIT: PG9.0–9.3 unmodified; TINY: PG9.0–9.3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for krb_srvname as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

krb_server_keyfile · hba_file · ssl · password_encryption

References

2.10 - listen_addresses

listen_addresses is the PostgreSQL setting that defines the host name or IP address(es) to listen to.
Note

Fact — official short description: “Sets the host name or IP address(es) to listen to.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Valuelocalhost
localhost

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 localhost — localhost

How it works

listen_addresses sets the host name or IP address(es) to listen to. The server binds the listed interfaces at startup; reachability still depends on port, pg_hba.conf, host firewalls, and network routing.

listen_addresses is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

The listener endpoint combines listen_addresses and port at startup, while pg_hba.conf, TLS, firewalls, routing, and service discovery determine which clients can use it.

Tuning advice

Tip

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

Workload Guidance
OLTP Set listen_addresses from the service topology and expose only required interfaces or ports. Validate poolers, health checks, pg_hba.conf, firewalls, failover, and restart sequencing together.
OLAP Use an explicit analytical endpoint or network when isolation is required, but keep connection information consistent across failover targets.
Small nodes Prefer local-only exposure unless remote access is required. Preserve a tested administrative route before changing listen_addresses and restarting.

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

  • Expecting a reload or SET to activate listen_addresses, although it requires a controlled server restart.
  • Assuming a bound address or port grants access; pg_hba.conf and operating-system or network controls still apply.
  • Changing a startup-only endpoint without updating discovery, health checks, firewalls, clients, and the administrative recovery path.
  • Changing listen_addresses globally without a rollback plan and a client or operational compatibility test.

Related parameters

port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

References

2.11 - max_connections

The startup-time ceiling on concurrent PostgreSQL client connections and a sizing input for several shared resources.
Note

Fact — official short description: “Sets the maximum number of concurrent connections.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value1 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value100
100

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 100 — 100

How it works

max_connections limits concurrent database-server connections and can only be changed at server start. PostgreSQL sizes some resources directly from it, so raising the ceiling increases allocations including shared memory even when not all slots are busy.

reserved_connections and superuser_reserved_connections carve emergency or privileged capacity out of the same overall ceiling. An application therefore cannot normally consume every configured slot.

A standby must use a value at least as high as its primary. Connection pooling can decouple large client populations from a smaller, controlled number of PostgreSQL backends.

Tuning advice

Tip

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

Workload Guidance
OLTP Prefer transaction pooling for large client populations and size PostgreSQL backends for peak active database work plus monitoring, maintenance, and failover margin. Do not map one client connection to one server slot by default.
OLAP Analytical sessions are usually fewer and heavier; keep the backend ceiling low enough that simultaneous work_mem and parallel-worker demand remain bounded. Reserve explicit capacity for ETL and administration.
Small nodes Use a low ceiling with a pooler and preserve reserved slots. Validate startup shared-memory requirements and do not compensate for connection leaks by repeatedly raising the limit.

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 500 different {{ pg_max_connections }}
OLAP 500 different {{ pg_max_connections }}
CRIT 500 different {{ pg_max_connections }}
TINY 250 different {{ pg_max_connections }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 500 (dcs); OLAP: PG9.0–19 Beta 3 = 500 (dcs); CRIT: PG9.0–19 Beta 3 = 500 (dcs); TINY: PG9.0–19 Beta 3 = 250 (dcs). Advice, pending human review — Editorial inference: the templates expose a generous compatibility ceiling behind pooling while reducing it for the small-node profile, but actual active-backend and memory limits still need workload-specific review.

Common pitfalls

  • Changing the value without planning a restart and keeping standbys at least as high as the primary.
  • Ignoring shared-memory and per-backend overhead created by a higher ceiling.
  • Forgetting reserved and superuser-reserved slots when calculating application capacity.
  • Combining a high connection ceiling with generous per-operation memory settings and assuming the product cannot occur.

Related parameters

reserved_connections · superuser_reserved_connections · work_mem · max_worker_processes · max_prepared_transactions · max_wal_senders

References

2.12 - md5_password_warnings

md5_password_warnings is the PostgreSQL setting that controls whether PostgreSQL enables deprecation warnings for MD5 passwords.
Note

Fact — official short description: “Enables deprecation warnings for MD5 passwords.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Authentication
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit db6a4a985bc0 — Deprecate MD5 passwords.
Commit date 2024-12-02
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 on — on

How it works

md5_password_warnings controls a PostgreSQL 18 deprecation WARNING emitted when CREATE ROLE or ALTER ROLE sets an MD5-encrypted password. It does not report authentication with an existing MD5 verifier and is therefore not an inventory of active MD5 clients or roles.

It is a USER-context setting, so an authorized role can change it for the current session and ALTER ROLE or ALTER DATABASE can establish future-session defaults. The warning can only arise in a session that both performs a password-setting statement and has the setting enabled.

password_encryption controls the format generated when plaintext passwords are set, while existing pg_authid verifiers remain unchanged until their passwords are reset. Migration therefore needs a protected verifier inventory, client compatibility testing, and credential rotation in addition to this warning.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep md5_password_warnings on, but treat each warning only as evidence that a password-setting statement created or supplied an MD5 verifier. Separately inventory existing verifier types and test every authentication path before enforcing SCRAM-only access.
OLAP Use the same rule for analytical roles: a silent legacy driver may continue authenticating with an old MD5 verifier without generating this warning, so test and rotate those credentials explicitly.
Small nodes Leave the warning enabled; its cost is negligible. Do not mistake an empty warning stream for proof that no MD5 verifiers or MD5-only clients remain.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Assuming the warning fires when an existing MD5 verifier is used for authentication; it fires only when CREATE ROLE or ALTER ROLE sets one.
  • Using the absence of warnings as proof that the cluster has no MD5 secrets or MD5-only clients.
  • Disabling the warning in deployment sessions that create or rotate roles and thereby hiding new MD5 verifier creation.
  • Changing password_encryption without rotating existing role passwords, which leaves their stored verifier format unchanged.

Related parameters

password_encryption · scram_iterations · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

References

2.13 - oauth_validator_libraries

oauth_validator_libraries is the PostgreSQL setting that lists libraries that may be called to validate OAuth v2 bearer tokens.
Note

Fact — official short description: “Lists libraries that may be called to validate OAuth v2 bearer tokens.”

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 / Authentication
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit b3f0be788afc — Add support for OAUTHBEARER SASL mechanism
Commit date 2025-02-20
Discussion thread 1

Default history

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

How it works

oauth_validator_libraries lists trusted server modules that can validate OAuth 2.0 bearer tokens. PostgreSQL 18 ships no validator implementation, and the empty default refuses all OAuth connections; a usable deployment must install and name at least one compatible module.

With exactly one listed library, PostgreSQL uses it by default for OAuth connections. With multiple libraries, every oauth record in pg_hba.conf must name a validator selected from this list. The setting has SIGHUP context, so changing the allow-list requires a configuration reload and affects subsequent authentication attempts.

A validator executes trusted native code inside the server authentication path. Its token issuer, audience, claim-to-role mapping, failure behavior, dependencies, package version, and availability on every primary/failover node must agree with pg_hba.conf and the identity provider.

Tuning advice

Tip

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

Workload Guidance
OLTP Install one reviewed validator first, pin its package/version on every failover target, and test issuer, audience, expiry, revocation, role mapping, malformed tokens, and identity-provider outage before enabling an oauth HBA rule.
OLAP Use the same validator trust policy for analytical access. If a different issuer or claim mapping is required, list the reviewed modules explicitly and select the intended validator in every matching HBA record.
Small nodes The empty value securely disables OAuth but is not a working OAuth configuration. On a small node, prefer one well-tested validator and budget its token-validation latency instead of weakening checks.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Creating an oauth HBA rule while the list is empty; PostgreSQL will refuse every OAuth connection.
  • Expecting PostgreSQL to provide a built-in validator implementation.
  • Listing multiple libraries without selecting a validator in every oauth HBA record.
  • Installing a validator on the primary but not on a failover target, or trusting native code whose issuer, audience, and role mapping were not reviewed.

Related parameters

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · krb_server_keyfile

References

2.14 - password_encryption

password_encryption is the PostgreSQL setting that chooses the algorithm for encrypting passwords.
Note

Fact — official short description: “Chooses the algorithm for encrypting passwords.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuemd5, scram-sha-256
— for non-enum types
Category ValueConnections and Authentication / Authentication
Upstream classification
Latest boot value Valuescram-sha-256
scram-sha-256

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.6 on — on
PG10–13 md5 — md5
PG14–19 Beta 3 scram-sha-256 — scram-sha-256

How it works

password_encryption chooses the algorithm for encrypting passwords. It affects secrets generated by CREATE ROLE, ALTER ROLE, and password-setting commands; existing stored secrets are not rehashed automatically.

password_encryption is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The final authentication path combines this setting with pg_hba.conf, role attributes, credential material, client capabilities, and sometimes operating-system identity services.

Tuning advice

Tip

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

Workload Guidance
OLTP Set password_encryption from the authentication architecture and security policy, not workload throughput. Test every driver, identity mapping, failover path, and credential-rotation procedure.
OLAP Apply the same security baseline to analytical access; isolate any legacy client exception to a dedicated role and a dated migration plan.
Small nodes Prefer the current secure default for password_encryption. Avoid weakening authentication to save marginal CPU on a small node; reduce connection churn with pooling instead.

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 scram-sha-256 same as boot {{ pg_pwd_enc|default('scram-sha-256') }}
OLAP scram-sha-256 same as boot {{ pg_pwd_enc|default('scram-sha-256') }}
CRIT scram-sha-256 same as boot {{ pg_pwd_enc|default('scram-sha-256') }}
TINY scram-sha-256 same as boot {{ pg_pwd_enc|default('scram-sha-256') }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = scram-sha-256 (dcs); OLAP: PG9.0–19 Beta 3 = scram-sha-256 (dcs); CRIT: PG9.0–19 Beta 3 = scram-sha-256 (dcs); TINY: PG9.0–19 Beta 3 = scram-sha-256 (dcs). Advice, pending human review — Editorial inference: SCRAM-SHA-256 establishes a modern password-secret baseline consistently across profiles and supported PostgreSQL releases.

Common pitfalls

  • Changing password_encryption in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Changing one authentication setting without testing pg_hba.conf ordering, existing secrets, mappings, and every client library.
  • Weakening identity policy to solve connection churn or CPU cost that should be addressed with pooling and capacity planning.
  • Changing the algorithm and assuming existing role secrets are automatically converted.

Related parameters

scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

References

2.15 - password_expiration_warning_threshold

password_expiration_warning_threshold — Threshold for password expiration warnings. Observed in PG19 Beta 3; its last measured boot default is 7 d in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Threshold for password expiration warnings.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Authentication
Upstream classification
Latest boot value Value604800
7 d

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit 1d92e0c2cc47 — Add password expiration warnings.
Commit date 2026-02-11
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 604800 s 7 d

How it works

PostgreSQL describes password_expiration_warning_threshold as follows: “Threshold for password expiration warnings.” A configuration reload applies the value to the server without a full 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.

After successful password authentication, PostgreSQL warns when a role with VALID UNTIL has less than this interval remaining. Zero disables the warning; the default seven-day window is advisory and does not create, rotate, or extend credentials, and non-password authentication does not make password expiry management automatic.

Read it together with password_encryption, authentication_timeout, md5_password_warnings, hba_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

Tip

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

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 password_expiration_warning_threshold as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

password_encryption · authentication_timeout · md5_password_warnings · hba_file

References

2.16 - port

port is the PostgreSQL setting that defines the TCP port the server listens on.
Note

Fact — official short description: “Sets the TCP port the server listens on.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value1 – 65535
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value5432
5432

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 5432 — 5432

How it works

port sets the TCP port the server listens on. One port is used for every TCP listener address and becomes part of client connection strings, service discovery, firewall rules, and health checks.

port is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

The listener endpoint combines listen_addresses and port at startup, while pg_hba.conf, TLS, firewalls, routing, and service discovery determine which clients can use it.

Tuning advice

Tip

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

Workload Guidance
OLTP Set port from the service topology and expose only required interfaces or ports. Validate poolers, health checks, pg_hba.conf, firewalls, failover, and restart sequencing together.
OLAP Use an explicit analytical endpoint or network when isolation is required, but keep connection information consistent across failover targets.
Small nodes Prefer local-only exposure unless remote access is required. Preserve a tested administrative route before changing port and restarting.

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

  • Expecting a reload or SET to activate port, although it requires a controlled server restart.
  • Assuming a bound address or port grants access; pg_hba.conf and operating-system or network controls still apply.
  • Changing a startup-only endpoint without updating discovery, health checks, firewalls, clients, and the administrative recovery path.
  • Changing port globally without a rollback plan and a client or operational compatibility test.

Related parameters

listen_addresses · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

References

2.17 - reserved_connections

reserved_connections is the PostgreSQL setting that defines the number of connection slots reserved for roles with privileges of pg_use_reserved_connections.
Note

Fact — official short description: “Sets the number of connection slots reserved for roles with privileges of pg_use_reserved_connections.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value0
0

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 6e2775e4d4e4 — Add new GUC reserved_connections.
Commit date 2023-01-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 0 — 0

How it works

reserved_connections sets the number of connection slots reserved for roles with privileges of pg_use_reserved_connections. These slots become available only to roles granted pg_use_reserved_connections and sit above ordinary capacity but below superuser-only reserves.

reserved_connections is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

reserved_connections and superuser_reserved_connections carve privileged tiers from max_connections; poolers, monitoring, replication, maintenance, and failover must all fit the same total backend budget.

Tuning advice

Tip

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

Workload Guidance
OLTP Size reserved_connections inside max_connections from the number of independent emergency actors, pooler behavior, and failover operations. Test that ordinary saturation still leaves usable administrative access.
OLAP Reserve enough slots for control, monitoring, and cancellation around heavy analytical sessions, but do not let reserves consume an excessive share of a deliberately small backend pool.
Small nodes Keep reserved_connections modest relative to max_connections while preserving at least one tested emergency path; reserved slots are capacity unavailable to ordinary clients at saturation.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Expecting a reload or SET to activate reserved_connections, although it requires a controlled server restart.
  • Counting reserved slots outside max_connections even though every tier consumes the same total ceiling.
  • Reserving too little for incident response or so much that ordinary application capacity collapses at saturation.
  • Sizing ordinary, reserved, and superuser-reserved slots without ensuring their sum fits max_connections.

Related parameters

listen_addresses · port · max_connections · superuser_reserved_connections · unix_socket_directories

References

2.18 - scram_iterations

scram_iterations is the PostgreSQL setting that defines the iteration count for SCRAM secret generation.
Note

Fact — official short description: “Sets the iteration count for SCRAM secret generation.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Authentication
Upstream classification
Latest boot value Value4096
4096

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit b577743000cd — Make SCRAM iteration count configurable
Commit date 2023-03-27
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 4096 — 4096

How it works

scram_iterations is embedded in every newly generated SCRAM-SHA-256 verifier. Raising it increases offline-guessing cost but also increases legitimate password-setting and authentication work; existing verifiers keep the iteration count with which they were created until their passwords are reset.

It is a USER-context setting, so the session that executes CREATE ROLE or ALTER ROLE determines the count written into the new verifier. Role, database, or application-specific overrides can therefore create a mixture of counts even when postgresql.conf has one value.

PostgreSQL warns that when a role’s stored count differs from the configured server value, an unauthenticated observer can distinguish response behavior and infer that the role exists. A count change therefore requires uniform session policy and rotation of all SCRAM verifiers, not only a GUC edit.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose one count through a security and authentication-latency benchmark, enforce it in every password-management session, and rotate all role passwords so stored verifiers converge. Load-test reconnect storms and failover before raising it.
OLAP Use the same count for analytical roles; workload class is not a reason to expose a distinct verifier count. Schedule credential rotation so long-lived service accounts do not retain the old count.
Small nodes Keep the upstream count unless testing justifies a change. A smaller server should reduce connection churn with pooling, but must still keep all generated verifiers at one consistent count.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing the GUC without resetting existing passwords; their verifiers retain the old count.
  • Allowing role or database session defaults to generate verifiers with counts different from postgresql.conf, creating a role-existence side channel.
  • Raising the count without load-testing authentication storms, failover, pooler reconnects, and password rotation jobs.
  • Assuming a higher count repairs weak passwords or compensates for leaked verifier material.

Related parameters

password_encryption · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

References

2.19 - ssl

ssl is the PostgreSQL setting that controls whether PostgreSQL enables SSL connections.
Note

Fact — official short description: “Enables SSL connections.”

Identity

Type Valuebool
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 Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

ssl enables SSL connections. Turning it on makes TLS listeners available when certificate and key material are valid; pg_hba.conf hostssl rules are what require TLS for selected clients.

ssl is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat ssl as transport-security policy rather than a performance knob. Follow the organization’s TLS baseline and test certificate rotation, reload, and every client class.
OLAP Use the same TLS floor for analytical traffic; benchmark only after correctness because bulk transfer may expose CPU cost but is not a reason to accept obsolete protocols.
Small nodes Keep ssl simple and secure, using managed certificates and library defaults reviewed for the installed OpenSSL version. Rehearse renewal before expiry.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = on (dcs); OLAP: PG9.0–19 Beta 3 = on (dcs); CRIT: PG9.0–19 Beta 3 = on (dcs); TINY: PG9.0–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference: All templates enable TLS so certificate-based encrypted transport is available as a uniform baseline; pg_hba.conf must still require it where policy demands.

Common pitfalls

  • Editing ssl without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

References

2.20 - ssl_ca_file

ssl_ca_file is the PostgreSQL setting that identifies the location of the SSL certificate authority file.
Note

Fact — official short description: “Location of the SSL certificate authority file.”

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 PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
Commit date 2012-02-22
Discussion —

Default history

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

How it works

ssl_ca_file identifies the location of the SSL certificate authority file. The PEM CA bundle defines trust roots for client-certificate verification and the acceptable-authority list sent during TLS negotiation.

ssl_ca_file is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Use ssl_ca_file only for a reviewed CA bundle that is intended to validate client certificates. Plan overlapping trust roots during CA rotation, restrict file writes, and test every cert/clientcert HBA path after reload.
OLAP Analytical access uses the same trust roots unless it is a deliberately separate PKI realm. Do not broaden the CA bundle to solve a client deployment problem.
Small nodes Leave it empty when client-certificate verification is not used. If enabled, keep the bundle minimal, monitored for expiry, and identical on failover nodes.

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 /pg/cert/ca.crt different '/pg/cert/ca.crt'
OLAP /pg/cert/ca.crt different '/pg/cert/ca.crt'
CRIT /pg/cert/ca.crt different '/pg/cert/ca.crt'
TINY /pg/cert/ca.crt different '/pg/cert/ca.crt'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs); OLAP: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs); CRIT: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs); TINY: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs). Advice, pending human review — Editorial inference: The common managed CA path aligns trust material across profiles and supports repeatable certificate deployment.

Common pitfalls

  • Editing ssl_ca_file without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_ca_file globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl · ssl_cert_file · ssl_key_file · ssl_crl_file · ssl_min_protocol_version

References

2.21 - ssl_cert_file

ssl_cert_file is the PostgreSQL setting that identifies the location of the SSL server certificate file.
Note

Fact — official short description: “Location of the SSL server certificate file.”

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 Valueserver.crt
server.crt

Lifecycle

Fact Value
First observed PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
Commit date 2012-02-22
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.2–19 Beta 3 server.crt — server.crt

How it works

ssl_cert_file identifies the location of the SSL server certificate file. The PEM file supplies the server leaf certificate and may include intermediate certificates needed to present a complete chain to clients.

ssl_cert_file is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Deploy a certificate whose key usage, SANs, validity, and chain match every advertised database endpoint. Test reload and a fresh client handshake before removing the previous certificate.
OLAP Analytical endpoints need the same identity guarantees; if they use a separate name, issue the correct SAN rather than reusing a mismatched certificate.
Small nodes Automate renewal and expiry alerts. A small node gains nothing from a shorter chain if clients cannot build trust; keep only the necessary leaf and intermediates.

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 /pg/cert/server.crt different '/pg/cert/server.crt'
OLAP /pg/cert/server.crt different '/pg/cert/server.crt'
CRIT /pg/cert/server.crt different '/pg/cert/server.crt'
TINY /pg/cert/server.crt different '/pg/cert/server.crt'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs); OLAP: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs); CRIT: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs); TINY: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs). Advice, pending human review — Editorial inference: The common managed server-certificate path aligns every profile with the same certificate lifecycle layout.

Common pitfalls

  • Editing ssl_cert_file without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_cert_file globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

References

2.22 - ssl_ciphers

ssl_ciphers is the PostgreSQL setting that defines the list of allowed TLSv1.2 (and lower) ciphers.
Note

Fact — official short description: “Sets the list of allowed TLSv1.2 (and lower) ciphers.”

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 ValueHIGH:MEDIUM:+3DES:!aNULL
HIGH:MEDIUM:+3DES:!aNULL

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit Not asserted: the name already exists at the 2008 Git-history boundary
Commit date ≤ 2008-01-01
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–9.2 ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH — ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
PG9.3 DEFAULT:!LOW:!EXP:!MD5:@STRENGTH — DEFAULT:!LOW:!EXP:!MD5:@STRENGTH
PG9.4–19 Beta 3 HIGH:MEDIUM:+3DES:!aNULL — HIGH:MEDIUM:+3DES:!aNULL

How it works

The ssl_ciphers name already exists in PostgreSQL’s GUC source at the project’s 2008 history boundary and in PG9.0, where it is compiled only under USE_SSL. The audited PG9.0 fallback build does not enable OpenSSL, so the name first appears in the PG9.1 official-image snapshot; that matrix boundary reflects build capability, not the feature’s original invention.

The OpenSSL cipher string governs TLS 1.2 and older handshakes. PostgreSQL 18 and later configure TLS 1.3 suites separately with ssl_tls13_ciphers. A SIGHUP reload changes the policy for new TLS contexts and connections but does not renegotiate sessions that are already established.

Treat ssl_ciphers as one part of a complete transport policy with ssl, pg_hba.conf, certificate and key files, CA and revocation settings, protocol floors and ceilings, ssl_groups, and client capabilities. Validate the exact installed OpenSSL build because accepted cipher names and security levels are library-dependent.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat ssl_ciphers as transport-security policy rather than a performance knob. Follow the organization’s TLS baseline and test certificate rotation, reload, and every client class.
OLAP Use the same TLS floor for analytical traffic; benchmark only after correctness because bulk transfer may expose CPU cost but is not a reason to accept obsolete protocols.
Small nodes Keep ssl_ciphers simple and secure, using managed certificates and library defaults reviewed for the installed OpenSSL version. Rehearse renewal before expiry.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_ciphers without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_ciphers globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

References

2.23 - ssl_crl_dir

ssl_crl_dir is the PostgreSQL setting that identifies the location of the SSL certificate revocation list directory.
Note

Fact — official short description: “Location of the SSL certificate revocation list directory.”

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 PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit f5465fade908 — Allow specifying CRL directory
Commit date 2021-02-18
Discussion thread 1

Default history

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

How it works

ssl_crl_dir names a directory of client-certificate revocation lists. OpenSSL requires hashed lookup links, so the directory must be prepared again with openssl rehash or c_rehash whenever CRLs are added or replaced. It supplements ssl_crl_file; both sources can be active.

Changing the directory path is a SIGHUP-context configuration change, but CRL files inside the configured directory are loaded on demand at connection time. A newly installed and correctly rehashed CRL can therefore be used immediately by new connections without a PostgreSQL reload.

This differs from ssl_crl_file, whose file content is loaded at server startup or configuration reload. Existing TLS sessions are not retroactively revoked by either setting; test revocation with a fresh client-certificate handshake and monitor CRL issuer, signature, and expiry.

Tuning advice

Tip

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

Workload Guidance
OLTP Manage ssl_crl_dir as an issuer-indexed CRL repository: add current CRLs, run openssl rehash or c_rehash, and test revocation with a new connection. Use it when on-demand multi-issuer updates are operationally maintained.
OLAP Analytical certificates use the same revocation repository. Do not create a separate stale directory merely because those clients connect less often.
Small nodes Keep the directory empty unless automated CRL retrieval, rehashing, expiry monitoring, and failover synchronization are in place; an unmaintained directory creates false assurance.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Adding or replacing a CRL without running openssl rehash or c_rehash, leaving it undiscoverable by OpenSSL.
  • Reloading PostgreSQL but not refreshing an expired CRL, or assuming a directory change applies retroactively to established TLS sessions.
  • Treating ssl_crl_dir like ssl_crl_file and missing that directory CRLs are loaded on demand for new connections.
  • Synchronizing the directory path but not its CRLs and hash links to every failover node.

Related parameters

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

References

2.24 - ssl_crl_file

ssl_crl_file is the PostgreSQL setting that identifies the location of the SSL certificate revocation list file.
Note

Fact — official short description: “Location of the SSL certificate revocation list file.”

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 PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
Commit date 2012-02-22
Discussion —

Default history

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

How it works

ssl_crl_file identifies the location of the SSL certificate revocation list file. The PEM revocation list is consulted when validating client certificates and must be refreshed as issuers publish new revocation state.

ssl_crl_file is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Refresh ssl_crl_file from the issuing CA before its next-update deadline, validate its signature and issuer coverage, reload PostgreSQL, and prove that a newly revoked client certificate is rejected.
OLAP Analytical clients follow the same revocation policy; do not defer CRL refresh because their sessions are longer or less frequent.
Small nodes If a managed CRL feed is unavailable, document that client-certificate revocation is not current rather than relying on a stale file. Keep the file and reload process monitored on every failover node.

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: PG9.2–19 Beta 3 unmodified; OLAP: PG9.2–19 Beta 3 unmodified; CRIT: PG9.2–19 Beta 3 unmodified; TINY: PG9.2–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_crl_file without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_crl_file globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_min_protocol_version

References

2.25 - ssl_dh_params_file

ssl_dh_params_file is the PostgreSQL setting that identifies the location of the SSL DH parameters file.
Note

Fact — official short description: “Location of the SSL DH parameters file.”

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 PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit c0a15e07cd71 — Always use 2048 bit DH parameters for OpenSSL ephemeral DH ciphers.
Commit date 2017-07-31
Discussion thread 1

Default history

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

How it works

ssl_dh_params_file identifies the location of the SSL DH parameters file. An empty string means use compiled-in default parameters. An empty value uses PostgreSQL’s compiled-in DH parameters; the file matters only for cipher suites that perform finite-field Diffie-Hellman exchange.

ssl_dh_params_file is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Use a custom ssl_dh_params_file only when finite-field ephemeral-DH cipher suites are intentionally supported and the parameters are generated by an approved current process. Test OpenSSL acceptance and reload before rollout.
OLAP Analytical throughput is not a reason to weaken DH parameters. Prefer the same reviewed key-exchange policy and measure only after client compatibility is proven.
Small nodes Leave the file empty to use PostgreSQL’s compiled-in parameters unless policy requires a managed custom set; generating or loading custom parameters does not improve capacity.

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: PG10–19 Beta 3 unmodified; OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 unmodified; TINY: PG10–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_dh_params_file without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_dh_params_file globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

References

2.26 - ssl_ecdh_curve

ssl_ecdh_curve is the PostgreSQL setting that defines the curve to use for ECDH.
Note

Fact — official short description: “Sets the curve to use for ECDH.”

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

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–17
Removed in PG18
Introduction commit 3164721462d5 — SSL: Support ECDH key exchange
Commit date 2013-12-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–17 prime256v1 — prime256v1

How it works

ssl_ecdh_curve sets the curve to use for ECDH. This single-curve control existed through PostgreSQL 17 and was replaced in PostgreSQL 18 by the multi-group ssl_groups setting.

ssl_ecdh_curve is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune ssl_ecdh_curve on PostgreSQL 18+: migrate reviewed policy to ssl_groups. On older releases, change it only with TLS-library compatibility testing.
OLAP Use the same reviewed key-exchange policy as OLTP; analytical throughput is not a reason to retain a removed single-curve control.
Small nodes Keep the supported secure default on PostgreSQL 17 and earlier, then validate the ssl_groups replacement during upgrade.

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

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

Common pitfalls

  • Editing ssl_ecdh_curve without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Leaving the removed name in PostgreSQL 18 configuration instead of migrating to ssl_groups.

Related parameters

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

References

2.27 - ssl_groups

ssl_groups is the PostgreSQL setting that defines the group(s) to use for Diffie-Hellman key exchange.
Note

Fact — official short description: “Sets the group(s) to use for Diffie-Hellman key exchange.”

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 ValueX25519:prime256v1
X25519:prime256v1

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 3d1ef3a15c3e — Support configuring multiple ECDH curves
Commit date 2024-10-24
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 X25519:prime256v1 — X25519:prime256v1

How it works

ssl_groups sets the group(s) to use for Diffie-Hellman key exchange. Multiple groups can be specified using a colon-separated list. PostgreSQL 18 accepts an ordered colon-separated list, replacing the former single ssl_ecdh_curve choice and covering supported key-exchange groups.

ssl_groups is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat ssl_groups as transport-security policy rather than a performance knob. Follow the organization’s TLS baseline and test certificate rotation, reload, and every client class.
OLAP Use the same TLS floor for analytical traffic; benchmark only after correctness because bulk transfer may expose CPU cost but is not a reason to accept obsolete protocols.
Small nodes Keep ssl_groups simple and secure, using managed certificates and library defaults reviewed for the installed OpenSSL version. Rehearse renewal before expiry.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_groups without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_groups globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers

References

2.28 - ssl_key_file

ssl_key_file is the PostgreSQL setting that identifies the location of the SSL server private key file.
Note

Fact — official short description: “Location of the SSL server private key file.”

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 Valueserver.key
server.key

Lifecycle

Fact Value
First observed PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
Commit date 2012-02-22
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.2–19 Beta 3 server.key — server.key

How it works

ssl_key_file identifies the location of the SSL server private key file. The file contains the private key matching ssl_cert_file; PostgreSQL enforces restrictive ownership and permissions before accepting it.

ssl_key_file is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep ssl_key_file owned by the PostgreSQL service account with PostgreSQL-accepted restrictive permissions, ensure it matches ssl_cert_file, and rotate it through an audited secret-delivery path.
OLAP Use the same private-key controls for analytical nodes; workload type never justifies a shared, group-writable, or copied key outside the managed PKI process.
Small nodes Prefer one managed key with expiry/renewal tests and protected backups. If it is encrypted, test ssl_passphrase_command and reload behavior before an unattended restart.

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 /pg/cert/server.key different '/pg/cert/server.key'
OLAP /pg/cert/server.key different '/pg/cert/server.key'
CRIT /pg/cert/server.key different '/pg/cert/server.key'
TINY /pg/cert/server.key different '/pg/cert/server.key'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs); OLAP: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs); CRIT: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs); TINY: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs). Advice, pending human review — Editorial inference: The common managed private-key path pairs with the server certificate and centralizes ownership and renewal conventions.

Common pitfalls

  • Editing ssl_key_file without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Installing a private key with ownership or permissions that PostgreSQL rejects, or leaking it to a readable group.

Related parameters

ssl · ssl_cert_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

References

2.29 - ssl_max_protocol_version

ssl_max_protocol_version is the PostgreSQL setting that defines the maximum SSL/TLS protocol version to use.
Note

Fact — official short description: “Sets the maximum SSL/TLS protocol version to use.”

Identity

Type Valueenum
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"", TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
— for non-enum types
Category ValueConnections and Authentication / SSL
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit e73e67c71959 — Add settings to control SSL/TLS protocol version
Commit date 2018-11-20
Discussion thread 1

Default history

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

How it works

ssl_max_protocol_version sets the maximum SSL/TLS protocol version to use. An empty value imposes no PostgreSQL-specific ceiling beyond the SSL library, while a named version can intentionally block newer protocols for compatibility testing.

ssl_max_protocol_version is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat ssl_max_protocol_version as transport-security policy rather than a performance knob. Follow the organization’s TLS baseline and test certificate rotation, reload, and every client class.
OLAP Use the same TLS floor for analytical traffic; benchmark only after correctness because bulk transfer may expose CPU cost but is not a reason to accept obsolete protocols.
Small nodes Keep ssl_max_protocol_version simple and secure, using managed certificates and library defaults reviewed for the installed OpenSSL version. Rehearse renewal before expiry.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_max_protocol_version without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_max_protocol_version globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_prefer_server_ciphers · ssl_groups

References

2.30 - ssl_min_protocol_version

ssl_min_protocol_version is the PostgreSQL setting that defines the minimum SSL/TLS protocol version to use.
Note

Fact — official short description: “Sets the minimum SSL/TLS protocol version to use.”

Identity

Type Valueenum
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 ValueTLSv1, TLSv1.1, TLSv1.2, TLSv1.3
— for non-enum types
Category ValueConnections and Authentication / SSL
Upstream classification
Latest boot value ValueTLSv1.2
TLSv1.2

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit e73e67c71959 — Add settings to control SSL/TLS protocol version
Commit date 2018-11-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12 TLSv1 — TLSv1
PG13–19 Beta 3 TLSv1.2 — TLSv1.2

How it works

ssl_min_protocol_version sets the minimum SSL/TLS protocol version to use. Connections negotiating below the floor are rejected; the upstream default moved from TLSv1 in PostgreSQL 12 to TLSv1.2 in PostgreSQL 13.

ssl_min_protocol_version is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat ssl_min_protocol_version as transport-security policy rather than a performance knob. Follow the organization’s TLS baseline and test certificate rotation, reload, and every client class.
OLAP Use the same TLS floor for analytical traffic; benchmark only after correctness because bulk transfer may expose CPU cost but is not a reason to accept obsolete protocols.
Small nodes Keep ssl_min_protocol_version simple and secure, using managed certificates and library defaults reviewed for the installed OpenSSL version. Rehearse renewal before expiry.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_min_protocol_version without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Changing ssl_min_protocol_version globally without a rollback plan and a client or operational compatibility test.

Related parameters

ssl_ciphers · ssl_tls13_ciphers · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

References

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

Related parameters

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

References

2.32 - ssl_passphrase_command_supports_reload

ssl_passphrase_command_supports_reload is the PostgreSQL setting that controls whether “ssl_passphrase_command” is called during server reload.
Note

Fact — official short description: “Controls whether “ssl_passphrase_command” is called during server reload.”

Identity

Type Valuebool
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 Valueoff
off

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

How it works

ssl_passphrase_command_supports_reload decides whether ssl_passphrase_command may be invoked during configuration reload when a replacement SSL key needs a passphrase. When it is off, the command is ignored during reload and PostgreSQL does not reload the SSL configuration if a passphrase is required.

The setting has SIGHUP context and affects replacement TLS material used by new handshakes; existing TLS sessions are not renegotiated. It should be on only when the helper is noninteractive, reliably available, and safe to invoke in the running server environment.

On Windows this setting must be on, because the Windows process model causes every connection to perform a configuration reload. That platform requirement overrides the usual Unix-oriented choice to keep a TTY-dependent helper startup-only.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable this only after ssl_passphrase_command is proven noninteractive, idempotent, fast, and available during reload; otherwise a certificate refresh can fail operationally.
OLAP Use the same reload capability across workload classes so certificate rotation behavior is predictable on every node.
Small nodes On Windows this setting must be on. On Unix, leave it off only when reload-time passphrase retrieval is unnecessary; if unattended rotation is required, enable it after testing the helper in the server environment.

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

  • Setting it to off on Windows, where PostgreSQL requires it to be on because each connection performs a configuration reload.
  • Enabling reload support while the passphrase helper is interactive, slow, unavailable, or unsafe to invoke repeatedly.
  • Assuming a reload renegotiates existing sessions; replacement TLS material affects new handshakes only.
  • Failing to inspect server logs after reload; if passphrase retrieval fails, PostgreSQL keeps the previous SSL configuration.

Related parameters

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

References

2.33 - ssl_prefer_server_ciphers

ssl_prefer_server_ciphers is the PostgreSQL setting that gives priority to server ciphersuite order.
Note

Fact — official short description: “Give priority to server ciphersuite order.”

Identity

Type Valuebool
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 Valueon
on

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit ef3267523d1e — SSL: Add configuration option to prefer server cipher order
Commit date 2013-12-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–19 Beta 3 on — on

How it works

ssl_prefer_server_ciphers gives priority to server ciphersuite order. It affects server-versus-client ordering only for TLS 1.2 and older; TLS 1.3 negotiation does not use this switch.

ssl_prefer_server_ciphers is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat ssl_prefer_server_ciphers as transport-security policy rather than a performance knob. Follow the organization’s TLS baseline and test certificate rotation, reload, and every client class.
OLAP Use the same TLS floor for analytical traffic; benchmark only after correctness because bulk transfer may expose CPU cost but is not a reason to accept obsolete protocols.
Small nodes Keep ssl_prefer_server_ciphers simple and secure, using managed certificates and library defaults reviewed for the installed OpenSSL version. Rehearse renewal before expiry.

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: PG9.4–19 Beta 3 unmodified; OLAP: PG9.4–19 Beta 3 unmodified; CRIT: PG9.4–19 Beta 3 unmodified; TINY: PG9.4–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_prefer_server_ciphers without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Assuming it controls TLS 1.3 cipher ordering.

Related parameters

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_groups

References

2.34 - ssl_renegotiation_limit

ssl_renegotiation_limit — Set the amount of traffic to send and receive before renegotiating the encryption keys. Observed in PG9.0–9.4; its last measured boot default is 0 B in PG9.4, with user context. It was removed in PG9.5.
Note

Fact — official short description: “Set the amount of traffic to send and receive before renegotiating the encryption keys.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValuekB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Security and Authentication
Upstream classification
Latest boot value Value0
0 B

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.4
Removed in PG9.5
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.4 0 kB 0 B

How it works

PostgreSQL describes ssl_renegotiation_limit as follows: “Set the amount of traffic to send and receive before renegotiating the encryption keys.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. The atlas measures it in PG9.0–9.4; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

This setting initiated TLS key renegotiation after a traffic threshold. PostgreSQL removed it in 9.5 as protocol/library behavior and security guidance moved away from renegotiation; modern TLS policy should use supported protocol versions, ciphers, certificates, and ordinary connection rotation.

Read it together with ssl_min_protocol_version, ssl_max_protocol_version, ssl_ciphers, ssl. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.4; 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: PG9.0–9.4 unmodified; OLAP: PG9.0–9.4 unmodified; CRIT: PG9.0–9.4 unmodified; TINY: PG9.0–9.4 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for ssl_renegotiation_limit as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports user context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

ssl_min_protocol_version · ssl_max_protocol_version · ssl_ciphers · ssl

References

2.35 - ssl_sni

ssl_sni — Sets whether to interpret SNI extensions in SSL connections. Observed in PG19 Beta 3; its last measured boot default is off in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets whether to interpret SNI extensions in SSL connections.”

Identity

Type Valuebool
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 Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 off — off

How it works

PostgreSQL describes ssl_sni as follows: “Sets whether to interpret SNI extensions in SSL connections.” A configuration reload applies the value to the server without a full 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.

When enabled with TLS, PostgreSQL reads the client’s Server Name Indication and selects credentials through hosts_file. Hostnames match case-insensitively; /no_sni/ and * provide explicit fallback behavior. Certificate identity, client verification, CRLs, permissions, and reload failures still require independent validation.

Read it together with hosts_file, ssl, ssl_cert_file, ssl_key_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

Tip

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

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 ssl_sni as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

hosts_file · ssl · ssl_cert_file · ssl_key_file · ssl_ca_file

References

2.36 - ssl_tls13_ciphers

ssl_tls13_ciphers is the PostgreSQL setting that defines the list of allowed TLSv1.3 cipher suites.
Note

Fact — official short description: “Sets the list of allowed TLSv1.3 cipher suites.”

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 PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 45188c2ea239 — Support configuring TLSv1.3 cipher suites
Commit date 2024-10-24
Discussion thread 1

Default history

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

How it works

ssl_tls13_ciphers sets the list of allowed TLSv1.3 cipher suites. An empty string means use the default cipher suites. An empty value delegates TLS 1.3 suite selection to the SSL library default, and the syntax is distinct from ssl_ciphers.

ssl_tls13_ciphers is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value. Existing TLS sessions are not renegotiated.

It participates in the TLS context used for new handshakes. ssl enables transport, pg_hba.conf decides which connection classes require it, and the certificate, key, CA, revocation, protocol, and cipher settings must form one valid policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat ssl_tls13_ciphers as transport-security policy rather than a performance knob. Follow the organization’s TLS baseline and test certificate rotation, reload, and every client class.
OLAP Use the same TLS floor for analytical traffic; benchmark only after correctness because bulk transfer may expose CPU cost but is not a reason to accept obsolete protocols.
Small nodes Keep ssl_tls13_ciphers simple and secure, using managed certificates and library defaults reviewed for the installed OpenSSL version. Rehearse renewal before expiry.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing ssl_tls13_ciphers without reloading configuration and verifying the effective value and subsequent behavior.
  • Updating only one TLS file or policy knob and leaving an invalid chain, unreadable key, or incompatible protocol set.
  • Assuming a reload renegotiates existing sessions; TLS policy changes affect new handshakes.
  • Using ssl_ciphers syntax or names for TLS 1.3 and unintentionally rejecting every intended suite.

Related parameters

ssl_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

References

2.37 - superuser_reserved_connections

superuser_reserved_connections is the PostgreSQL setting that defines the number of connection slots reserved for superusers.
Note

Fact — official short description: “Sets the number of connection slots reserved for superusers.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value3
3

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 3 — 3

How it works

superuser_reserved_connections sets the number of connection slots reserved for superusers. These slots are usable only after ordinary and reserved_connections capacity is exhausted, preserving an emergency path for superusers.

superuser_reserved_connections is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

reserved_connections and superuser_reserved_connections carve privileged tiers from max_connections; poolers, monitoring, replication, maintenance, and failover must all fit the same total backend budget.

Tuning advice

Tip

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

Workload Guidance
OLTP Size superuser_reserved_connections inside max_connections from the number of independent emergency actors, pooler behavior, and failover operations. Test that ordinary saturation still leaves usable administrative access.
OLAP Reserve enough slots for control, monitoring, and cancellation around heavy analytical sessions, but do not let reserves consume an excessive share of a deliberately small backend pool.
Small nodes Keep superuser_reserved_connections modest relative to max_connections while preserving at least one tested emergency path; reserved slots are capacity unavailable to ordinary clients at saturation.

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 10 different 10
OLAP 10 different 10
CRIT 10 different 10
TINY 10 different 10
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 10 (dcs); OLAP: PG9.0–19 Beta 3 = 10 (dcs); CRIT: PG9.0–19 Beta 3 = 10 (dcs); TINY: PG9.0–19 Beta 3 = 10 (dcs). Advice, pending human review — Editorial inference: Ten emergency slots preserve more operational headroom than upstream for monitoring, repair, and failover on a pooler-fronted service.

Common pitfalls

  • Expecting a reload or SET to activate superuser_reserved_connections, although it requires a controlled server restart.
  • Counting reserved slots outside max_connections even though every tier consumes the same total ceiling.
  • Reserving too little for incident response or so much that ordinary application capacity collapses at saturation.
  • Changing superuser_reserved_connections globally without a rollback plan and a client or operational compatibility test.

Related parameters

listen_addresses · port · max_connections · reserved_connections · unix_socket_directories

References

2.38 - tcp_keepalives_count

tcp_keepalives_count is the PostgreSQL setting that defines the maximum number of TCP keepalive retransmits.
Note

Fact — official short description: “Maximum number of TCP keepalive retransmits.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / TCP Settings
Upstream classification
Latest boot value Value0
0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 — 0

How it works

tcp_keepalives_count sets the maximum number of TCP keepalive retransmits. Number of consecutive keepalive retransmits that can be lost before a connection is considered dead. 0 means use the system default. Together with idle and interval, it determines how many unanswered probes precede failure; zero selects the operating-system default where supported.

tcp_keepalives_count is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The effective failure window is derived from tcp_keepalives_idle, tcp_keepalives_interval, and tcp_keepalives_count, subject to operating-system support and any shorter network-device timeout.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose tcp_keepalives_count with the other keepalive controls so total failure-detection time fits load-balancer, failover, and retry budgets. Confirm the operating system implements the requested socket option.
OLAP Long analytical connections need keepalive timing shorter than intervening network idle expiry but not so aggressive that transient loss aborts healthy jobs.
Small nodes Use operating-system defaults unless a measured network failure mode requires an override; tune the complete idle/interval/count tuple, not tcp_keepalives_count alone.

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

  • Changing tcp_keepalives_count in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Tuning one keepalive component without calculating the full idle-plus-retransmit failure window.
  • Assuming PostgreSQL’s requested value overrides unsupported platforms or a shorter firewall and load-balancer idle policy.
  • Assuming zero means no probes when it actually selects the operating-system default.

Related parameters

tcp_keepalives_idle · tcp_keepalives_interval · tcp_user_timeout · client_connection_check_interval · authentication_timeout

References

2.39 - tcp_keepalives_idle

tcp_keepalives_idle is the PostgreSQL setting that defines the interval between issuing TCP keepalives.
Note

Fact — official short description: “Time between issuing TCP keepalives.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Values
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / TCP Settings
Upstream classification
Latest boot value Value0
0 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 s 0 s

How it works

tcp_keepalives_idle defines the interval between issuing TCP keepalives. 0 means use the system default. It determines how long an otherwise idle TCP connection waits before the first keepalive probe; zero selects the operating-system default.

tcp_keepalives_idle is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The effective failure window is derived from tcp_keepalives_idle, tcp_keepalives_interval, and tcp_keepalives_count, subject to operating-system support and any shorter network-device timeout.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose tcp_keepalives_idle with the other keepalive controls so total failure-detection time fits load-balancer, failover, and retry budgets. Confirm the operating system implements the requested socket option.
OLAP Long analytical connections need keepalive timing shorter than intervening network idle expiry but not so aggressive that transient loss aborts healthy jobs.
Small nodes Use operating-system defaults unless a measured network failure mode requires an override; tune the complete idle/interval/count tuple, not tcp_keepalives_idle alone.

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

  • Changing tcp_keepalives_idle in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Tuning one keepalive component without calculating the full idle-plus-retransmit failure window.
  • Assuming PostgreSQL’s requested value overrides unsupported platforms or a shorter firewall and load-balancer idle policy.
  • Choosing a value longer than the network device’s idle timeout and never getting a useful probe first.

Related parameters

tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout

References

2.40 - tcp_keepalives_interval

tcp_keepalives_interval is the PostgreSQL setting that defines the interval between TCP keepalive retransmits.
Note

Fact — official short description: “Time between TCP keepalive retransmits.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Values
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / TCP Settings
Upstream classification
Latest boot value Value0
0 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 s 0 s

How it works

tcp_keepalives_interval defines the interval between TCP keepalive retransmits. 0 means use the system default. After probing begins, it spaces retransmissions and combines with tcp_keepalives_count to determine total failure-detection time.

tcp_keepalives_interval is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The effective failure window is derived from tcp_keepalives_idle, tcp_keepalives_interval, and tcp_keepalives_count, subject to operating-system support and any shorter network-device timeout.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose tcp_keepalives_interval with the other keepalive controls so total failure-detection time fits load-balancer, failover, and retry budgets. Confirm the operating system implements the requested socket option.
OLAP Long analytical connections need keepalive timing shorter than intervening network idle expiry but not so aggressive that transient loss aborts healthy jobs.
Small nodes Use operating-system defaults unless a measured network failure mode requires an override; tune the complete idle/interval/count tuple, not tcp_keepalives_interval alone.

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

  • Changing tcp_keepalives_interval in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Tuning one keepalive component without calculating the full idle-plus-retransmit failure window.
  • Assuming PostgreSQL’s requested value overrides unsupported platforms or a shorter firewall and load-balancer idle policy.
  • Tuning the retransmit interval without considering tcp_keepalives_count and total failure-detection time.

Related parameters

tcp_keepalives_idle · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout

References

2.41 - tcp_user_timeout

tcp_user_timeout is the PostgreSQL setting that defines the TCP user timeout.
Note

Fact — official short description: “TCP user timeout.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / TCP Settings
Upstream classification
Latest boot value Value0
0 ms

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 249d64999615 — Add support TCP user timeout in libpq and the backend server
Commit date 2019-04-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 0 ms 0 ms

How it works

tcp_user_timeout sets the TCP user timeout. 0 means use the system default. Where supported, it bounds how long transmitted data may remain unacknowledged before TCP closes the connection; it is distinct from keepalive probing of an idle connection.

tcp_user_timeout is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Tuning advice

Tip

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

Workload Guidance
OLTP Set tcp_user_timeout from the maximum acceptable unacknowledged-data stall, below the service failover budget and with client retry behavior tested.
OLAP Allow for temporary congestion during large result transfer, but keep the value below the point where an unreachable peer wastes a worker for the rest of the job window.
Small nodes Use the operating-system default unless measured half-open connections require a bound; confirm platform support before relying on it.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing tcp_user_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Forgetting that zero usually disables the timeout or delegates behavior to the operating system.
  • Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.
  • Confusing unacknowledged-data timeout with keepalive detection for an otherwise idle socket.

Related parameters

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · client_connection_check_interval · authentication_timeout

References

2.42 - unix_socket_directories

unix_socket_directories is the PostgreSQL setting that defines the directories where Unix-domain sockets will be created.
Note

Fact — official short description: “Sets the directories where Unix-domain sockets will be created.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value/var/run/postgresql
/var/run/postgresql

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit c9b0cbe98bd7 — Support having multiple Unix-domain sockets per postmaster.
Commit date 2012-08-10
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 /var/run/postgresql — /var/run/postgresql

How it works

unix_socket_directories sets the directories where Unix-domain sockets will be created. PostgreSQL creates one socket and lock file per listed directory at startup; a value beginning with @ selects an abstract namespace on supported systems.

unix_socket_directories is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Unix-socket reachability combines directory existence and traversal rights, socket group and mode, the server account, and client search paths; pg_hba.conf local records still authenticate users.

Tuning advice

Tip

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

Workload Guidance
OLTP Configure unix_socket_directories as one Unix-socket access policy: choose trusted directories, ownership, group membership, and modes, then test local poolers, monitoring, backup, and administration.
OLAP Use the same reviewed local-access boundary for analytical tools; add a directory or group only when its client and operating-system lifecycle are managed.
Small nodes Keep unix_socket_directories simple and least-privileged. A local socket avoids TCP overhead only marginally and should not be made world-accessible for convenience.

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 /var/run/postgresql, /tmp different '/var/run/postgresql, /tmp'
OLAP /var/run/postgresql, /tmp different '/var/run/postgresql, /tmp'
CRIT /var/run/postgresql, /tmp different '/var/run/postgresql, /tmp'
TINY /var/run/postgresql, /tmp different '/var/run/postgresql, /tmp'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local); OLAP: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local); CRIT: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local); TINY: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local). Advice, pending human review — Editorial inference: Providing both the distribution runtime directory and /tmp improves compatibility for local tools while retaining the conventional managed socket path.

Common pitfalls

  • Expecting a reload or SET to activate unix_socket_directories, although it requires a controlled server restart.
  • Opening the socket mode broadly while overlooking directory traversal, group membership, and pg_hba.conf local authentication.
  • Adding a volatile or missing directory and preventing server startup or confusing local clients after restart.
  • Changing unix_socket_directories globally without a rollback plan and a client or operational compatibility test.

Related parameters

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections

References

2.43 - unix_socket_directory

unix_socket_directory — Sets the directory where the Unix-domain socket will be created. Observed in PG9.0–9.2; its last measured boot default is empty string in PG9.2, with postmaster context. It was removed in PG9.3.
Note

Fact — official short description: “Sets the directory where the Unix-domain socket will be created.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.2
Removed in PG9.3
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

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

How it works

PostgreSQL describes unix_socket_directory as follows: “Sets the directory where the Unix-domain socket will be created.” The value is fixed when the server starts, so changing it requires a controlled restart. The atlas measures it in PG9.0–9.2; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

This singular path setting selected the server’s Unix-domain socket directory. PostgreSQL 9.3 replaced it with unix_socket_directories, a comma-separated list that can create sockets in multiple locations; group and permission controls remain separate.

Read it together with unix_socket_directories, unix_socket_group, unix_socket_permissions, listen_addresses. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.2; 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: PG9.0–9.2 unmodified; OLAP: PG9.0–9.2 unmodified; CRIT: PG9.0–9.2 unmodified; TINY: PG9.0–9.2 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for unix_socket_directory 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.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

unix_socket_directories · unix_socket_group · unix_socket_permissions · listen_addresses

References

2.44 - unix_socket_group

unix_socket_group is the PostgreSQL setting that defines the owning group of the Unix-domain socket.
Note

Fact — official short description: “Sets the owning group of the Unix-domain socket.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

unix_socket_group sets the owning group of filesystem Unix-domain sockets; the owning user remains the PostgreSQL server account. An empty string uses that account’s default group, and unix_socket_permissions determines which group access bits are usable.

It is a POSTMASTER-context setting, so changing it requires restart and affects sockets recreated at startup. Directory ownership and traversal rights, group membership, and pg_hba.conf local records remain separate access layers.

The setting is unsupported and ignored on Windows. It is also ignored for Linux abstract-namespace sockets selected by an @-prefixed unix_socket_directories entry, because those sockets have no filesystem owner or group.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose a dedicated operating-system group only for local tools that need socket reachability, audit its membership, and pair it with 0770-style socket and directory permissions. Test pg_hba.conf authentication separately.
OLAP Analytical tools should join the same reviewed local-access group or use TCP/TLS; do not create a broad group merely for convenience.
Small nodes Use the server account’s default group unless a managed local client requires another one. On Windows or abstract sockets, configure the actual applicable access boundary instead because this GUC is ignored.

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

  • Expecting a reload to change socket ownership; the socket is recreated only at server restart.
  • Relying on this setting on Windows or for an abstract-namespace socket, where it is ignored.
  • Granting membership in the socket group without separately enforcing pg_hba.conf authentication and database privileges.
  • Changing the socket group while directory traversal permissions still prevent intended clients from reaching it.

Related parameters

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

References

2.45 - unix_socket_permissions

unix_socket_permissions is the PostgreSQL setting that defines the access permissions of the Unix-domain socket.
Note

Fact — official short description: “Sets the access permissions of the Unix-domain socket.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 511
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueConnections and Authentication / Connection Settings
Upstream classification
Latest boot value Value511
511

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 511 — 511

How it works

unix_socket_permissions sets the chmod-style mode of filesystem Unix-domain sockets. Use a leading zero for octal notation. For a socket, only the write bit controls the ability to connect; read and execute bits do not provide meaningful additional socket access.

It is a POSTMASTER-context setting, so the mode changes only when sockets are recreated at server restart. Directory traversal permissions and unix_socket_group can form another local boundary, while pg_hba.conf local records still authenticate database users independently.

Abstract-namespace sockets have no filesystem permissions, so this setting is ignored for @-prefixed socket entries. Some operating systems also ignore socket modes entirely; the page must not present the mode as a portable replacement for directory permissions or pg_hba.conf.

Tuning advice

Tip

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

Workload Guidance
OLTP Use 0770 or 0700 only when local operating-system membership is an intentional first boundary, and verify that directory permissions and pg_hba.conf still enforce the desired policy. The portable default 0777 can be acceptable when pg_hba.conf is authoritative.
OLAP Apply the same local policy to analytical tools. Do not weaken the mode to solve a missing group or directory deployment; repair the operating-system identity path instead.
Small nodes Choose the simplest mode supported by the platform and test it after restart. For abstract sockets or systems that ignore socket modes, enforce access through the directory choice where applicable and pg_hba.conf.

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

  • Writing decimal 770 instead of octal 0770 and creating an unintended numeric mode.
  • Expecting read or execute bits to control socket connection access; only the write bit matters.
  • Relying on the mode for abstract-namespace sockets or operating systems that ignore socket permissions.
  • Treating a restrictive socket mode as a substitute for pg_hba.conf authentication, role privileges, or directory traversal controls.

Related parameters

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

References

3 - Customized Options

Complete dossiers for 1 core PostgreSQL settings in Customized Options.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

3.1 - custom_variable_classes

custom_variable_classes — Sets the list of known custom variable classes. Observed in PG9.0–9.1; its last measured boot default is not set in PG9.1, with sighup context. It was removed in PG9.2.
Note

Fact — official short description: “Sets the list of known custom variable classes.”

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 ValueCustomized Options
Upstream classification
Latest boot value Value—
not set

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.1
Removed in PG9.2
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.1 — — not set

How it works

PostgreSQL describes custom_variable_classes as follows: “Sets the list of known custom variable classes.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG9.0–9.1; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

Old releases required extensions and applications to predeclare accepted custom GUC prefixes. PostgreSQL 9.2 removed that registration mechanism; modern servers accept any two-part custom name and preserve an unrecognized placeholder until the defining extension is loaded.

Read it together with shared_preload_libraries, session_preload_libraries, config_file, allow_alter_system. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.1; 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: PG9.0–9.1 unmodified; OLAP: PG9.0–9.1 unmodified; CRIT: PG9.0–9.1 unmodified; TINY: PG9.0–9.1 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for custom_variable_classes as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

shared_preload_libraries · session_preload_libraries · config_file · allow_alter_system

References

4 - Developer Options

Complete dossiers for 27 core PostgreSQL settings in Developer Options.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

4.1 - allow_in_place_tablespaces

allow_in_place_tablespaces — Allows tablespaces directly inside pg_tblspc, for testing. Observed in PG10–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Allows tablespaces directly inside pg_tblspc, for testing.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit 7bdbbb87340f — Allow “in place” tablespaces.
Commit date 2022-07-27
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 off — off

How it works

allow_in_place_tablespaces lets a superuser create a tablespace with an empty location directly under pg_tblspc instead of using the normal external-location symbolic link. It exists to test primary and standby instances on one machine.

The directory layout violates assumptions made by backup and tablespace-management tools, which normally expect pg_tblspc entries to be links. It does not make colocated tablespaces independent storage.

The switch is consulted for the privileged CREATE TABLESPACE operation and is not a performance setting. Objects created this way can remain after the setting is turned off. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with allow_in_place_tablespaces. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify allow_in_place_tablespaces’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep allow_in_place_tablespaces at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG10–19 Beta 3 unmodified; OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 unmodified; TINY: PG10–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving allow_in_place_tablespaces enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

data_directory · wal_level · hot_standby · archive_mode

References

4.2 - allow_system_table_mods

allow_system_table_mods — Allows modifications of the structure of system tables. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Allows modifications of the structure of system tables.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

allow_system_table_mods removes protections against changing system-catalog structure and permits other normally forbidden catalog actions. Superuser status alone does not normally grant these operations.

Catalog definitions are coupled to PostgreSQL code, cache descriptors, bootstrap data, WAL, and upgrade assumptions. A superficially valid ALTER can create irreversible corruption or data loss.

The parameter exists for PostgreSQL development, bootstrap, and tightly controlled tooling. It does not provide a supported extension mechanism; extensions must use published catalog and hook interfaces. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Never use allow_system_table_mods for performance tuning. Restrict it to PostgreSQL development or a documented, disposable maintenance procedure with a verified backup and exact rollback path.
OLAP Workload type does not reduce the catalog-corruption risk from allow_system_table_mods; keep it off on analytical systems too.
Small nodes Keep allow_system_table_mods=off. Lack of a staging system is not permission to experiment on the only copy of the data.

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

  • Leaving allow_system_table_mods enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

allow_in_place_tablespaces · ignore_system_indexes · zero_damaged_pages · wal_consistency_checking

References

4.3 - backtrace_functions

backtrace_functions — Log backtrace for errors in these functions. Observed in PG13–19 Beta 3; its last measured boot default is empty string in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Log backtrace for errors in these functions.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 71a8a4f6e365 — Add backtrace support for error reporting
Commit date 2019-11-08
Discussion thread 1 · thread 2

Default history

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

How it works

backtrace_functions is a comma-separated list of internal C function names. If an error originates in a listed function, PostgreSQL appends a native backtrace to that error in the server log.

It matches C symbols, not SQL function names. Availability and symbol quality depend on platform, compiler, build flags, debug information, and whether functions were inlined.

The setting can target a narrow failure path without logging stacks for every error. Stack traces can expose implementation detail and increase log volume, so collection should be scoped and protected. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with backtrace_functions. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify backtrace_functions’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep backtrace_functions at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving backtrace_functions enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

log_error_verbosity · log_min_error_statement · compute_query_id · log_line_prefix

References

4.4 - debug_discard_caches

debug_discard_caches — Aggressively flush system caches for debugging purposes. Observed in PG14–19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Aggressively flush system caches for debugging purposes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value0 – 0
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Value0
0

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 6201fa3c166f — Rename debug_invalidate_system_caches_always to debug_discard_caches.
Commit date 2021-07-13
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 0 — 0

How it works

debug_discard_caches invalidates system-catalog cache entries at the earliest opportunity; higher values recurse the behavior. Nonzero values make the server extremely slow to expose cache invalidation bugs.

It is supported only in builds compiled with DISCARD_CACHES_ENABLED, automatically associated with –enable-cassert. Production builds keep zero and reject attempts to change it.

The parameter tests correctness under pathological cache churn. It does not flush shared_buffers, the operating-system page cache, or ordinary query result caches. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with debug_discard_caches. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify debug_discard_caches’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep debug_discard_caches at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving debug_discard_caches enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

ignore_system_indexes · shared_buffers · debug_parallel_query · allow_system_table_mods

References

4.5 - debug_io_direct

debug_io_direct — Use direct I/O for file access. Observed in PG16–19 Beta 3; its last measured boot default is empty string in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Use direct I/O for file access.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 319bae9a8da6 — Rename io_direct to debug_io_direct.
Commit date 2023-05-15
Discussion thread 1

Default history

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

How it works

debug_io_direct requests cache-bypassing file access for selected operations: data, wal, and wal_init. PostgreSQL maps this to O_DIRECT, F_NOCACHE, or FILE_FLAG_NO_BUFFERING according to platform.

The empty string disables direct I/O. Unsupported kernels or file systems can reject startup or fail operations, and alignment constraints differ across platforms.

PostgreSQL documentation explicitly describes current nondefault use as performance-reducing developer testing. It is distinct from the PG18 asynchronous-I/O method and should not be presented as a production cache policy. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with debug_io_direct. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify debug_io_direct’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep debug_io_direct at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving debug_io_direct enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

io_method · io_max_concurrency · wal_sync_method · shared_buffers · backend_flush_after

References

4.6 - debug_logical_replication_streaming

debug_logical_replication_streaming — Forces immediate streaming or serialization of changes in large transactions. Observed in PG16–19 Beta 3; its last measured boot default is buffered in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Forces immediate streaming or serialization of changes in large transactions.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuebuffered, immediate
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valuebuffered
buffered

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 39d4207e876f — Rename logical_replication_mode to debug_logical_replication_streaming
Commit date 2023-08-29
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 buffered — buffered

How it works

debug_logical_replication_streaming forces large-transaction logical replication paths to stream or serialize immediately instead of waiting for normal buffering thresholds. buffered is the production behavior.

On a publisher, immediate streams each change when subscription streaming is enabled or serializes it otherwise, bypassing the logical_decoding_work_mem trigger. On a parallel subscriber, immediate forces file serialization instead of the normal shared-memory queue path.

The two sides therefore exercise different code paths. This is a regression and fault-reproduction control, not a latency or memory tuning shortcut. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with debug_logical_replication_streaming. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify debug_logical_replication_streaming’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep debug_logical_replication_streaming at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving debug_logical_replication_streaming enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

logical_decoding_work_mem · max_logical_replication_workers · max_sync_workers_per_subscription · wal_level

References

4.7 - debug_parallel_query

debug_parallel_query — Forces the planner’s use parallel query nodes. Observed in PG16–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Forces the planner’s use parallel query nodes.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueoff, on, regress
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 5352ca22e001 — Rename force_parallel_mode to debug_parallel_query
Commit date 2023-02-15
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 off — off

How it works

debug_parallel_query forces safe queries through parallel mode even when no performance benefit is expected. on adds a top-level Gather where safe; regress also hides testing-only output differences.

Parallel-safety restrictions still apply. The forced context can expose functions incorrectly marked parallel safe and can prohibit operations such as subtransactions even when no worker is ultimately available.

It replaced the earlier force_parallel_mode name in PG16. Its purpose is regression testing, not making production queries faster or overriding all parallel cost decisions. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with debug_parallel_query. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify debug_parallel_query’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep debug_parallel_query at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving debug_parallel_query enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

force_parallel_mode · max_parallel_workers_per_gather · max_parallel_workers · parallel_setup_cost · parallel_leader_participation

References

4.8 - force_parallel_mode

force_parallel_mode — Forces use of parallel query facilities. Observed in PG9.6–15; its last measured boot default is off in PG15, with user context. It was removed in PG16.
Note

Fact — official short description: “Forces use of parallel query facilities.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueoff, on, regress
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–15
Removed in PG16
Introduction commit 7c944bd90339 — Introduce a new GUC force_parallel_mode for testing purposes.
Commit date 2016-02-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–15 off — off

How it works

Through PG15, force_parallel_mode forced otherwise safe queries to run under a Gather so parallel-mode behavior could be tested even without an expected speedup. regress suppressed output differences for regression suites.

It did not make unsafe queries safe and could impose parallel-context restrictions even when no worker ran. The top-level Gather was diagnostic overhead rather than a plan hint.

PostgreSQL 16 removed this GUC and introduced debug_parallel_query for the testing role. Upgrade configurations must delete the old name and should not automatically enable the replacement in production. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not configure force_parallel_mode on current PostgreSQL. Remove it during upgrades; use any named successor only for the same controlled developer test, not as a production default.
OLAP Analytical workload does not justify retaining the removed force_parallel_mode. Diagnose current versions with supported EXPLAIN, logs, or the documented replacement.
Small nodes Delete force_parallel_mode from modern configurations. Unknown-parameter startup failure and diagnostic overhead outweigh any historical use.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG15; 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: PG9.6–15 unmodified; OLAP: PG9.6–15 unmodified; CRIT: PG9.6–15 unmodified; TINY: PG9.6–15 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving force_parallel_mode enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

debug_parallel_query · max_parallel_workers_per_gather · max_parallel_workers · parallel_setup_cost

References

4.9 - ignore_checksum_failure

ignore_checksum_failure — Continues processing after a checksum failure. Observed in PG9.3–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Continues processing after a checksum failure.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit 96ef3b8ff1cf — Allow I/O reliability checks using 16-bit checksums
Commit date 2013-03-22
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 off — off

How it works

With data checksums enabled, a page checksum mismatch normally aborts the current transaction. ignore_checksum_failure instead emits a warning and attempts to continue if the page header is still sane.

It does not repair the page or prove remaining tuples are valid. Continuing can crash, hide or propagate corruption, and a damaged header still stops access.

The only defensible use is controlled data salvage from an immutable copy after storage and backup recovery options are exhausted. Every read under this mode is suspect evidence, not restored integrity. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Never use ignore_checksum_failure as tuning or a steady-state availability setting. Stop writes, preserve immutable copies, exhaust backup/storage repair, document expected data loss, salvage narrowly, rebuild, and validate before any return to service.
OLAP Read-only analytics does not make ignore_checksum_failure safe: corrupted pages can still poison results or structures. Use only on a disposable salvage copy with explicit acceptance of lost data.
Small nodes Do not enable ignore_checksum_failure merely because no replica exists. Preserve the original first and seek a clean backup; this switch can convert visible corruption into silent loss.

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: PG9.3–19 Beta 3 unmodified; OLAP: PG9.3–19 Beta 3 unmodified; CRIT: PG9.3–19 Beta 3 unmodified; TINY: PG9.3–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving ignore_checksum_failure enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

zero_damaged_pages · ignore_invalid_pages · data_checksums · wal_consistency_checking

References

4.10 - ignore_invalid_pages

ignore_invalid_pages — Continues recovery after an invalid pages failure. Observed in PG13–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Continues recovery after an invalid pages failure.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 41c184bc642b — Add GUC ignore_invalid_pages.
Commit date 2020-01-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 off — off

How it works

During recovery, WAL references to invalid pages normally cause PANIC and stop recovery. ignore_invalid_pages logs a warning and continues past those references.

The startup-only setting has effect only in recovery or standby mode. Skipping redo can lose data, propagate corruption, and leave structures internally inconsistent even if the server reaches a running state.

It is an emergency salvage mechanism after preserving evidence and exhausting correct restore paths. A server that starts under it must not be considered healthy or promoted into normal service. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Never use ignore_invalid_pages as tuning or a steady-state availability setting. Stop writes, preserve immutable copies, exhaust backup/storage repair, document expected data loss, salvage narrowly, rebuild, and validate before any return to service.
OLAP Read-only analytics does not make ignore_invalid_pages safe: corrupted pages can still poison results or structures. Use only on a disposable salvage copy with explicit acceptance of lost data.
Small nodes Do not enable ignore_invalid_pages merely because no replica exists. Preserve the original first and seek a clean backup; this switch can convert visible corruption into silent loss.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving ignore_invalid_pages enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

ignore_checksum_failure · zero_damaged_pages · restore_command · wal_consistency_checking

References

4.11 - ignore_system_indexes

ignore_system_indexes — Disables reading from system indexes. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with backend context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Disables reading from system indexes.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuebackend
Fixed when a backend starts
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

ignore_system_indexes makes a newly started backend read system catalogs without using their indexes, while catalog modifications still update the indexes. It is intended to recover from damaged system indexes.

Because its backend context is fixed at session start, changing the setting inside an existing session is ineffective. Catalog scans can become very slow.

The mode does not repair an index; it only creates a path to inspect data and REINDEX the damaged system index. Leaving it enabled hides symptoms and imposes broad catalog overhead. Its backend context fixes the value during connection startup; an existing session cannot change it.

Tuning advice

Tip

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

Workload Guidance
OLTP Never use ignore_system_indexes as tuning or a steady-state availability setting. Stop writes, preserve immutable copies, exhaust backup/storage repair, document expected data loss, salvage narrowly, rebuild, and validate before any return to service.
OLAP Read-only analytics does not make ignore_system_indexes safe: corrupted pages can still poison results or structures. Use only on a disposable salvage copy with explicit acceptance of lost data.
Small nodes Do not enable ignore_system_indexes merely because no replica exists. Preserve the original first and seek a clean backup; this switch can convert visible corruption into silent loss.

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

  • Leaving ignore_system_indexes enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

allow_system_table_mods · ignore_checksum_failure · zero_damaged_pages · shared_buffers

References

4.12 - jit_debugging_support

jit_debugging_support — Register JIT-compiled functions with debugger. Observed in PG11–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser-backend context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Register JIT-compiled functions with debugger.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser-backend
Fixed when a superuser backend starts
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 250bca7fc145 — Debugging and profiling support for LLVM JIT provider.
Commit date 2018-03-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 off — off

How it works

jit_debugging_support registers generated JIT functions with GDB when LLVM and the platform provide the required listener interfaces. It improves symbol visibility for debugger sessions.

The value is fixed at backend start and does not enable JIT itself. Queries still need jit, a provider, and cost thresholds to generate code.

Registration adds developer instrumentation and is useful only while debugging JIT internals or generated code. It is not a query-performance feature. Its superuser-backend context fixes the value during connection startup and restricts who may set it.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with jit_debugging_support. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify jit_debugging_support’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep jit_debugging_support at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving jit_debugging_support enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

jit · jit_above_cost · jit_dump_bitcode · jit_profiling_support · jit_expressions

References

4.13 - jit_dump_bitcode

jit_dump_bitcode — Write out LLVM bitcode to facilitate JIT debugging. Observed in PG11–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Write out LLVM bitcode to facilitate JIT debugging.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit b96d550eb03c — Support for optimizing and emitting code in LLVM JIT provider.
Commit date 2018-03-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 off — off

How it works

jit_dump_bitcode writes generated LLVM IR/bitcode files inside data_directory for queries that actually run JIT. It exists to inspect and reproduce JIT compiler behavior.

It does not activate JIT and produces nothing when no query crosses the JIT gates. Generated artifacts can accumulate, consume disk, and contain details derived from executed expressions.

Only a tightly controlled debugging session should enable it; files require explicit collection and cleanup. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with jit_dump_bitcode. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify jit_dump_bitcode’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep jit_dump_bitcode at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving jit_dump_bitcode enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

jit · jit_above_cost · jit_debugging_support · jit_profiling_support · data_directory

References

4.14 - jit_expressions

jit_expressions — Allow JIT compilation of expressions. Observed in PG11–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Allow JIT compilation of expressions.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 2a0faed9d702 — Add expression compilation support to LLVM JIT provider.
Commit date 2018-03-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 on — on

How it works

jit_expressions controls whether expression evaluation is JIT compiled after the query has already crossed the top-level JIT cost gate. It does not activate JIT by itself.

Disabling it leaves expressions interpreted while other eligible JIT work can still occur. This isolates expression-code generation for testing correctness or compilation overhead.

The setting is a developer diagnostic rather than the normal way to tune JIT; jit_above_cost and the top-level jit switch govern production selection. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with jit_expressions. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify jit_expressions’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep jit_expressions at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving jit_expressions enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

jit · jit_above_cost · jit_tuple_deforming · jit_inline_above_cost · jit_optimize_above_cost

References

4.15 - jit_profiling_support

jit_profiling_support — Register JIT-compiled functions with perf profiler. Observed in PG11–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser-backend context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Register JIT-compiled functions with perf profiler.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser-backend
Fixed when a superuser backend starts
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 250bca7fc145 — Debugging and profiling support for LLVM JIT provider.
Commit date 2018-03-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 off — off

How it works

jit_profiling_support emits registration data so Linux perf can attribute samples to JIT-generated functions when LLVM support is available. Files are written under the server user’s ~/.debug/jit directory.

The value is fixed at backend start and does not enable JIT. It only affects queries that generate code after crossing normal JIT gates.

PostgreSQL does not clean the profiling files automatically. Long-lived or busy systems can accumulate sensitive artifacts and consume disk. Its superuser-backend context fixes the value during connection startup and restricts who may set it.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with jit_profiling_support. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify jit_profiling_support’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep jit_profiling_support at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving jit_profiling_support enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

jit · jit_above_cost · jit_debugging_support · jit_dump_bitcode · data_directory

References

4.16 - jit_tuple_deforming

jit_tuple_deforming — Allow JIT compilation of tuple deforming. Observed in PG11–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Allow JIT compilation of tuple deforming.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 32af96b2b118 — JIT tuple deforming in LLVM JIT provider.
Commit date 2018-03-26
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 on — on

How it works

jit_tuple_deforming controls JIT compilation of the code that extracts attributes from PostgreSQL heap tuples after a query crosses the main JIT gate.

Disabling it leaves tuple deforming interpreted while expression JIT and other compilation can remain active. This isolates a compiler path for correctness and overhead diagnosis.

It is not an independent performance switch for every scan. Tuple layout, selected columns, row count, jit_above_cost, and total compilation time determine any effect. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with jit_tuple_deforming. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify jit_tuple_deforming’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep jit_tuple_deforming at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving jit_tuple_deforming enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

jit · jit_above_cost · jit_expressions · jit_inline_above_cost · cpu_tuple_cost

References

4.17 - post_auth_delay

post_auth_delay — Sets the amount of time to wait after authentication on connection startup. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 s in PG19 Beta 3, with backend context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the amount of time to wait after authentication on connection startup.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuebackend
Fixed when a backend starts
Unit Values
Raw unit
Range Value0 – 2147
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Value0
0 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 s 0 s

How it works

post_auth_delay pauses a newly created backend after authentication succeeds, giving a developer time to attach a debugger to that process. Zero disables the delay.

The backend-context value is fixed at session start. Authentication has completed, so the session and server resources are already allocated while it sleeps.

This intentionally increases connection latency and can consume backend slots under connection storms. It is not a throttling, security, or connection-pooling control. Its backend context fixes the value during connection startup; an existing session cannot change it.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with post_auth_delay. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify post_auth_delay’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep post_auth_delay at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving post_auth_delay enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

pre_auth_delay · authentication_timeout · max_connections · log_connections

References

4.18 - pre_auth_delay

pre_auth_delay — Sets the amount of time to wait before authentication on connection startup. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the amount of time to wait before authentication on connection startup.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value0 – 60
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Value0
0 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 s 0 s

How it works

pre_auth_delay pauses a newly forked server process before authentication so a developer can attach a debugger to handshake and authentication code. Zero disables it.

The SIGHUP setting applies to future connection startups. While a process sleeps, the client is unauthenticated and a server process and connection slot can remain occupied.

It intentionally delays every affected connection and can amplify denial-of-service exposure. It is not a replacement for authentication_timeout or network rate limiting. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with pre_auth_delay. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify pre_auth_delay’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep pre_auth_delay at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving pre_auth_delay enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

post_auth_delay · authentication_timeout · max_connections · trace_connection_negotiation

References

4.19 - remove_temp_files_after_crash

remove_temp_files_after_crash — Remove temporary files after backend crash. Observed in PG14–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Remove temporary files after backend crash.”

Identity

Type Valuebool
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 ValueDeveloper Options
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit cd91de0d1795 — Remove temporary files after backend crash
Commit date 2021-03-18
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 on — on

How it works

After a backend crash, remove_temp_files_after_crash controls whether PostgreSQL removes temporary files left by the failed process. on is the normal cleanup behavior.

Turning it off preserves artifacts for forensic debugging but repeated failures can accumulate useless files and exhaust the temporary-file file systems.

The setting does not prevent a crash, recover query state, or retain ordinary temporary tables for reuse. Any forensic retention needs explicit space monitoring and later cleanup. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with remove_temp_files_after_crash. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify remove_temp_files_after_crash’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep remove_temp_files_after_crash at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving remove_temp_files_after_crash enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

temp_file_limit · temp_tablespaces · log_temp_files · send_abort_for_crash

References

4.20 - send_abort_for_crash

send_abort_for_crash — Send SIGABRT not SIGQUIT to child processes after backend crash. Observed in PG16–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Send SIGABRT not SIGQUIT to child processes after backend crash.”

Identity

Type Valuebool
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 ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 51b5834cd53f — Provide options for postmaster to kill child processes with SIGABRT.
Commit date 2022-11-21
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 off — off

How it works

After one backend crashes, the postmaster normally asks remaining children to stop with SIGQUIT. send_abort_for_crash substitutes SIGABRT so those peer processes normally produce core dumps.

The dumps capture peer state around the incident, not just the original crashing process. Repeated crashes can therefore create many large core files.

PostgreSQL provides no automatic core-file cleanup. OS core limits, storage capacity, privacy, and a collection workflow must be configured before enabling it. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with send_abort_for_crash. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify send_abort_for_crash’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep send_abort_for_crash at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving send_abort_for_crash enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

send_abort_for_kill · remove_temp_files_after_crash · log_error_verbosity · data_directory

References

4.21 - send_abort_for_kill

send_abort_for_kill — Send SIGABRT not SIGKILL to stuck child processes. Observed in PG16–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Send SIGABRT not SIGKILL to stuck child processes.”

Identity

Type Valuebool
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 ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 51b5834cd53f — Provide options for postmaster to kill child processes with SIGABRT.
Commit date 2022-11-21
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 off — off

How it works

When a child does not exit after SIGQUIT, the postmaster normally escalates to SIGKILL after five seconds. send_abort_for_kill uses SIGABRT instead so the stuck child normally writes a core dump.

SIGABRT provides forensic state but can take time and disk space, potentially delaying crash recovery. It is not guaranteed to terminate as promptly as SIGKILL in every failure mode.

PostgreSQL does not clean generated cores. OS policy and monitoring must prevent repeated stuck processes from filling storage. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with send_abort_for_kill. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify send_abort_for_kill’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep send_abort_for_kill at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving send_abort_for_kill enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

send_abort_for_crash · remove_temp_files_after_crash · log_error_verbosity · data_directory

References

4.22 - trace_connection_negotiation

trace_connection_negotiation — Logs details of pre-authentication connection handshake. Observed in PG17–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Logs details of pre-authentication connection handshake.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 705843d294d5 — Enhance libpq encryption negotiation tests with new GUC
Commit date 2024-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 off — off

How it works

trace_connection_negotiation logs details from the pre-authentication connection negotiation path, providing evidence for protocol, encryption, and handshake debugging before normal authentication logs are available.

It is a server-start setting, so enabling it affects subsequent connection handshakes cluster-wide until restart. It does not alter authentication rules or make negotiation succeed.

Handshake logs can be high-volume and reveal network or client capability details. Use a controlled reproduction and protect the resulting server logs. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with trace_connection_negotiation. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify trace_connection_negotiation’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep trace_connection_negotiation at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving trace_connection_negotiation enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

log_connections · authentication_timeout · ssl · pre_auth_delay · log_error_verbosity

References

4.23 - trace_notify

trace_notify — Generates debugging output for LISTEN and NOTIFY. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Generates debugging output for LISTEN and NOTIFY.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

trace_notify emits extensive internal debugging messages for LISTEN and NOTIFY. Output is visible only when client_min_messages or log_min_messages includes DEBUG1 or lower.

It traces implementation activity rather than providing a durable audit of notification payloads. The extra messages can be much larger than the application notification stream.

Use it to reproduce queue and delivery bugs in a controlled session. Queue capacity and cleanup are governed separately by max_notify_queue_pages and listener transaction behavior. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with trace_notify. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify trace_notify’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep trace_notify at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving trace_notify enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

max_notify_queue_pages · notify_buffers · client_min_messages · log_min_messages · track_activities

References

4.24 - trace_recovery_messages

trace_recovery_messages — Enables logging of recovery-related debugging information. Observed in PG9.0–16; its last measured boot default is log in PG16, with sighup context. It was removed in PG17.
Note

Fact — official short description: “Enables logging of recovery-related debugging information.”

Identity

Type Valueenum
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 Valuedebug5, debug4, debug3, debug2, debug1, log, notice, warning, error
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valuelog
log

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–16
Removed in PG17
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–16 log — log

How it works

Through PG16, trace_recovery_messages remapped recovery DEBUG messages at or above a chosen severity to LOG, making normally hidden recovery internals visible during testing.

It changed message visibility, not recovery decisions, WAL replay order, or durability. Verbose recovery logging could be extremely large and timing-sensitive.

PostgreSQL 17 removed the parameter. Upgrade configurations must delete it; current recovery diagnosis should use supported logging, progress, and WAL inspection facilities. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not configure trace_recovery_messages on current PostgreSQL. Remove it during upgrades; use any named successor only for the same controlled developer test, not as a production default.
OLAP Analytical workload does not justify retaining the removed trace_recovery_messages. Diagnose current versions with supported EXPLAIN, logs, or the documented replacement.
Small nodes Delete trace_recovery_messages from modern configurations. Unknown-parameter startup failure and diagnostic overhead outweigh any historical use.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG16; 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: PG9.0–16 unmodified; OLAP: PG9.0–16 unmodified; CRIT: PG9.0–16 unmodified; TINY: PG9.0–16 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving trace_recovery_messages enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

log_min_messages · restore_command · recovery_min_apply_delay · wal_consistency_checking

References

4.25 - trace_sort

trace_sort — Emit information about resource usage in sorting. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Emit information about resource usage in sorting.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

trace_sort emits internal resource-use messages for sort operations, including memory, run generation, merge passes, and timing details useful to PostgreSQL developers.

It is diagnostic logging, not the same as EXPLAIN’s Sort Method output or log_temp_files. Enabling it can produce many messages on sort-heavy workloads.

The switch does not alter work_mem, the sorting algorithm, or spill thresholds. It should be scoped to a reproduction and paired with log-level settings that actually capture the output. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with trace_sort. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify trace_sort’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep trace_sort at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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

  • Leaving trace_sort enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

work_mem · log_temp_files · enable_sort · temp_file_limit · log_min_messages

References

4.26 - wal_consistency_checking

wal_consistency_checking — Sets the WAL resource managers for which WAL consistency checks are done. Observed in PG10–19 Beta 3; its last measured boot default is empty string in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the WAL resource managers for which WAL consistency checks are done.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit a507b86900f6 — Add WAL consistency checking facility.
Commit date 2017-02-08
Discussion —

Default history

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

How it works

wal_consistency_checking names WAL resource managers whose redo routines should be verified. For selected records, PostgreSQL includes full-page images and after replay compares the resulting buffers with those images.

Unexpected differences terminate recovery with a fatal error; known nondeterministic differences such as some hint bits are handled specially. all enables every supported resource manager.

The added full-page images can greatly increase WAL volume and replay work. This finds redo implementation bugs; it is not a general on-disk checksum, backup verification, or corruption repair tool. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune production OLTP with wal_consistency_checking. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.
OLAP Long analytical runs can amplify wal_consistency_checking’s debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.
Small nodes Keep wal_consistency_checking at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.

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: PG10–19 Beta 3 unmodified; OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 unmodified; TINY: PG10–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Leaving wal_consistency_checking enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

full_page_writes · wal_log_hints · ignore_invalid_pages · ignore_checksum_failure · wal_level

References

4.27 - zero_damaged_pages

zero_damaged_pages — Continues processing past damaged page headers. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Continues processing past damaged page headers.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueDeveloper Options
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

When PostgreSQL detects a damaged page header, zero_damaged_pages substitutes an all-zero page in memory, emits a warning, and continues. Every row formerly on that page is thereby lost to the salvage read.

The zero page is not forced to disk automatically, so continuing to use the relation can produce inconsistent behavior. The table or index must be rebuilt after salvage.

This is a last-resort data-extraction switch after backups and storage recovery are exhausted. It must be used on a preserved copy, scoped narrowly, and turned off immediately afterward. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Never use zero_damaged_pages as tuning or a steady-state availability setting. Stop writes, preserve immutable copies, exhaust backup/storage repair, document expected data loss, salvage narrowly, rebuild, and validate before any return to service.
OLAP Read-only analytics does not make zero_damaged_pages safe: corrupted pages can still poison results or structures. Use only on a disposable salvage copy with explicit acceptance of lost data.
Small nodes Do not enable zero_damaged_pages merely because no replica exists. Preserve the original first and seek a clean backup; this switch can convert visible corruption into silent loss.

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

  • Leaving zero_damaged_pages enabled after the bounded diagnostic or recovery task.
  • Running the experiment on the only copy of production data.
  • Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.
  • Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Related parameters

ignore_checksum_failure · ignore_invalid_pages · data_checksums · wal_consistency_checking

References

5 - Error Handling

Complete dossiers for 4 core PostgreSQL settings in Error Handling.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

5.1 - data_sync_retry

data_sync_retry — Whether to continue running after a failure to sync data files. Observed in PG9.4–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Whether to continue running after a failure to sync data files.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueError Handling
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit f1ff5f51d249 — PANIC on fsync() failure.
Commit date 2018-11-19
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–19 Beta 3 off — off

How it works

Whether to continue running after a failure to sync data files. The value is fixed when the server starts, so changing it requires a restart.

After a data-file fsync failure, the default behavior treats shared buffers as potentially inconsistent and raises PANIC so crash recovery re-establishes state. Continuing can lose knowledge of dirty pages and is intended only for platforms whose kernel semantics make retry safe.

Monitor and change data_sync_retry together with restart_after_crash, recovery_init_sync_method, fsync. 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

Tip

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

Workload Guidance
OLTP Change data_sync_retry only from an explicit failure model and measured evidence. Validate in a session/test environment, deploy according to its context, and retain a rollback value.
OLAP Test separately under long queries, batch jobs, and peak concurrency rather than copying OLTP assumptions to analytical nodes.
Small nodes Keep the default without a concrete problem; small systems should not trade global compatibility or failure semantics for a marginal gain.

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: PG9.4–19 Beta 3 unmodified; OLAP: PG9.4–19 Beta 3 unmodified; CRIT: PG9.4–19 Beta 3 unmodified; TINY: PG9.4–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Enabling it on a platform where fsync failure loses dirty-page knowledge.
  • Treating an I/O error as transient without replacing or fencing bad storage.
  • Optimizing availability at the expense of silent corruption.
  • Confusing the boot default of data_sync_retry with its current effective value.
  • Ignoring its postmaster context when deciding when it takes effect.

Related parameters

restart_after_crash · recovery_init_sync_method · fsync · full_page_writes · exit_on_error

References

5.2 - exit_on_error

exit_on_error — Terminate session on any error. Observed in PG9.1–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Terminate session on any error.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueError Handling
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit Not asserted: the name already exists at the 2008 Git-history boundary
Commit date ≤ 2008-01-01
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 off — off

How it works

The exit_on_error name already exists in PostgreSQL’s GUC table at this project’s 2008 Git-history boundary and in the PG9.0 source. PG9.0 marks it GUC_NO_SHOW_ALL, so it is absent from that version’s pg_settings snapshot; first observation in PG9.1 is a visibility change, not a claim that the underlying behavior was invented in PG9.1.

When enabled, an error terminates the backend session after normal error processing, not merely the current transaction. It differs from client-side stop-on-error behavior such as psql’s ON_ERROR_STOP and can discard session-local state, prepared statements, temporary objects, and an application’s connection unexpectedly.

Because it has user context, a controlled session can test the policy without changing every connection. Treat it together with restart_after_crash, transaction error handling, pooler retry behavior, statement_timeout, and idle_in_transaction_session_timeout; server termination is not a substitute for correct transaction recovery.

Tuning advice

Tip

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

Workload Guidance
OLTP Change exit_on_error only from an explicit failure model and measured evidence. Validate in a session/test environment, deploy according to its context, and retain a rollback value.
OLAP Test separately under long queries, batch jobs, and peak concurrency rather than copying OLTP assumptions to analytical nodes.
Small nodes Keep the default without a concrete problem; small systems should not trade global compatibility or failure semantics for a marginal gain.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Confusing the boot default of exit_on_error with its current effective value.
  • Ignoring its user context when deciding when it takes effect.
  • Changing several interacting settings at once and losing causal evidence.
  • Rolling out globally without testing the real failure or workload boundary.

Related parameters

restart_after_crash · statement_timeout · idle_in_transaction_session_timeout · data_sync_retry · recovery_init_sync_method

References

5.3 - recovery_init_sync_method

recovery_init_sync_method sets the method for synchronizing the data directory before crash recovery. It is a sighup setting present in PG14–18; the latest recorded boot default is fsync.
Note

Fact — official short description: “Sets the method for synchronizing the data directory before crash recovery.”

Identity

Type Valueenum
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 Valuefsync, syncfs
— for non-enum types
Category ValueError Handling
Upstream classification
Latest boot value Valuefsync
fsync

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 61752afb2640 — Provide recovery_init_sync_method=syncfs.
Commit date 2021-03-20
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 fsync — fsync

How it works

Sets the method for synchronizing the data directory before crash recovery. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Before crash recovery, PostgreSQL synchronizes the data directory so replay is not built on unflushed copied files. fsync walks files portably; where supported, syncfs can synchronize the containing filesystem more quickly but has a broader scope.

Monitor and change recovery_init_sync_method together with data_sync_retry, restart_after_crash, fsync. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Change recovery_init_sync_method only from an explicit failure model and measured evidence. Validate in a session/test environment, deploy according to its context, and retain a rollback value.
OLAP Test separately under long queries, batch jobs, and peak concurrency rather than copying OLTP assumptions to analytical nodes.
Small nodes Keep the default without a concrete problem; small systems should not trade global compatibility or failure semantics for a marginal gain.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Confusing the boot default of recovery_init_sync_method with its current effective value.
  • Ignoring its sighup context when deciding when it takes effect.
  • Changing several interacting settings at once and losing causal evidence.
  • Rolling out globally without testing the real failure or workload boundary.

Related parameters

data_sync_retry · restart_after_crash · fsync · full_page_writes · exit_on_error

References

5.4 - restart_after_crash

restart_after_crash — Reinitialize server after backend crash. Observed in PG9.1–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Reinitialize server after backend crash.”

Identity

Type Valuebool
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 ValueError Handling
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit 5ffaa9005c45 — Add restart_after_crash GUC.
Commit date 2010-07-20
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 on — on

How it works

Reinitialize server after backend crash. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

After a backend crash, the default postmaster behavior terminates sibling backends, performs crash recovery, and resumes service. Turning this off leaves restart policy to an external supervisor and converts one backend failure into a full service stop.

Monitor and change restart_after_crash together with data_sync_retry, recovery_init_sync_method, fsync. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Change restart_after_crash only from an explicit failure model and measured evidence. Validate in a session/test environment, deploy according to its context, and retain a rollback value.
OLAP Test separately under long queries, batch jobs, and peak concurrency rather than copying OLTP assumptions to analytical nodes.
Small nodes Keep the default without a concrete problem; small systems should not trade global compatibility or failure semantics for a marginal gain.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Confusing the boot default of restart_after_crash with its current effective value.
  • Ignoring its sighup context when deciding when it takes effect.
  • Changing several interacting settings at once and losing causal evidence.
  • Rolling out globally without testing the real failure or workload boundary.

Related parameters

data_sync_retry · recovery_init_sync_method · fsync · full_page_writes · exit_on_error · statement_timeout

References

6 - File Locations

Complete dossiers for 7 core PostgreSQL settings in File Locations.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

6.1 - config_file

config_file — Sets the server’s main configuration file. Observed in PG9.0–19 Beta 3; its last measured boot default is not set in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the server’s main configuration file.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueFile Locations
Upstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
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

Tip

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

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

6.2 - data_directory

data_directory — Sets the server’s data directory. Observed in PG9.0–19 Beta 3; its last measured boot default is not set in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the server’s data directory.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueFile Locations
Upstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
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

Tip

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

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

6.3 - extension_destdir

extension_destdir is a Debian/PGDG downstream staging-prefix GUC observed in the packaged PostgreSQL 9.5–17 images. It was never an upstream PostgreSQL parameter and disappears from the measured packages at PostgreSQL 18.
Note

Fact — measured pg_settings description: “Path to prepend for extension loading.”

Identity

Type Valuestring
Measured downstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueFile Locations
Measured downstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
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

Tip

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

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

6.4 - external_pid_file

external_pid_file — Writes the postmaster PID to the specified file. Observed in PG9.0–19 Beta 3; its last measured boot default is not set in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Writes the postmaster PID to the specified file.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueFile Locations
Upstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
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

Tip

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

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

6.5 - hba_file

hba_file — Sets the server’s “hba” configuration file. Observed in PG9.0–19 Beta 3; its last measured boot default is not set in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the server’s “hba” configuration file.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueFile Locations
Upstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
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

Tip

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

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.6 - hosts_file

hosts_file — Sets the server’s “hosts” configuration file. Observed in PG19 Beta 3; its last measured boot default is not set in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the server’s “hosts” configuration file.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueFile Locations
Upstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
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

Tip

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

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

6.7 - ident_file

ident_file — Sets the server’s “ident” configuration file. Observed in PG9.0–19 Beta 3; its last measured boot default is not set in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the server’s “ident” configuration file.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueFile Locations
Upstream classification
Latest boot value 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

Measured PG9.0–19 Beta 3 boot defaults
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

Tip

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

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

References

7 - Lock Management

Complete dossiers for 5 core PostgreSQL settings in Lock Management.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

7.1 - deadlock_timeout

deadlock_timeout — Sets the time to wait on a lock before checking for deadlock. Observed in PG9.0–19 Beta 3; its last measured boot default is 1 s in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the time to wait on a lock before checking for deadlock.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Valuems
Raw unit
Range Value1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueLock Management
Upstream classification
Latest boot value Value1000
1 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 1000 ms 1 s

How it works

Sets the time to wait on a lock before checking for deadlock. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

PostgreSQL waits this long before running the comparatively expensive deadlock detector. The same interval controls lock-wait logging when log_lock_waits is enabled, so lowering it improves diagnostics and deadlock response at the cost of more checks during ordinary contention.

Monitor and change deadlock_timeout together with log_lock_waits, lock_timeout, max_locks_per_transaction. Validate on the relevant server role and real workload, then use its superuser context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate deadlock_timeout from lock-wait logs, objects touched, and the concurrency bound. Fix long transactions and access ordering before adding shared memory or changing detection granularity.
OLAP Partitioned queries, bulk DDL, and SERIALIZABLE reports may touch many objects; test the worst plan, not only an average transaction.
Small nodes Defaults are usually sufficient. If raising a startup lock-table setting, account for max_connections, prepared transactions, and standby consistency together.

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 50ms different 50ms
OLAP 50ms different 50ms
CRIT 50ms different 50ms
TINY 50ms different 50ms
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 50ms (dcs); OLAP: PG9.0–19 Beta 3 = 50ms (dcs); CRIT: PG9.0–19 Beta 3 = 50ms (dcs); TINY: PG9.0–19 Beta 3 = 50ms (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to detect true deadlocks and emit lock-wait diagnostics faster than upstream; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Reading an average shared-memory sizing value as a hard per-transaction limit.
  • Raising it without the multiplier from connections and prepared transactions.
  • Expanding lock memory instead of fixing long transactions, access order, or partition explosion.
  • Ignoring compatible startup lock capacity on standbys.

Related parameters

log_lock_waits · lock_timeout · max_locks_per_transaction · max_pred_locks_per_transaction · max_pred_locks_per_page · max_pred_locks_per_relation

References

7.2 - max_locks_per_transaction

max_locks_per_transaction — Sets the maximum number of locks per transaction. Observed in PG9.0–19 Beta 3; its last measured boot default is 128 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of locks per transaction.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value10 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueLock Management
Upstream classification
Latest boot value Value128
128

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–18 64 — 64
PG19 Beta 3 128 — 128

How it works

Sets the maximum number of locks per transaction. The value is fixed when the server starts, so changing it requires a restart.

The shared lock table is sized for this average number of distinct lockable objects per backend or prepared transaction. A single transaction may exceed the number if space remains; it does not limit row locks, and standbys need a value at least as large as the primary.

Monitor and change max_locks_per_transaction together with deadlock_timeout, log_lock_waits, lock_timeout. 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

Tip

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

Workload Guidance
OLTP Calibrate max_locks_per_transaction from lock-wait logs, objects touched, and the concurrency bound. Fix long transactions and access ordering before adding shared memory or changing detection granularity.
OLAP Partitioned queries, bulk DDL, and SERIALIZABLE reports may touch many objects; test the worst plan, not only an average transaction.
Small nodes Defaults are usually sufficient. If raising a startup lock-table setting, account for max_connections, prepared transactions, and standby consistency together.

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 500 different {{ pg_max_locks_per_transaction }}
OLAP 1000 different {{ pg_max_locks_per_transaction }}
CRIT 500 different {{ pg_max_locks_per_transaction }}
TINY 250 different {{ pg_max_locks_per_transaction }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 500 (dcs); OLAP: PG9.0–19 Beta 3 = 1000 (dcs); CRIT: PG9.0–19 Beta 3 = 500 (dcs); TINY: PG9.0–19 Beta 3 = 250 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to reserve shared lock-table capacity for partition-heavy and schema-rich workloads; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Reading it as a row-lock limit or a hard limit for one transaction.
  • Raising it without accounting for max_connections and prepared transactions.
  • Setting a standby below its primary and preventing standby queries.
  • Reading an average shared-memory sizing value as a hard per-transaction limit.
  • Raising it without the multiplier from connections and prepared transactions.

Related parameters

deadlock_timeout · log_lock_waits · lock_timeout · max_pred_locks_per_transaction · max_pred_locks_per_relation · max_pred_locks_per_page

References

7.3 - max_pred_locks_per_page

max_pred_locks_per_page — Sets the maximum number of predicate-locked tuples per page. Observed in PG10–19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of predicate-locked tuples per page.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueLock Management
Upstream classification
Latest boot value Value2
2

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit c63172d60f24 — Add GUCs for predicate lock promotion thresholds.
Commit date 2017-04-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 2 — 2

How it works

Sets the maximum number of predicate-locked tuples per page. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Serializable Snapshot Isolation promotes tuple-level predicate locks to a page-level lock after this many tuples on one page. Promotion saves shared memory but increases the chance that unrelated writes appear to conflict and cause serialization failures.

Monitor and change max_pred_locks_per_page together with max_pred_locks_per_transaction, max_pred_locks_per_relation, default_transaction_isolation. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate max_pred_locks_per_page from lock-wait logs, objects touched, and the concurrency bound. Fix long transactions and access ordering before adding shared memory or changing detection granularity.
OLAP Partitioned queries, bulk DDL, and SERIALIZABLE reports may touch many objects; test the worst plan, not only an average transaction.
Small nodes Defaults are usually sufficient. If raising a startup lock-table setting, account for max_connections, prepared transactions, and standby consistency together.

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: PG10–19 Beta 3 unmodified; OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 unmodified; TINY: PG10–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Reading an average shared-memory sizing value as a hard per-transaction limit.
  • Raising it without the multiplier from connections and prepared transactions.
  • Expanding lock memory instead of fixing long transactions, access order, or partition explosion.
  • Ignoring compatible startup lock capacity on standbys.

Related parameters

max_pred_locks_per_transaction · max_pred_locks_per_relation · default_transaction_isolation · max_locks_per_transaction · deadlock_timeout

References

7.4 - max_pred_locks_per_relation

max_pred_locks_per_relation — Sets the maximum number of predicate-locked pages and tuples per relation. Observed in PG10–19 Beta 3; its last measured boot default is -2 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of predicate-locked pages and tuples per relation.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value-2147483648 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueLock Management
Upstream classification
Latest boot value Value-2
-2

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit c63172d60f24 — Add GUCs for predicate lock promotion thresholds.
Commit date 2017-04-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 -2 — -2

How it works

Sets the maximum number of predicate-locked pages and tuples per relation. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

SSI promotes page/tuple predicate locks to one relation-level lock at this threshold. A negative value means max_pred_locks_per_transaction divided by its absolute value; promotion changes granularity, not SQL lock strength.

Monitor and change max_pred_locks_per_relation together with max_pred_locks_per_transaction, max_pred_locks_per_page, default_transaction_isolation. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate max_pred_locks_per_relation from lock-wait logs, objects touched, and the concurrency bound. Fix long transactions and access ordering before adding shared memory or changing detection granularity.
OLAP Partitioned queries, bulk DDL, and SERIALIZABLE reports may touch many objects; test the worst plan, not only an average transaction.
Small nodes Defaults are usually sufficient. If raising a startup lock-table setting, account for max_connections, prepared transactions, and standby consistency together.

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: PG10–19 Beta 3 unmodified; OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 unmodified; TINY: PG10–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Reading an average shared-memory sizing value as a hard per-transaction limit.
  • Raising it without the multiplier from connections and prepared transactions.
  • Expanding lock memory instead of fixing long transactions, access order, or partition explosion.
  • Ignoring compatible startup lock capacity on standbys.

Related parameters

max_pred_locks_per_transaction · max_pred_locks_per_page · default_transaction_isolation · max_locks_per_transaction · deadlock_timeout

References

7.5 - max_pred_locks_per_transaction

max_pred_locks_per_transaction — Sets the maximum number of predicate locks per transaction. Observed in PG9.1–19 Beta 3; its last measured boot default is 64 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of predicate locks per transaction.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value10 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueLock Management
Upstream classification
Latest boot value Value64
64

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit 6a77e9385eb4 — Rename max_predicate_locks_per_transaction.
Commit date 2011-02-15
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 64 — 64

How it works

Sets the maximum number of predicate locks per transaction. The value is fixed when the server starts, so changing it requires a restart.

This sizes the shared predicate-lock table per backend or prepared transaction for SERIALIZABLE conflict tracking. It is an average shared-memory allocation rather than a hard per-transaction ceiling, and is unrelated to ordinary row-lock counts.

Monitor and change max_pred_locks_per_transaction together with deadlock_timeout, log_lock_waits, lock_timeout. 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

Tip

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

Workload Guidance
OLTP Calibrate max_pred_locks_per_transaction from lock-wait logs, objects touched, and the concurrency bound. Fix long transactions and access ordering before adding shared memory or changing detection granularity.
OLAP Partitioned queries, bulk DDL, and SERIALIZABLE reports may touch many objects; test the worst plan, not only an average transaction.
Small nodes Defaults are usually sufficient. If raising a startup lock-table setting, account for max_connections, prepared transactions, and standby consistency together.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Reading an average shared-memory sizing value as a hard per-transaction limit.
  • Raising it without the multiplier from connections and prepared transactions.
  • Expanding lock memory instead of fixing long transactions, access order, or partition explosion.
  • Ignoring compatible startup lock capacity on standbys.

Related parameters

deadlock_timeout · log_lock_waits · lock_timeout · max_locks_per_transaction · max_pred_locks_per_relation · max_pred_locks_per_page

References

8 - Preset Options

Complete dossiers for 24 core PostgreSQL settings in Preset Options.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

8.1 - block_size

block_size — Shows the size of a disk block. Observed in PG9.0–19 Beta 3; its last measured boot default is 8192 in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the size of a disk block.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value8192 – 8192
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value8192
8192

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 8192 — 8192

How it works

Shows the size of a disk block. It is read-only and cannot be changed with SET or configuration-file edits.

It reflects BLCKSZ, normally 8 KiB, chosen when PostgreSQL was built; all heap and index page layouts depend on it.

Interpret it with wal_block_size, wal_segment_size, segment_size. Applications and operations tooling may read block_size for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record block_size as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use block_size to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only block_size with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

wal_block_size · wal_segment_size · segment_size · data_checksums · server_version_num · max_function_args

References

8.2 - data_checksums

data_checksums — Shows whether data checksums are turned on for this cluster. Observed in PG9.3–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows whether data checksums are turned on for this cluster.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value""
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit 5a7e75849cb5 — Add a GUC to report whether data page checksums are enabled.
Commit date 2013-09-16
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 off — off

How it works

Reports the cluster-wide data-checksum state stored in the control file. It is internal/read-only in SQL and cannot be changed with SET.

Checksums are chosen by initdb or changed later with the server stopped by pg_checksums. PostgreSQL verifies page checksums when reading from storage and computes them when writing pages.

A checksum detects a torn or corrupted page; it does not repair it or prove that WAL, backups, memory, and every storage layer are healthy. Changes require an offline procedure, capacity for a full-cluster scan, and a verified backup.

Tuning advice

Tip

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

Workload Guidance
OLTP Treat the value as an integrity capability, not a performance knob. Prefer checksums for persistent clusters and monitor checksum failures; use a planned offline pg_checksums procedure for an existing cluster.
OLAP Budget the checksum CPU and full-cluster enable/disable scan on the actual dataset. Verify backup and replica compatibility before the offline transition.
Small nodes Enable at initdb when possible. For an existing small cluster, pg_checksums is usually simpler than a rebuild, but still requires shutdown and a recoverable backup.

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: PG9.3–19 Beta 3 unmodified; OLAP: PG9.3–19 Beta 3 unmodified; CRIT: PG9.3–19 Beta 3 unmodified; TINY: PG9.3–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to change the read-only report with SET or ALTER SYSTEM.
  • Running pg_checksums while the server is not cleanly shut down.
  • Treating a checksum failure as repairable by ignoring the error.
  • Assuming checksums validate WAL records, logical correctness, or backups by themselves.
  • Enabling checksums without monitoring checksum failures and storage health.

Related parameters

ignore_checksum_failure · zero_damaged_pages · wal_log_hints · full_page_writes · data_directory · block_size

References

8.3 - data_directory_mode

data_directory_mode shows the mode of the data directory. It is read-only metadata in PG11–18, not a runtime tuning control.
Note

Fact — official short description: “Shows the mode of the data directory.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value0 – 511
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value448
448

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit c37b3d08ca68 — Allow group access on PGDATA
Commit date 2018-04-07
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 448 — 448

How it works

Shows the mode of the data directory. It is read-only and cannot be changed with SET or configuration-file edits.

It reports the effective Unix permission mode of the data directory, commonly 0700 or group-readable 0750, in decimal pg_settings representation.

Interpret it with block_size, data_checksums, debug_assertions. Applications and operations tooling may read data_directory_mode for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record data_directory_mode as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use data_directory_mode to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only data_directory_mode with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

block_size · data_checksums · debug_assertions · huge_pages_status · in_hot_standby · integer_datetimes

References

8.4 - debug_assertions

debug_assertions — Shows whether the running server has assertion checks enabled. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows whether the running server has assertion checks enabled.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

Shows whether the running server has assertion checks enabled. It is read-only and cannot be changed with SET or configuration-file edits.

It reflects whether the server binary was built with assertion checks, a developer diagnostic that adds overhead and may abort on violated invariants.

Interpret it with server_version, server_version_num, server_encoding. Applications and operations tooling may read debug_assertions for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record debug_assertions as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use debug_assertions to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only debug_assertions with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

server_version · server_version_num · server_encoding · ssl_library · integer_datetimes · block_size

References

8.5 - debug_exec_backend

debug_exec_backend — Shows whether the running server is built with EXEC_BACKEND enabled. Observed in PG19 Beta 3; its last measured boot default is off in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows whether the running server is built with EXEC_BACKEND enabled.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit b3fe098d330f — Add GUC to show EXEC_BACKEND state
Commit date 2025-11-26
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 off — off

How it works

PostgreSQL describes debug_exec_backend as follows: “Shows whether the running server is built with EXEC_BACKEND enabled.” It is read-only state reported by PostgreSQL, not an operator-controlled tuning knob. 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.

EXEC_BACKEND creates new backends by executing a fresh server process instead of relying only on forked address-space inheritance. The reported value is determined by platform or build flags—normally true on Windows—and is useful to explain parameter propagation and platform-specific startup behavior.

Read it together with debug_assertions, server_version, server_version_num, dynamic_shared_memory_type. 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

Tip

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

Workload Guidance
OLTP Keep the upstream default until a reproducible operational need is demonstrated. Test under representative concurrency and inspect logs, latency, and the related settings before changing cluster-wide policy.
OLAP Evaluate the setting with representative long-running and batch work. Measure total runtime, resource use, log volume, and failure behavior across the whole job rather than one isolated operation.
Small nodes Minimize overrides and document rollback. A small system has less room for extra logging, workers, memory, or retained WAL, so validate the change with explicit resource limits.

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: 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 debug_exec_backend as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports internal 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

debug_assertions · server_version · server_version_num · dynamic_shared_memory_type

References

8.6 - effective_wal_level

effective_wal_level — Shows effective WAL level. Observed in PG19 Beta 3; its last measured boot default is replica in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows effective WAL level.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueminimal, replica, logical
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Valuereplica
replica

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit 67c20979ce72 — Toggle logical decoding dynamically based on logical slot presence.
Commit date 2025-12-23
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 replica — replica

How it works

PostgreSQL describes effective_wal_level as follows: “Shows effective WAL level.” It is read-only state reported by PostgreSQL, not an operator-controlled tuning knob. 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.

Unlike configured wal_level, this read-only value reports the operational logging level. PostgreSQL 19 can maintain logical-equivalent WAL when logical slots require it even if wal_level is replica, and a standby inherits the effective value from the most upstream server in its replication chain.

Read it together with wal_level, max_replication_slots, max_wal_senders, track_commit_timestamp. 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

Tip

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

Workload Guidance
OLTP Keep the upstream default until a reproducible operational need is demonstrated. Test under representative concurrency and inspect logs, latency, and the related settings before changing cluster-wide policy.
OLAP Evaluate the setting with representative long-running and batch work. Measure total runtime, resource use, log volume, and failure behavior across the whole job rather than one isolated operation.
Small nodes Minimize overrides and document rollback. A small system has less room for extra logging, workers, memory, or retained WAL, so validate the change with explicit resource limits.

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: 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 effective_wal_level as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports internal 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

wal_level · max_replication_slots · max_wal_senders · track_commit_timestamp

References

8.7 - huge_pages_status

huge_pages_status indicates the status of huge pages. It is read-only metadata in PG17–18, not a runtime tuning control.
Note

Fact — official short description: “Indicates the status of huge pages.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueoff, on, unknown
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Valueunknown
unknown

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit a14354cac0e3 — Add GUC parameter “huge_pages_status”
Commit date 2023-07-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 unknown — unknown

How it works

Reports whether the main shared-memory area actually uses explicit huge pages. It is an internal, read-only startup result with values off, on, or unknown.

The result is derived after applying huge_pages and attempting startup allocation against operating-system support and the available huge-page pool. It is not fixed by the PostgreSQL binary or initdb.

Use shared_memory_size_in_huge_pages to estimate the required pool and compare huge_pages_status with the requested huge_pages policy after every restart. Transparent Huge Pages are a separate operating-system mechanism.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable directly. If on was requested but status is off, check huge_pages policy, OS support, pool size, permissions, and startup logs; resize the OS pool before restarting.
OLAP Large shared memory can need many huge pages. Reserve the pool with headroom for the real shared_memory_size and verify NUMA placement and restart behavior on each node.
Small nodes Keep huge_pages=try unless the platform policy says otherwise. Do not reserve a large OS huge-page pool merely to make the status on for a small shared-memory area.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to SET a read-only startup result.
  • Confusing huge_pages_status with the configured huge_pages request.
  • Ignoring a too-small operating-system huge-page pool or startup allocation failure.
  • Confusing explicit PostgreSQL huge pages with Transparent Huge Pages.
  • Assuming a status from one node applies to failover nodes with different OS configuration.

Related parameters

huge_pages · shared_memory_size_in_huge_pages · shared_memory_size · shared_buffers · min_dynamic_shared_memory · dynamic_shared_memory_type

References

8.8 - in_hot_standby

in_hot_standby shows whether hot standby is currently active. It is read-only metadata in PG14–18, not a runtime tuning control.
Note

Fact — official short description: “Shows whether hot standby is currently active.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit bf8a662c9afa — Introduce a new GUC_REPORT setting “in_hot_standby”.
Commit date 2021-01-05
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 off — off

How it works

Shows whether hot standby is currently active. It is read-only and cannot be changed with SET or configuration-file edits.

It changes as recovery enters or leaves hot-standby operation and is intended for feature detection by SQL code.

Interpret it with hot_standby, max_standby_streaming_delay, hot_standby_feedback. Applications and operations tooling may read in_hot_standby for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record in_hot_standby as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use in_hot_standby to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to change read-only in_hot_standby with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

hot_standby · max_standby_streaming_delay · hot_standby_feedback · primary_conninfo · block_size · data_checksums

References

8.9 - integer_datetimes

integer_datetimes — Shows whether datetimes are integer based. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows whether datetimes are integer based.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

Shows whether datetimes are integer based. It is read-only and cannot be changed with SET or configuration-file edits.

It reports the server’s datetime representation. All measured PG9.0–19 Beta 3 builds use integer datetimes; applications should treat it as compatibility metadata.

Interpret it with server_version, server_version_num, server_encoding. Applications and operations tooling may read integer_datetimes for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record integer_datetimes as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use integer_datetimes to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only integer_datetimes with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

server_version · server_version_num · server_encoding · ssl_library · debug_assertions · block_size

References

8.10 - lc_collate

lc_collate — Shows the collation order locale. Observed in PG9.0–15; its last measured boot default is C in PG15, with internal context. It was removed in PG16.
Note

Fact — official short description: “Shows the collation order locale.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value ValueC
C

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–15
Removed in PG16
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–15 C — C

How it works

Reported the current database’s collation locale through PG15. It was an internal read-only value, not a configurable GUC, and PostgreSQL 16 removed it from pg_settings.

The collation locale is selected when a database is created and can differ between databases in one cluster. It affects ordering and comparison semantics; changing the server configuration cannot rewrite existing indexes or database locale metadata.

On PG16 and later, monitoring and applications should read the current database row in pg_database and its locale-provider-specific metadata, and use pg_collation for individual collation objects. Test collation-version changes separately from this removed reporter.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Replace SHOW/current_setting readers with a version-aware pg_database query, and regression-test indexed ordering and uniqueness when moving databases between locale providers or versions.
OLAP Record per-database provider and locale beside analytical exports. A desired collation change requires a deliberate database/object migration and possible REINDEX, not a GUC edit.
Small nodes Use the database-creation default only when it is intentional. Preserve locale metadata in inventory and backups so a rebuild does not silently choose different ordering rules.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG15; 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: PG9.0–15 unmodified; OLAP: PG9.0–15 unmodified; CRIT: PG9.0–15 unmodified; TINY: PG9.0–15 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to remove or set lc_collate in configuration even though it was always internal/read-only.
  • Assuming one cluster-wide value applies to every database.
  • Changing operating-system or ICU locale data without checking collation versions and rebuilding affected indexes.
  • Comparing text behavior across providers using only a locale name.

Related parameters

lc_ctype · server_encoding · client_encoding · icu_validation_level · default_text_search_config · server_version_num

References

8.11 - lc_ctype

lc_ctype — Shows the character classification and case conversion locale. Observed in PG9.0–15; its last measured boot default is C in PG15, with internal context. It was removed in PG16.
Note

Fact — official short description: “Shows the character classification and case conversion locale.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value ValueC
C

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–15
Removed in PG16
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–15 C — C

How it works

Reported the current database’s character-classification and case-conversion locale through PG15. It was internal/read-only and PostgreSQL 16 removed it from pg_settings.

The locale is fixed when a database is created and can differ by database. It affects locale-aware character classes and case conversion, but is not a session switch and cannot be changed with ALTER SYSTEM.

On PG16 and later, migrate SHOW/current_setting consumers to pg_database locale-provider metadata and inspect pg_collation for object-level behavior. Application tests should cover case conversion and pattern/character-class assumptions.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Migrate readers to pg_database and test case-folding, upper/lower behavior, and expression indexes before a locale/provider upgrade.
OLAP Record locale metadata with ETL outputs whose classification or normalization depends on it. Changing the locale requires deliberate migration, not a runtime setting.
Small nodes Keep locale choice explicit at database creation and in rebuild automation. Do not assume the host default is stable across images or operating-system upgrades.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG15; 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: PG9.0–15 unmodified; OLAP: PG9.0–15 unmodified; CRIT: PG9.0–15 unmodified; TINY: PG9.0–15 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to configure a value that was always internal/read-only.
  • Assuming character classification is identical across databases or locale providers.
  • Changing locale libraries without testing expression indexes and case-conversion results.
  • Migrating only monitoring text while leaving applications dependent on SHOW lc_ctype.

Related parameters

lc_collate · server_encoding · client_encoding · icu_validation_level · default_text_search_config · server_version_num

References

8.12 - max_function_args

max_function_args — Shows the maximum number of function arguments. Observed in PG9.0–19 Beta 3; its last measured boot default is 100 in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the maximum number of function arguments.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value100 – 100
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value100
100

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 100 — 100

How it works

Shows the maximum number of function arguments. It is read-only and cannot be changed with SET or configuration-file edits.

It exposes the FUNC_MAX_ARGS build constant; changing it requires a compatible custom build, not a configuration edit.

Interpret it with max_identifier_length, max_index_keys, block_size. Applications and operations tooling may read max_function_args for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record max_function_args as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use max_function_args to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only max_function_args with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

max_identifier_length · max_index_keys · block_size · server_version_num · data_checksums · data_directory_mode

References

8.13 - max_identifier_length

max_identifier_length — Shows the maximum identifier length. Observed in PG9.0–19 Beta 3; its last measured boot default is 63 in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the maximum identifier length.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value63 – 63
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value63
63

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 63 — 63

How it works

Shows the maximum identifier length. It is read-only and cannot be changed with SET or configuration-file edits.

It exposes NAMEDATALEN minus one; longer unquoted or quoted identifiers are truncated when objects are created.

Interpret it with max_function_args, max_index_keys, block_size. Applications and operations tooling may read max_identifier_length for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record max_identifier_length as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use max_identifier_length to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only max_identifier_length with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

max_function_args · max_index_keys · block_size · server_version_num · data_checksums · data_directory_mode

References

8.14 - max_index_keys

max_index_keys — Shows the maximum number of index keys. Observed in PG9.0–19 Beta 3; its last measured boot default is 32 in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the maximum number of index keys.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value32 – 32
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value32
32

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 32 — 32

How it works

Shows the maximum number of index keys. It is read-only and cannot be changed with SET or configuration-file edits.

It exposes the INDEX_MAX_KEYS build limit on index attributes, including key and INCLUDE columns where applicable.

Interpret it with max_function_args, max_identifier_length, block_size. Applications and operations tooling may read max_index_keys for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record max_index_keys as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use max_index_keys to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only max_index_keys with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

max_function_args · max_identifier_length · block_size · server_version_num · data_checksums · data_directory_mode

References

8.15 - num_os_semaphores

num_os_semaphores — Shows the number of semaphores required for the server. Observed in PG18–19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the number of semaphores required for the server.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value0
0

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 0dcaea569034 — Introduce num_os_semaphores GUC.
Commit date 2024-07-26
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 0 — 0

How it works

Shows the number of semaphores required for the server. It is read-only and cannot be changed with SET or configuration-file edits.

It is computed from the startup process and connection configuration so administrators can plan System V semaphore capacity.

Interpret it with shared_memory_size, shared_memory_size_in_huge_pages, huge_pages. Applications and operations tooling may read num_os_semaphores for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record num_os_semaphores as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use num_os_semaphores to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to change read-only num_os_semaphores with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

shared_memory_size · shared_memory_size_in_huge_pages · huge_pages · huge_pages_status · max_connections · block_size

References

8.16 - segment_size

segment_size — Shows the number of pages per disk file. Observed in PG9.0–19 Beta 3; its last measured boot default is 1 GiB (131072 × 8kB) in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the number of pages per disk file.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value8kB
Raw unit
Range Value131072 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value131072
1 GiB (131072 × 8kB)

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 131072 8kB 1 GiB (131072 × 8kB)

How it works

Shows the number of pages per disk file. It is read-only and cannot be changed with SET or configuration-file edits.

It reports the number of database pages per relation segment; together with block_size it determines the file-segmentation boundary.

Interpret it with block_size, wal_block_size, wal_segment_size. Applications and operations tooling may read segment_size for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record segment_size as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use segment_size to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only segment_size with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

block_size · wal_block_size · wal_segment_size · data_checksums · server_version_num · data_directory_mode

References

8.17 - server_encoding

server_encoding — Shows the server (database) character set encoding. Observed in PG9.0–19 Beta 3; its last measured boot default is SQL_ASCII in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the server (database) character set encoding.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value ValueSQL_ASCII
SQL_ASCII

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 SQL_ASCII — SQL_ASCII

How it works

Shows the server (database) character set encoding. It is read-only and cannot be changed with SET or configuration-file edits.

It reports the current database encoding. Encoding is selected at database creation and can differ between databases in a cluster.

Interpret it with lc_collate, lc_ctype, client_encoding. Applications and operations tooling may read server_encoding for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record server_encoding as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use server_encoding to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only server_encoding with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

lc_collate · lc_ctype · client_encoding · default_text_search_config · icu_validation_level · server_version

References

8.18 - server_version

server_version — Shows the server version. Observed in PG9.0–19 Beta 3; its last measured boot default is 19beta3 (Debian 19~beta3-1.pgdg13+1) in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the server version.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value19beta3 (Debian 19~beta3-1.pgdg13+1)
19beta3 (Debian 19~beta3-1.pgdg13+1)

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 9.0.23 — 9.0.23
PG9.1 9.1.24 — 9.1.24
PG9.2 9.2.23 — 9.2.23
PG9.3 9.3.25 — 9.3.25
PG9.4 9.4.26 — 9.4.26
PG9.5 9.5.25 — 9.5.25
PG9.6 9.6.24 — 9.6.24
PG10 10.23 (Debian 10.23-1.pgdg110+1) — 10.23 (Debian 10.23-1.pgdg110+1)
PG11 11.22 (Debian 11.22-1.pgdg120+1) — 11.22 (Debian 11.22-1.pgdg120+1)
PG12 12.22 (Debian 12.22-1.pgdg120+1) — 12.22 (Debian 12.22-1.pgdg120+1)
PG13 13.23 (Debian 13.23-1.pgdg13+1) — 13.23 (Debian 13.23-1.pgdg13+1)
PG14 14.24 (Debian 14.24-1.pgdg13+2) — 14.24 (Debian 14.24-1.pgdg13+2)
PG15 15.19 (Debian 15.19-1.pgdg13+2) — 15.19 (Debian 15.19-1.pgdg13+2)
PG16 16.15 (Debian 16.15-1.pgdg13+2) — 16.15 (Debian 16.15-1.pgdg13+2)
PG17 17.11 (Debian 17.11-1.pgdg13+2) — 17.11 (Debian 17.11-1.pgdg13+2)
PG18 18.6 (Debian 18.6-1.pgdg13+2) — 18.6 (Debian 18.6-1.pgdg13+2)
PG19 Beta 3 19beta3 (Debian 19~beta3-1.pgdg13+1) — 19beta3 (Debian 19~beta3-1.pgdg13+1)

How it works

Shows the server version. It is read-only and cannot be changed with SET or configuration-file edits.

It is the human-readable server build/version string and may include vendor packaging text; it is not safe for numeric ordering.

Interpret it with server_version_num, server_encoding, ssl_library. Applications and operations tooling may read server_version for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record server_version as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use server_version to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only server_version with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

server_version_num · server_encoding · ssl_library · integer_datetimes · debug_assertions · block_size

References

8.19 - server_version_num

server_version_num — Shows the server version as an integer. Observed in PG9.0–19 Beta 3; its last measured boot default is 190000 in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the server version as an integer.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value190000 – 190000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value190000
190000

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 90023 — 90023
PG9.1 90124 — 90124
PG9.2 90223 — 90223
PG9.3 90325 — 90325
PG9.4 90426 — 90426
PG9.5 90525 — 90525
PG9.6 90624 — 90624
PG10 100023 — 100023
PG11 110022 — 110022
PG12 120022 — 120022
PG13 130023 — 130023
PG14 140024 — 140024
PG15 150019 — 150019
PG16 160015 — 160015
PG17 170011 — 170011
PG18 180006 — 180006
PG19 Beta 3 190000 — 190000

How it works

Reports the running server binary’s version as an integer. It is internal/read-only and is determined by the binary, not by initdb or database creation.

For the measured PG9.0–19 Beta 3 releases, the integer encodes the major version and minor update so software can make numeric feature/version comparisons without parsing vendor text from server_version.

Use it for compatibility gating only when server-side feature discovery is unavailable. Extensions and clients must still account for vendor backports that do not change the upstream version number.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record it from every server after upgrade and use numeric comparisons in deployment checks; changing it means running a different PostgreSQL binary.
OLAP Verify coordinator, workers, replicas, and extension builds against the actual server version before enabling version-specific SQL or planner features.
Small nodes Use the value for simple compatibility checks, but prefer probing the required feature. Do not attempt to alter it through configuration or initdb.

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

  • Comparing the integer as a string.
  • Trying to change it with configuration or by recreating a database.
  • Assuming the number captures vendor backports and downstream patches.
  • Using a client-library version as a substitute for the connected server version.

Related parameters

server_version · server_encoding · integer_datetimes · ssl_library · max_identifier_length · block_size

References

8.20 - shared_memory_size

shared_memory_size shows the size of the server’s main shared memory area (rounded up to the nearest MB). It is read-only metadata in PG15–18, not a runtime tuning control.
Note

Fact — official short description: “Shows the size of the server’s main shared memory area (rounded up to the nearest MB).”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit ValueMB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value0
0 B

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit bd1788051b02 — Introduce GUC shared_memory_size
Commit date 2021-09-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG15–19 Beta 3 0 MB 0 B

How it works

Shows the size of the server’s main shared memory area (rounded up to the nearest MB). It is read-only and cannot be changed with SET or configuration-file edits.

It reports the rounded size of PostgreSQL’s main shared-memory segment after startup sizing.

Interpret it with shared_memory_size_in_huge_pages, huge_pages, huge_pages_status. Applications and operations tooling may read shared_memory_size for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record shared_memory_size as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use shared_memory_size to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to change read-only shared_memory_size with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

shared_memory_size_in_huge_pages · huge_pages · huge_pages_status · num_os_semaphores · max_connections · block_size

References

8.21 - shared_memory_size_in_huge_pages

shared_memory_size_in_huge_pages shows the number of huge pages needed for the main shared memory area. It is read-only metadata in PG15–18, not a runtime tuning control.
Note

Fact — official short description: “Shows the number of huge pages needed for the main shared memory area.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value-1
-1

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit 43c1c4f65eab — Introduce GUC shared_memory_size_in_huge_pages
Commit date 2021-09-21
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG15–19 Beta 3 -1 — -1

How it works

Shows the number of huge pages needed for the main shared memory area. It is read-only and cannot be changed with SET or configuration-file edits.

It estimates how many huge pages the main shared-memory segment needs and returns -1 when the platform cannot provide the estimate.

Interpret it with shared_memory_size, huge_pages, huge_pages_status. Applications and operations tooling may read shared_memory_size_in_huge_pages for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record shared_memory_size_in_huge_pages as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use shared_memory_size_in_huge_pages to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to change read-only shared_memory_size_in_huge_pages with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

shared_memory_size · huge_pages · huge_pages_status · num_os_semaphores · max_connections · block_size

References

8.22 - ssl_library

ssl_library shows the name of the SSL library. It is read-only metadata in PG12–18, not a runtime tuning control.
Note

Fact — official short description: “Shows the name of the SSL library.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value ValueOpenSSL
OpenSSL

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 98efa76fe313 — Add ssl_library preset parameter
Commit date 2018-06-26
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 OpenSSL — OpenSSL

How it works

Shows the name of the SSL library. It is read-only and cannot be changed with SET or configuration-file edits.

It reports the SSL implementation linked into the server, which helps diagnose provider-specific TLS behavior.

Interpret it with server_version, server_version_num, server_encoding. Applications and operations tooling may read ssl_library for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record ssl_library as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use ssl_library to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Trying to change read-only ssl_library with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

server_version · server_version_num · server_encoding · integer_datetimes · debug_assertions · block_size

References

8.23 - wal_block_size

wal_block_size — Shows the block size in the write ahead log. Observed in PG9.0–19 Beta 3; its last measured boot default is 8192 in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the block size in the write ahead log.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit Value—
Raw unit
Range Value8192 – 8192
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value8192
8192

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 8192 — 8192

How it works

Shows the block size in the write ahead log. It is read-only and cannot be changed with SET or configuration-file edits.

It reflects XLOG_BLCKSZ, normally 8 KiB, chosen at build time and used for WAL I/O buffers.

Interpret it with block_size, wal_segment_size, segment_size. Applications and operations tooling may read wal_block_size for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record wal_block_size as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use wal_block_size to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only wal_block_size with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

block_size · wal_segment_size · segment_size · data_checksums · server_version_num · data_directory_mode

References

8.24 - wal_segment_size

wal_segment_size — Shows the size of write ahead log segments. Observed in PG9.0–19 Beta 3; its last measured boot default is 16 MiB in PG19 Beta 3, with internal context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Shows the size of write ahead log segments.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueinternal
Internal/preset and not user-settable
Unit ValueB
Raw unit
Range Value1048576 – 1073741824
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValuePreset Options
Upstream classification
Latest boot value Value16777216
16 MiB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–10 2048 8kB 16 MiB (2048 × 8kB)
PG11–19 Beta 3 16777216 B 16 MiB

How it works

Shows the size of write ahead log segments. It is read-only and cannot be changed with SET or configuration-file edits.

It reports the WAL segment size. PostgreSQL 11 and later choose it at initdb time; older clusters normally inherit the build-time value.

Interpret it with min_wal_size, max_wal_size, wal_keep_size. Applications and operations tooling may read wal_segment_size for capability or environment detection, but cannot SET it; cross-cluster comparisons must account for build, initdb, and current-database differences.

Tuning advice

Tip

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

Workload Guidance
OLTP Not tunable. Record wal_segment_size as a deployment/capability fact; if it is unexpected, fix the binary, initdb, or database-creation process rather than trying SET.
OLAP Not tunable. Use wal_segment_size to verify format, build, or resource assumptions on analytical nodes and keep every read/write candidate compatible.
Small nodes Not tunable. Preserve it in inventory and incident reports; do not custom-build or rebuild merely to change it without a demonstrated compatibility need.

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

  • Trying to change read-only wal_segment_size with SET or a configuration file.
  • Assuming every cluster, database, or vendor build reports the same value.
  • Ignoring the value in file-format or feature-compatibility checks.
  • Treating reported metadata as a performance target instead of an environment fact.

Related parameters

min_wal_size · max_wal_size · wal_keep_size · checkpoint_timeout · checkpoint_completion_target · wal_keep_segments

References

9 - Query Tuning

Complete dossiers for 55 core PostgreSQL settings in Query Tuning.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

9.1 - constraint_exclusion

constraint_exclusion — Enables the planner to use constraints to optimize queries. Observed in PG9.0–19 Beta 3; its last measured boot default is partition in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner to use constraints to optimize queries.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuepartition, on, off
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Valuepartition
partition

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 partition — partition

How it works

constraint_exclusion lets the planner compare query predicates with CHECK constraints and omit relations whose constraints prove that they cannot match. partition limits that work to traditional inheritance children and UNION ALL arms; it is separate from declarative partition pruning.

The proof is attempted at planning time, so enabling it more broadly increases planning work even when no relation can be excluded. It relies on constraints that are visible and logically contradictory to the query conditions.

For declaratively partitioned tables, enable_partition_pruning is the primary control. constraint_exclusion remains useful for inheritance-based partitioning and carefully constructed constraint-backed UNION ALL views. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep constraint_exclusion at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.
OLAP Analytical SQL can make constraint_exclusion more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.
Small nodes On a small host, avoid increasing planning search or memory pressure through constraint_exclusion without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.

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

  • Treating constraint_exclusion as an executor resource limit rather than a planning assumption or policy.
  • Testing only one parameter set or one data distribution.
  • Expecting an already cached plan to be rewritten automatically.
  • Using a global override to hide stale statistics or fragile SQL structure.

Related parameters

enable_partition_pruning · from_collapse_limit · join_collapse_limit · default_statistics_target

References

9.2 - cpu_index_tuple_cost

cpu_index_tuple_cost — Sets the planner’s estimate of the cost of processing each index entry during an index scan. Observed in PG9.0–19 Beta 3; its last measured boot default is 0.005 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the cost of processing each index entry during an index scan.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value0.005
0.005

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0.005 — 0.005

How it works

cpu_index_tuple_cost models the CPU work to process one index entry during an index scan. It is one term in estimated path cost and does not allocate resources or change executor behavior directly.

Planner cost units are arbitrary and only their ratios matter. Scaling all cost constants together leaves path ordering unchanged; changing one alters the balance between I/O, row processing, operators, and parallel overhead.

The value is consulted when a plan is built. Statistics, row-count estimates, cache assumptions, tablespace overrides, and enabled plan methods can outweigh a small change in this constant. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate cpu_index_tuple_cost only from a representative workload, not one plan. First correct stale statistics and compare EXPLAIN (ANALYZE, BUFFERS) estimates with reality; use role or tablespace scope where possible.
OLAP Analytical workloads can justify a different CPU-versus-I/O balance, but change cpu_index_tuple_cost together with the related cost model and validate the full scan/join/aggregate mix.
Small nodes Keep the upstream value unless repeated evidence shows a systematic modeling error. On small systems, concurrency and cache residency often matter more than fine-grained changes to cpu_index_tuple_cost.

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

  • Interpreting the value as elapsed time or a hard resource limit.
  • Tuning it to repair one query and regressing the wider workload.
  • Changing cost constants before correcting statistics and cardinality estimates.
  • Forgetting that only relative values influence path choice.

Related parameters

cpu_tuple_cost · cpu_operator_cost · random_page_cost · seq_page_cost · enable_indexscan

References

9.3 - cpu_operator_cost

cpu_operator_cost — Sets the planner’s estimate of the cost of processing each operator or function call. Observed in PG9.0–19 Beta 3; its last measured boot default is 0.0025 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the cost of processing each operator or function call.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value0.0025
0.0025

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0.0025 — 0.0025

How it works

cpu_operator_cost models the CPU work for each operator or function invocation. It is one term in estimated path cost and does not allocate resources or change executor behavior directly.

Planner cost units are arbitrary and only their ratios matter. Scaling all cost constants together leaves path ordering unchanged; changing one alters the balance between I/O, row processing, operators, and parallel overhead.

The value is consulted when a plan is built. Statistics, row-count estimates, cache assumptions, tablespace overrides, and enabled plan methods can outweigh a small change in this constant. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate cpu_operator_cost only from a representative workload, not one plan. First correct stale statistics and compare EXPLAIN (ANALYZE, BUFFERS) estimates with reality; use role or tablespace scope where possible.
OLAP Analytical workloads can justify a different CPU-versus-I/O balance, but change cpu_operator_cost together with the related cost model and validate the full scan/join/aggregate mix.
Small nodes Keep the upstream value unless repeated evidence shows a systematic modeling error. On small systems, concurrency and cache residency often matter more than fine-grained changes to cpu_operator_cost.

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

  • Interpreting the value as elapsed time or a hard resource limit.
  • Tuning it to repair one query and regressing the wider workload.
  • Changing cost constants before correcting statistics and cardinality estimates.
  • Forgetting that only relative values influence path choice.

Related parameters

cpu_tuple_cost · cpu_index_tuple_cost · jit_above_cost · seq_page_cost

References

9.4 - cpu_tuple_cost

cpu_tuple_cost — Sets the planner’s estimate of the cost of processing each tuple (row). Observed in PG9.0–19 Beta 3; its last measured boot default is 0.01 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the cost of processing each tuple (row).”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value0.01
0.01

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0.01 — 0.01

How it works

cpu_tuple_cost models the CPU work to process one row. It is one term in estimated path cost and does not allocate resources or change executor behavior directly.

Planner cost units are arbitrary and only their ratios matter. Scaling all cost constants together leaves path ordering unchanged; changing one alters the balance between I/O, row processing, operators, and parallel overhead.

The value is consulted when a plan is built. Statistics, row-count estimates, cache assumptions, tablespace overrides, and enabled plan methods can outweigh a small change in this constant. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate cpu_tuple_cost only from a representative workload, not one plan. First correct stale statistics and compare EXPLAIN (ANALYZE, BUFFERS) estimates with reality; use role or tablespace scope where possible.
OLAP Analytical workloads can justify a different CPU-versus-I/O balance, but change cpu_tuple_cost together with the related cost model and validate the full scan/join/aggregate mix.
Small nodes Keep the upstream value unless repeated evidence shows a systematic modeling error. On small systems, concurrency and cache residency often matter more than fine-grained changes to cpu_tuple_cost.

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

  • Interpreting the value as elapsed time or a hard resource limit.
  • Tuning it to repair one query and regressing the wider workload.
  • Changing cost constants before correcting statistics and cardinality estimates.
  • Forgetting that only relative values influence path choice.

Related parameters

cpu_index_tuple_cost · cpu_operator_cost · seq_page_cost · random_page_cost · enable_seqscan

References

9.5 - cursor_tuple_fraction

cursor_tuple_fraction — Sets the planner’s estimate of the fraction of a cursor’s rows that will be retrieved. Observed in PG9.0–19 Beta 3; its last measured boot default is 0.1 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the fraction of a cursor’s rows that will be retrieved.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Value0.1
0.1

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0.1 — 0.1

How it works

cursor_tuple_fraction tells the planner what fraction of a cursor’s result is expected to be fetched. Lower fractions give more weight to startup cost; 1.0 plans like an ordinary query that consumes the full result.

The estimate can change join order and access paths by preferring a fast first row even when total execution would be slower. It does not stop FETCH after that fraction and is not a row limit.

It is consulted at planning time for cursor plans. Application behavior matters: cursors used for pagination, early exit, or full export have very different appropriate fractions. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep cursor_tuple_fraction at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.
OLAP Analytical SQL can make cursor_tuple_fraction more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.
Small nodes On a small host, avoid increasing planning search or memory pressure through cursor_tuple_fraction without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.

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

  • Treating cursor_tuple_fraction as an executor resource limit rather than a planning assumption or policy.
  • Testing only one parameter set or one data distribution.
  • Expecting an already cached plan to be rewritten automatically.
  • Using a global override to hide stale statistics or fragile SQL structure.

Related parameters

plan_cache_mode · random_page_cost · enable_nestloop · enable_indexscan

References

9.6 - default_statistics_target

Sets the default detail level for column statistics collected by ANALYZE when a column has no explicit target. More detail can improve cardinality estimates at the cost of collection time and catalog space.
Note

Fact — official short description: “Sets the default statistics target.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Value100
100

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 100 — 100

How it works

The target limits the number of entries in most-common-value lists and histogram bins stored for a column. The planner uses those statistics to estimate row counts, which feed access-path, join-order, and join-method decisions.

ANALYZE samples large tables rather than reading every row. Its sample size is driven by the largest statistics target among the columns being analyzed, so increasing the target raises analysis time and space roughly in proportion.

ALTER TABLE … ALTER COLUMN … SET STATISTICS overrides the global default for a column. Correlation between columns is a separate problem that normally requires CREATE STATISTICS rather than simply increasing this setting.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the global target moderate and raise it for skewed columns that actually produce row-estimate errors. Re-run ANALYZE and compare estimated versus actual rows before and after.
OLAP A higher baseline can help complex filters and joins, but use extended statistics for correlated predicates and budget the extra ANALYZE time after bulk loads.
Small nodes A modest global increase is usually inexpensive, but per-column tuning remains more precise. Do not collect deep histograms for columns never used in predicates, grouping, or ordering.

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 400 different 400
OLAP 1000 different 1000
CRIT 400 different 400
TINY 200 different 200
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 400 (dcs); OLAP: PG9.0–19 Beta 3 = 1000 (dcs); CRIT: PG9.0–19 Beta 3 = 400 (dcs); TINY: PG9.0–19 Beta 3 = 200 (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: the profiles trade progressively more ANALYZE work for better planner estimates, with OLAP emphasizing plan quality and TINY limiting collection overhead.

Common pitfalls

  • Changing the setting does not refresh existing statistics; ANALYZE must run afterward.
  • Higher single-column targets do not model cross-column correlation by themselves.
  • A high global target increases ANALYZE work even for unimportant columns.
  • Partitioned parents can require manual ANALYZE because child changes do not trigger it.
  • Approximate sampling can still produce estimation error and plan variation.

Related parameters

autovacuum_analyze_scale_factor · autovacuum_analyze_threshold · enable_partitionwise_join · plan_cache_mode · random_page_cost · effective_cache_size

References

9.7 - effective_cache_size

A planner estimate of how much PostgreSQL data cache is effectively available to one query; it changes plan costing but allocates no memory.
Note

Fact — official short description: “Sets the planner’s assumption about the total size of the data caches.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value8kB
Raw unit
Range Value1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value524288
4 GiB (524288 × 8kB)

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.3 16384 8kB 128 MiB (16384 × 8kB)
PG9.4–19 Beta 3 524288 8kB 4 GiB (524288 × 8kB)

How it works

effective_cache_size is a cost-model input. Higher values make index scans look more attractive; lower values make sequential scans more attractive.

The estimate should reflect both shared_buffers and the portion of the operating-system page cache likely to hold PostgreSQL data, while accounting for overlap and for concurrent queries sharing the same cache capacity.

Changing this parameter does not resize PostgreSQL shared memory, reserve kernel cache, or guarantee that pages remain cached between queries. Its effect is indirect, through plan selection.

Tuning advice

Tip

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

Workload Guidance
OLTP Estimate the cache actually usable by PostgreSQL after OS and co-located service needs, then validate index-heavy plans with EXPLAIN. Avoid copying a fixed percentage from a host with different concurrency or working-set behavior.
OLAP Large scans can evict or compete with cached data, so do not equate installed RAM with cache available to a single analytical query. Calibrate against representative mixed and cold-cache runs.
Small nodes Leave room for the OS and other services; a value near total RAM is usually an overstatement on a shared small host. Treat it as a planner estimate, not a memory target.

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 24576MB different {{ pg_effective_cache_size }}MB
OLAP 24576MB different {{ pg_effective_cache_size }}MB
CRIT 24576MB different {{ pg_effective_cache_size }}MB
TINY 24576MB different {{ pg_effective_cache_size }}MB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 24576MB (dcs); OLAP: PG9.0–19 Beta 3 = 24576MB (dcs); CRIT: PG9.0–19 Beta 3 = 24576MB (dcs); TINY: PG9.0–19 Beta 3 = 24576MB (dcs). Advice, pending human review — Editorial inference: using that remainder as the planner’s effective-cache estimate is a simplification that should be checked against real OS cache, overlap, co-located services, and query concurrency.

Common pitfalls

  • Expecting the setting to allocate or reserve memory.
  • Setting it equal to installed RAM without subtracting memory unavailable to PostgreSQL caching.
  • Ignoring that concurrent queries on different data sets share the effective cache.
  • Overstating it and then attributing index-heavy plan choices to unrelated cost parameters.

Related parameters

shared_buffers · random_page_cost · seq_page_cost · effective_io_concurrency · max_connections

References

9.8 - enable_async_append

enable_async_append — Enables the planner’s use of async append plans. Observed in PG14–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of async append plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 27e1f14563cf — Add support for asynchronous execution.
Commit date 2021-03-31
Discussion thread 1 · thread 2 · thread 3

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 on — on

How it works

enable_async_append controls whether the planner may choose async-aware Append, which can overlap waits while reading multiple asynchronous-capable children.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing async-aware Append, which can overlap waits while reading multiple asynchronous-capable children explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_async_append. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_async_append as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_async_append as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_parallel_append · effective_io_concurrency · io_method · enable_partition_pruning

References

9.9 - enable_bitmapscan

enable_bitmapscan — Enables the planner’s use of bitmap-scan plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of bitmap-scan plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_bitmapscan controls whether the planner may choose bitmap index and bitmap heap scans, which combine tuple locations before visiting heap pages.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing bitmap index and bitmap heap scans, which combine tuple locations before visiting heap pages explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_bitmapscan. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_bitmapscan as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_bitmapscan as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_indexscan · enable_seqscan · random_page_cost · work_mem · effective_io_concurrency

References

9.10 - enable_distinct_reordering

enable_distinct_reordering — Enables reordering of DISTINCT keys. Observed in PG18–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables reordering of DISTINCT keys.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit a8ccf4e93a7e — Reordering DISTINCT keys to match input path’s pathkeys
Commit date 2024-11-26
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 on — on

How it works

enable_distinct_reordering controls whether the planner may choose reordering DISTINCT keys to match useful input pathkeys and avoid or reduce sorting.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the PG18 default on. For a suspected regression, compare session-local plans and verify whether reordered DISTINCT keys actually match useful input pathkeys or merely trade one sort for another.
OLAP Large DISTINCT operations can benefit when reordering exploits index, merge, or existing sort order. Measure sort memory, spill volume, planning time, and total execution rather than disabling the optimization globally after one plan.
Small nodes Keep on unless a reproducible plan regression is demonstrated. If sorts spill, correct work_mem and plan inputs before treating this planner switch as a permanent hint.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_distinct_reordering as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_sort · enable_incremental_sort · enable_presorted_aggregate · work_mem

References

9.11 - enable_eager_aggregate

enable_eager_aggregate — Enables eager aggregation. Observed in PG19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables eager aggregation.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit 8e11859102f9 — Implement Eager Aggregation
Commit date 2025-10-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 on — on

How it works

PostgreSQL describes enable_eager_aggregate as follows: “Enables eager aggregation.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. 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.

Eager aggregation partially pushes aggregation below a join so fewer rows may cross the join, then finalizes the result after all relations are joined. It is considered only when estimated average group size reaches min_eager_agg_group_size; estimates, grouping semantics, memory, and alternative join paths still determine whether the planner selects it.

Read it together with min_eager_agg_group_size, enable_hashagg, enable_partitionwise_aggregate, work_mem. 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

Tip

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

Workload Guidance
OLTP Use a session-level experiment with EXPLAIN (ANALYZE, BUFFERS) and a representative parameter distribution. Keep the default unless eager aggregation consistently reduces rows and latency without plan instability.
OLAP Test joins with meaningful pre-aggregation opportunities, stale and fresh statistics, and spill pressure. Compare total CPU, peak memory, intermediate rows, and parallel plans, not just one query’s elapsed time.
Small nodes Leave planner switches and thresholds at their defaults until a repeatable regression is isolated. Fix cardinality statistics first; forcing a path globally can trade one improvement for many regressions.

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: 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 enable_eager_aggregate as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports user 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

min_eager_agg_group_size · enable_hashagg · enable_partitionwise_aggregate · work_mem · hash_mem_multiplier

References

9.12 - enable_gathermerge

enable_gathermerge — Enables the planner’s use of gather merge plans. Observed in PG10–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of gather merge plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit 355d3993c53e — Add a Gather Merge executor node.
Commit date 2017-03-09
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 on — on

How it works

enable_gathermerge controls whether the planner may choose Gather Merge, which preserves the order produced by parallel workers while merging their streams.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing Gather Merge, which preserves the order produced by parallel workers while merging their streams explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_gathermerge. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_gathermerge as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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: PG10–19 Beta 3 unmodified; OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 unmodified; TINY: PG10–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_gathermerge as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

max_parallel_workers_per_gather · enable_sort · enable_incremental_sort · parallel_leader_participation

References

9.13 - enable_group_by_reordering

enable_group_by_reordering — Enables reordering of GROUP BY keys. Observed in PG17–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables reordering of GROUP BY keys.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit db0d67db2401 — Optimize order of GROUP BY keys
Commit date 2022-03-31
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 on — on

How it works

enable_group_by_reordering controls whether the planner may choose reordering GROUP BY keys to match a child’s pathkeys and exploit preordered input.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the default on. If a plan regresses, compare session-local on/off plans and check whether reordered GROUP BY keys exploit a child’s existing pathkeys or add planning work without avoiding a sort.
OLAP Large groupings can benefit from index or presorted input order. Evaluate sort and aggregate nodes, spill, planning time, and result ordering requirements before changing the switch for a reporting role.
Small nodes Keep on unless a repeatable regression is isolated. Resolve stale statistics, missing ordering paths, and work_mem pressure before using off as a scoped workaround.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_group_by_reordering as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_sort · enable_incremental_sort · enable_hashagg · enable_presorted_aggregate

References

9.14 - enable_hashagg

enable_hashagg — Enables the planner’s use of hashed aggregation plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of hashed aggregation plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_hashagg controls whether the planner may choose hashed aggregation, which groups rows in hash tables instead of sorted streams.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing hashed aggregation, which groups rows in hash tables instead of sorted streams explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_hashagg. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_hashagg as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_hashagg as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

work_mem · hash_mem_multiplier · enable_sort · enable_partitionwise_aggregate

References

9.15 - enable_hashjoin

enable_hashjoin — Enables the planner’s use of hash join plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of hash join plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_hashjoin controls whether the planner may choose hash joins, which build a hash table for one input and probe it with the other.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing hash joins, which build a hash table for one input and probe it with the other explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_hashjoin. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_hashjoin as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_hashjoin as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

work_mem · hash_mem_multiplier · enable_parallel_hash · enable_mergejoin · enable_nestloop

References

9.16 - enable_incremental_sort

enable_incremental_sort — Enables the planner’s use of incremental sort steps. Observed in PG13–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of incremental sort steps.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 94e454cddfba — Rename enable_incrementalsort for clarity
Commit date 2020-07-05
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 on — on

How it works

enable_incremental_sort controls whether the planner may choose incremental sort, which sorts within groups that are already ordered by a prefix of the required keys.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing incremental sort, which sorts within groups that are already ordered by a prefix of the required keys explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_incremental_sort. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_incremental_sort as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_incremental_sort as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_sort · enable_gathermerge · work_mem · enable_presorted_aggregate

References

9.17 - enable_indexonlyscan

enable_indexonlyscan — Enables the planner’s use of index-only-scan plans. Observed in PG9.2–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of index-only-scan plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit a2822fb9337a — Support index-only scans using the visibility map to avoid heap fetches.
Commit date 2011-10-07
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.2–19 Beta 3 on — on

How it works

enable_indexonlyscan controls whether the planner may choose index-only scans, which can return index tuples without heap reads when visibility information permits.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

It has no effect unless enable_indexscan is also on, and heap visits still occur for pages not marked all-visible. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing index-only scans, which can return index tuples without heap reads when visibility information permits explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_indexonlyscan. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_indexonlyscan as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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: PG9.2–19 Beta 3 unmodified; OLAP: PG9.2–19 Beta 3 unmodified; CRIT: PG9.2–19 Beta 3 unmodified; TINY: PG9.2–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_indexonlyscan as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • It has no effect unless enable_indexscan is also on, and heap visits still occur for pages not marked all-visible.

Related parameters

enable_indexscan · enable_bitmapscan · enable_seqscan · random_page_cost · track_counts

References

9.18 - enable_indexscan

enable_indexscan — Enables the planner’s use of index-scan plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of index-scan plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_indexscan controls whether the planner may choose ordinary index scans; this switch also gates consideration of index-only scans.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing ordinary index scans; this switch also gates consideration of index-only scans explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_indexscan. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_indexscan as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_indexscan as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_indexonlyscan · enable_bitmapscan · enable_seqscan · random_page_cost · effective_cache_size

References

9.19 - enable_material

enable_material — Enables the planner’s use of materialization. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of materialization.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_material controls whether the planner may choose planner-inserted Materialize nodes that preserve an input for rescans or isolate execution properties.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

Turning it off cannot remove materialization that is required for correctness; it only prevents optional planner insertion. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing planner-inserted Materialize nodes that preserve an input for rescans or isolate execution properties explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_material. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_material as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_material as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • Turning it off cannot remove materialization that is required for correctness; it only prevents optional planner insertion.

Related parameters

work_mem · temp_file_limit · enable_memoize · enable_nestloop

References

9.20 - enable_memoize

enable_memoize — Enables the planner’s use of memoization. Observed in PG14–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of memoization.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 47ca4836441d — Change the name of the Result Cache node to Memoize
Commit date 2021-07-14
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 on — on

How it works

enable_memoize controls whether the planner may choose Memoize nodes that cache parameterized inner-scan results inside nested-loop joins.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing Memoize nodes that cache parameterized inner-scan results inside nested-loop joins explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_memoize. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_memoize as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_memoize as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_nestloop · work_mem · enable_material · cpu_operator_cost

References

9.21 - enable_mergejoin

enable_mergejoin — Enables the planner’s use of merge join plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of merge join plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_mergejoin controls whether the planner may choose merge joins, which consume inputs ordered on compatible join keys.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing merge joins, which consume inputs ordered on compatible join keys explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_mergejoin. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_mergejoin as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_mergejoin as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_hashjoin · enable_nestloop · enable_sort · enable_indexscan · work_mem

References

9.22 - enable_nestloop

enable_nestloop — Enables the planner’s use of nested-loop join plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of nested-loop join plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_nestloop controls whether the planner may choose nested-loop joins, including parameterized inner scans that may be best for small outer relations.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

Turning it off only discourages nested loops because some joins have no other correct implementation. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing nested-loop joins, including parameterized inner scans that may be best for small outer relations explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_nestloop. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_nestloop as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_nestloop as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • Turning it off only discourages nested loops because some joins have no other correct implementation.

Related parameters

enable_hashjoin · enable_mergejoin · enable_memoize · random_page_cost · work_mem

References

9.23 - enable_parallel_append

enable_parallel_append — Enables the planner’s use of parallel append plans. Observed in PG11–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of parallel append plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit ab7271677812 — Support Parallel Append plan nodes.
Commit date 2017-12-05
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 on — on

How it works

enable_parallel_append controls whether the planner may choose parallel-aware Append, allowing workers to divide work across child plans.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing parallel-aware Append, allowing workers to divide work across child plans explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_parallel_append. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_parallel_append as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_parallel_append as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_async_append · max_parallel_workers_per_gather · enable_partition_pruning · parallel_leader_participation

References

9.24 - enable_parallel_hash

enable_parallel_hash — Enables the planner’s use of parallel hash plans. Observed in PG11–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of parallel hash plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 1804284042e6 — Add parallel-aware hash joins.
Commit date 2017-12-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 on — on

How it works

enable_parallel_hash controls whether the planner may choose parallel hash, in which workers cooperate to build and probe a shared hash table.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

It has no effect when enable_hashjoin is off and also depends on a parallel-safe plan and available workers. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing parallel hash, in which workers cooperate to build and probe a shared hash table explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_parallel_hash. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_parallel_hash as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_parallel_hash as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • It has no effect when enable_hashjoin is off and also depends on a parallel-safe plan and available workers.

Related parameters

enable_hashjoin · max_parallel_workers_per_gather · work_mem · hash_mem_multiplier

References

9.25 - enable_partition_pruning

enable_partition_pruning — Enables plan-time and execution-time partition pruning. Observed in PG11–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables plan-time and execution-time partition pruning.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 055fb8d33da6 — Add GUC enable_partition_pruning
Commit date 2018-04-23
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 on — on

How it works

enable_partition_pruning controls whether the planner may choose plan-time and execution-time elimination of partitions contradicted by query predicates.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing plan-time and execution-time elimination of partitions contradicted by query predicates explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_partition_pruning. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_partition_pruning as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_partition_pruning as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

constraint_exclusion · enable_partitionwise_join · enable_partitionwise_aggregate · plan_cache_mode

References

9.26 - enable_partitionwise_aggregate

enable_partitionwise_aggregate — Enables partitionwise aggregation and grouping. Observed in PG11–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables partitionwise aggregation and grouping.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit e2f1eb0ee30d — Implement partition-wise grouping/aggregation.
Commit date 2018-03-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 off — off

How it works

enable_partitionwise_aggregate controls whether the planner may choose per-partition grouping or aggregation, with later finalization when grouping keys do not contain partition keys.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

It can multiply work_mem-limited nodes and planning effort roughly with the number of participating partitions. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing per-partition grouping or aggregation, with later finalization when grouping keys do not contain partition keys explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_partitionwise_aggregate. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_partitionwise_aggregate as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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 on different 'on'
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 = on (dcs); CRIT: PG11–19 Beta 3 unmodified; TINY: PG11–19 Beta 3 unmodified. Advice, pending human review — Editorial inference, pending maintainer review: The OLAP-only override is intended to exploit partition-local aggregation for analytical schemas while avoiding its planning and memory multiplication in other profiles.

Common pitfalls

  • Treating enable_partitionwise_aggregate as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • It can multiply work_mem-limited nodes and planning effort roughly with the number of participating partitions.

Related parameters

enable_partitionwise_join · enable_partition_pruning · work_mem · enable_hashagg · max_parallel_workers_per_gather

References

9.27 - enable_partitionwise_join

enable_partitionwise_join — Enables partitionwise join. Observed in PG11–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables partitionwise join.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 2fb1abaeb016 — Rename enable_partition_wise_join to enable_partitionwise_join
Commit date 2018-02-16
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 off — off

How it works

enable_partitionwise_join controls whether the planner may choose joining one-to-one matching partitions when join keys contain compatible partition keys.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

It can multiply work_mem-limited nodes and planning effort roughly with the number of participating partitions. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default off for routine OLTP. Test on at session scope only when both sides have one-to-one compatible partition layouts and the join includes every partition key; budget planning CPU and the work_mem-limited nodes created per partition.
OLAP Partition-aligned analytical joins can improve with on, which is why the current Pigsty OLAP template enables it. Compare planning memory, planning time, total execution memory, and partition count—not execution time alone.
Small nodes Leave off unless a specific partition-aligned join repeatedly benefits. Many partitions can make planning and per-node memory disproportionate on a small host even when each local join is efficient.

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 on different 'on'
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 = on (dcs); CRIT: PG11–19 Beta 3 unmodified; TINY: PG11–19 Beta 3 unmodified. Advice, pending human review — Editorial inference, pending maintainer review: The OLAP-only override is intended to exploit matching partition layouts for analytical joins while avoiding wider planning and memory cost in other profiles.

Common pitfalls

  • Treating enable_partitionwise_join as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • It can multiply work_mem-limited nodes and planning effort roughly with the number of participating partitions.

Related parameters

enable_partitionwise_aggregate · enable_partition_pruning · work_mem · join_collapse_limit · max_parallel_workers_per_gather

References

9.28 - enable_presorted_aggregate

enable_presorted_aggregate — Enables the planner’s ability to produce plans that provide presorted input for ORDER BY / DISTINCT aggregate functions. Observed in PG16–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s ability to produce plans that provide presorted input for ORDER BY / DISTINCT aggregate functions.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 3226f47282a0 — Add enable_presorted_aggregate GUC
Commit date 2022-12-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 on — on

How it works

enable_presorted_aggregate controls whether the planner may choose plans that deliver input already ordered for aggregate ORDER BY or DISTINCT clauses.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing plans that deliver input already ordered for aggregate ORDER BY or DISTINCT clauses explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_presorted_aggregate. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_presorted_aggregate as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_presorted_aggregate as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_sort · enable_incremental_sort · enable_group_by_reordering · work_mem

References

9.29 - enable_self_join_elimination

enable_self_join_elimination — Enables removal of unique self-joins. Observed in PG18–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables removal of unique self-joins.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit fc069a3a6319 — Implement Self-Join Elimination
Commit date 2025-02-13
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 on — on

How it works

enable_self_join_elimination controls whether the planner may choose removing provably redundant self-joins on plain tables when uniqueness and predicates preserve semantics.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The optimization is limited to plain tables and requires proofs that removing the duplicate relation preserves results. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the PG18 default on. If a regression is suspected, compare on and off in one session and inspect whether uniqueness proofs and predicates allow a redundant plain-table self-join to be removed; do not disable it cluster-wide to mask bad estimates.
OLAP Self-join elimination can reduce scans and join work in generated analytical SQL. Validate plan shape and result equivalence on representative statements, remembering that the optimization is limited to plain tables and provable uniqueness.
Small nodes Keep on unless a reproducible PG18 planner regression is isolated. The switch does not remove arbitrary self-joins, so query and index design remain necessary when the proof conditions are absent.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating enable_self_join_elimination as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The optimization is limited to plain tables and requires proofs that removing the duplicate relation preserves results.

Related parameters

join_collapse_limit · from_collapse_limit · enable_nestloop · enable_hashjoin

References

9.30 - enable_seqscan

enable_seqscan — Enables the planner’s use of sequential-scan plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of sequential-scan plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_seqscan controls whether the planner may choose sequential scans, which visit a relation in physical page order.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

Turning it off only discourages sequential scans because some queries still have no usable alternative. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing sequential scans, which visit a relation in physical page order explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_seqscan. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_seqscan as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_seqscan as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • Turning it off only discourages sequential scans because some queries still have no usable alternative.

Related parameters

enable_indexscan · enable_bitmapscan · seq_page_cost · random_page_cost · effective_cache_size

References

9.31 - enable_sort

enable_sort — Enables the planner’s use of explicit sort steps. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of explicit sort steps.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_sort controls whether the planner may choose explicit Sort nodes when no usable input order satisfies the requested pathkeys.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

Turning it off only discourages explicit sorting because correctness can still require a sort. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing explicit Sort nodes when no usable input order satisfies the requested pathkeys explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_sort. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_sort as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_sort as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • Turning it off only discourages explicit sorting because correctness can still require a sort.

Related parameters

work_mem · temp_file_limit · enable_incremental_sort · enable_gathermerge · trace_sort

References

9.32 - enable_tidscan

enable_tidscan — Enables the planner’s use of TID scan plans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables the planner’s use of TID scan plans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Method Configuration
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

enable_tidscan controls whether the planner may choose TID scans for predicates that identify physical tuple locations such as ctid.

It is consulted while a plan is built. A session-level change is useful for comparing EXPLAIN alternatives, but an already cached plan is not retroactively rewritten; invalidation or replanning is required to observe a different choice.

The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default for routine OLTP. Use a transaction- or session-local change to diagnose whether choosing TID scans for predicates that identify physical tuple locations such as ctid explains a regression, then repair statistics, indexes, estimates, or query shape instead of leaving a cluster-wide method ban.
OLAP Benchmark representative analytical plans with and without enable_tidscan. Judge planning time, memory, spill, and execution time together; a win for one report is not evidence for a global setting.
Small nodes Do not use enable_tidscan as a permanent hint on a small host. Resource pressure may change the best method, so verify with EXPLAIN (ANALYZE, BUFFERS) and keep the change scoped to the affected workload if it is still needed.

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

  • Treating enable_tidscan as a query hint even though it affects every plan built in its scope.
  • Testing an already cached prepared plan and concluding that the setting has no effect.
  • Masking stale statistics or cardinality errors by disabling a plan method globally.
  • The switch changes which candidate paths the planner may cost; it does not make the chosen method faster by itself.

Related parameters

enable_indexscan · enable_seqscan · random_page_cost · cpu_tuple_cost

References

9.33 - from_collapse_limit

from_collapse_limit — Sets the FROM-list size beyond which subqueries are not collapsed. Observed in PG9.0–19 Beta 3; its last measured boot default is 8 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the FROM-list size beyond which subqueries are not collapsed.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Value8
8

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 8 — 8

How it works

from_collapse_limit bounds how far the planner merges eligible subqueries into the parent FROM list. Flattening exposes more join orders and predicate movement opportunities but enlarges the search space.

If flattening would produce more FROM items than the limit, the subquery boundary is retained. Smaller values can reduce planning time while hiding a better global join order.

The resulting relation count interacts with join_collapse_limit and geqo_threshold; raising this limit can unexpectedly move the query from exhaustive planning into GEQO. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep from_collapse_limit at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.
OLAP Analytical SQL can make from_collapse_limit more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.
Small nodes On a small host, avoid increasing planning search or memory pressure through from_collapse_limit without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.

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

  • Treating from_collapse_limit as an executor resource limit rather than a planning assumption or policy.
  • Testing only one parameter set or one data distribution.
  • Expecting an already cached plan to be rewritten automatically.
  • Using a global override to hide stale statistics or fragile SQL structure.

Related parameters

join_collapse_limit · geqo_threshold · geqo · plan_cache_mode

References

9.34 - geqo

geqo — Enables genetic query optimization. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables genetic query optimization.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Genetic Query Optimizer
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

It selects the heuristic GEQO join-order search instead of exhaustive dynamic programming for sufficiently large join problems.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep geqo at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP For recurring many-table reports, test geqo with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes Avoid increasing geqo in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

  • Judging plan quality from one randomized GEQO run.
  • Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
  • Spending much more planning CPU for a marginal or unstable execution-time gain.
  • Assuming GEQO guarantees the globally best join order.

Related parameters

geqo_threshold · geqo_effort · geqo_pool_size · geqo_generations · join_collapse_limit

References

9.35 - geqo_effort

geqo_effort — GEQO: effort is used to set the default for other GEQO parameters. Observed in PG9.0–19 Beta 3; its last measured boot default is 5 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “GEQO: effort is used to set the default for other GEQO parameters.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1 – 10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Genetic Query Optimizer
Upstream classification
Latest boot value Value5
5

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 5 — 5

How it works

It is a convenience knob from 1 to 10 that derives defaults for pool size and generations; it has no direct step in the genetic algorithm.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep geqo_effort at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP For recurring many-table reports, test geqo_effort with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes Avoid increasing geqo_effort in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

  • Judging plan quality from one randomized GEQO run.
  • Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
  • Spending much more planning CPU for a marginal or unstable execution-time gain.
  • Assuming GEQO guarantees the globally best join order.

Related parameters

geqo · geqo_pool_size · geqo_generations · geqo_selection_bias · geqo_threshold

References

9.36 - geqo_generations

geqo_generations — GEQO: number of iterations of the algorithm. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “GEQO: number of iterations of the algorithm.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Genetic Query Optimizer
Upstream classification
Latest boot value Value0
0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 — 0

How it works

It sets the number of evolutionary iterations; zero derives a value from the selected pool size.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep geqo_generations at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP For recurring many-table reports, test geqo_generations with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes Avoid increasing geqo_generations in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

  • Judging plan quality from one randomized GEQO run.
  • Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
  • Spending much more planning CPU for a marginal or unstable execution-time gain.
  • Assuming GEQO guarantees the globally best join order.

Related parameters

geqo · geqo_pool_size · geqo_effort · geqo_seed · geqo_selection_bias

References

9.37 - geqo_pool_size

geqo_pool_size — GEQO: number of individuals in the population. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “GEQO: number of individuals in the population.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Genetic Query Optimizer
Upstream classification
Latest boot value Value0
0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 — 0

How it works

It sets the number of candidate join orders in the genetic population; zero asks PostgreSQL to derive a value from effort and query size.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep geqo_pool_size at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP For recurring many-table reports, test geqo_pool_size with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes Avoid increasing geqo_pool_size in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

  • Judging plan quality from one randomized GEQO run.
  • Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
  • Spending much more planning CPU for a marginal or unstable execution-time gain.
  • Assuming GEQO guarantees the globally best join order.

Related parameters

geqo · geqo_effort · geqo_generations · geqo_selection_bias · geqo_seed

References

9.38 - geqo_seed

geqo_seed — GEQO: seed for random path selection. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “GEQO: seed for random path selection.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Genetic Query Optimizer
Upstream classification
Latest boot value Value0
0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 — 0

How it works

It seeds GEQO’s random path selection. Changing it explores a different subset of join orders without changing table data or statistics.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep geqo_seed at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP For recurring many-table reports, test geqo_seed with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes Avoid increasing geqo_seed in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

  • Judging plan quality from one randomized GEQO run.
  • Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
  • Spending much more planning CPU for a marginal or unstable execution-time gain.
  • Assuming GEQO guarantees the globally best join order.

Related parameters

geqo · geqo_pool_size · geqo_generations · geqo_selection_bias · geqo_threshold

References

9.39 - geqo_selection_bias

geqo_selection_bias — GEQO: selective pressure within the population. Observed in PG9.0–19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “GEQO: selective pressure within the population.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1.5 – 2
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Genetic Query Optimizer
Upstream classification
Latest boot value Value2
2

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 2 — 2

How it works

It controls selective pressure: higher values more strongly favor fitter candidates while reducing population diversity.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep geqo_selection_bias at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP For recurring many-table reports, test geqo_selection_bias with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes Avoid increasing geqo_selection_bias in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

  • Judging plan quality from one randomized GEQO run.
  • Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
  • Spending much more planning CPU for a marginal or unstable execution-time gain.
  • Assuming GEQO guarantees the globally best join order.

Related parameters

geqo · geqo_pool_size · geqo_generations · geqo_seed · geqo_effort

References

9.40 - geqo_threshold

geqo_threshold — Sets the threshold of FROM items beyond which GEQO is used. Observed in PG9.0–19 Beta 3; its last measured boot default is 12 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the threshold of FROM items beyond which GEQO is used.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value2 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Genetic Query Optimizer
Upstream classification
Latest boot value Value12
12

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 12 — 12

How it works

It counts FROM items and switches eligible join problems to GEQO at or above the threshold; a FULL OUTER JOIN construct counts as one item.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep geqo_threshold at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP For recurring many-table reports, test geqo_threshold with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes Avoid increasing geqo_threshold in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

  • Judging plan quality from one randomized GEQO run.
  • Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
  • Spending much more planning CPU for a marginal or unstable execution-time gain.
  • Assuming GEQO guarantees the globally best join order.

Related parameters

geqo · geqo_effort · join_collapse_limit · from_collapse_limit · geqo_seed

References

9.41 - jit

Allows PostgreSQL to use just-in-time compilation when the build provides a JIT implementation and the plan’s estimated cost crosses the configured thresholds. Enabling it does not force JIT for every query.
Note

Fact — official short description: “Allow JIT compilation.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 432bb9e04da4 — Basic JIT provider and error handling infrastructure.
Commit date 2018-03-21
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11 off — off
PG12–18 on — on
PG19 Beta 3 off — off

How it works

The jit switch is the top-level gate. When it is on, jit_above_cost decides whether compilation starts, while jit_inline_above_cost and jit_optimize_above_cost govern additional, more expensive compilation work.

JIT is mainly beneficial for long-running CPU-bound queries, often analytical ones. Compilation adds latency, so short statements can become slower if thresholds are lowered too aggressively.

The decision is made at plan time. For a prepared statement using a generic plan, the settings active when that plan is prepared control the decision; EXPLAIN ANALYZE reports whether JIT ran and how much time its phases consumed.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave the default thresholds high or disable JIT if compilation latency appears in short-request tails. Test at the statement or role level before changing it cluster-wide.
OLAP Keep it available and benchmark CPU-heavy aggregates, expressions, and scans. Judge total execution time, including generation, inlining, optimization, and emission overhead.
Small nodes On small CPU-constrained systems, JIT often has little benefit for ordinary queries. Keeping it on with conservative thresholds is different from lowering thresholds to force compilation.

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

  • jit=on does nothing if PostgreSQL was built without an available JIT implementation.
  • On does not mean every query is compiled; cost thresholds still gate execution.
  • Lowering thresholds can make short queries slower than interpreted execution.
  • Generic prepared plans use the configuration in effect when the plan was prepared.
  • Estimated cost is not execution time, so threshold behavior must be measured with representative plans.

Related parameters

jit_above_cost · jit_inline_above_cost · jit_optimize_above_cost · jit_provider · plan_cache_mode · jit_expressions

References

9.42 - jit_above_cost

jit_above_cost — Perform JIT compilation if query is more expensive. Observed in PG11–19 Beta 3; its last measured boot default is 100000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Perform JIT compilation if query is more expensive.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value-1 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value100000
100000

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit cc415a56d09a — Basic planner and executor integration for JIT.
Commit date 2018-03-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 100000 — 100000

How it works

jit_above_cost compares the finished plan’s estimated cost with a threshold to decide whether PostgreSQL may start JIT compilation. The cost is the planner’s arbitrary estimate, not milliseconds.

The decision occurs at plan time and only matters when JIT is enabled and a provider is available. Generic prepared plans retain the decision made when the generic plan was generated.

A value of -1 disables this stage. jit_inline_above_cost and jit_optimize_above_cost are additional gates after jit_above_cost, so setting either below the base compilation threshold is not meaningful. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not lower jit_above_cost globally to chase a single CPU-heavy statement. Compilation latency is visible in short-query tails; test at statement or role scope and include JIT generation time in the result.
OLAP For long CPU-bound queries, benchmark total elapsed time on both sides of jit_above_cost. Lowering the threshold is useful only when saved execution CPU consistently exceeds compilation overhead.
Small nodes Keep the default or disable the stage with -1 when LLVM work competes with a small CPU budget. Estimated cost alone does not prove that JIT will pay back its startup cost.

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

  • Reading the threshold as milliseconds rather than arbitrary planner cost units.
  • Ignoring JIT generation, inlining, optimization, and emission time when benchmarking.
  • Expecting a changed value to alter a generic plan that was already generated.
  • Setting an advanced-stage threshold below jit_above_cost and expecting that stage to run by itself.

Related parameters

jit · jit_inline_above_cost · jit_optimize_above_cost · jit_expressions

References

9.43 - jit_inline_above_cost

jit_inline_above_cost — Perform JIT inlining if query is more expensive. Observed in PG11–19 Beta 3; its last measured boot default is 500000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Perform JIT inlining if query is more expensive.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value-1 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value500000
500000

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 9370462e9a79 — Add inlining support to LLVM JIT provider.
Commit date 2018-03-28
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 500000 — 500000

How it works

jit_inline_above_cost compares the finished plan’s estimated cost with a threshold to decide whether PostgreSQL may run JIT inlining. The cost is the planner’s arbitrary estimate, not milliseconds.

The decision occurs at plan time and only matters when JIT is enabled and a provider is available. Generic prepared plans retain the decision made when the generic plan was generated.

A value of -1 disables this stage. jit_inline_above_cost and jit_optimize_above_cost are additional gates after jit_above_cost, so setting either below the base compilation threshold is not meaningful. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not lower jit_inline_above_cost globally to chase a single CPU-heavy statement. Compilation latency is visible in short-query tails; test at statement or role scope and include JIT generation time in the result.
OLAP For long CPU-bound queries, benchmark total elapsed time on both sides of jit_inline_above_cost. Lowering the threshold is useful only when saved execution CPU consistently exceeds compilation overhead.
Small nodes Keep the default or disable the stage with -1 when LLVM work competes with a small CPU budget. Estimated cost alone does not prove that JIT will pay back its startup cost.

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

  • Reading the threshold as milliseconds rather than arbitrary planner cost units.
  • Ignoring JIT generation, inlining, optimization, and emission time when benchmarking.
  • Expecting a changed value to alter a generic plan that was already generated.
  • Setting an advanced-stage threshold below jit_above_cost and expecting that stage to run by itself.

Related parameters

jit · jit_above_cost · jit_optimize_above_cost · jit_expressions

References

9.44 - jit_optimize_above_cost

jit_optimize_above_cost — Optimize JIT-compiled functions if query is more expensive. Observed in PG11–19 Beta 3; its last measured boot default is 500000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Optimize JIT-compiled functions if query is more expensive.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value-1 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value500000
500000

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit cc415a56d09a — Basic planner and executor integration for JIT.
Commit date 2018-03-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 500000 — 500000

How it works

jit_optimize_above_cost compares the finished plan’s estimated cost with a threshold to decide whether PostgreSQL may run expensive JIT optimization passes. The cost is the planner’s arbitrary estimate, not milliseconds.

The decision occurs at plan time and only matters when JIT is enabled and a provider is available. Generic prepared plans retain the decision made when the generic plan was generated.

A value of -1 disables this stage. jit_inline_above_cost and jit_optimize_above_cost are additional gates after jit_above_cost, so setting either below the base compilation threshold is not meaningful. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not lower jit_optimize_above_cost globally to chase a single CPU-heavy statement. Compilation latency is visible in short-query tails; test at statement or role scope and include JIT generation time in the result.
OLAP For long CPU-bound queries, benchmark total elapsed time on both sides of jit_optimize_above_cost. Lowering the threshold is useful only when saved execution CPU consistently exceeds compilation overhead.
Small nodes Keep the default or disable the stage with -1 when LLVM work competes with a small CPU budget. Estimated cost alone does not prove that JIT will pay back its startup cost.

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

  • Reading the threshold as milliseconds rather than arbitrary planner cost units.
  • Ignoring JIT generation, inlining, optimization, and emission time when benchmarking.
  • Expecting a changed value to alter a generic plan that was already generated.
  • Setting an advanced-stage threshold below jit_above_cost and expecting that stage to run by itself.

Related parameters

jit · jit_above_cost · jit_inline_above_cost · jit_expressions

References

9.45 - join_collapse_limit

join_collapse_limit — Sets the FROM-list size beyond which JOIN constructs are not flattened. Observed in PG9.0–19 Beta 3; its last measured boot default is 8 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the FROM-list size beyond which JOIN constructs are not flattened.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Value8
8

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 8 — 8

How it works

join_collapse_limit controls when explicit JOIN constructs, except FULL JOIN, are flattened into a reorderable FROM list. A value of 1 preserves the written explicit join order.

Flattening enlarges the set of join orders the planner can explore, improving opportunities at the cost of planning CPU and memory. Outer-join semantics still constrain legal reorderings.

The exposed item count interacts with from_collapse_limit and geqo_threshold. Using 1 as a manual join-order tool transfers responsibility to SQL authors and is not a general plan-stability guarantee. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep join_collapse_limit at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.
OLAP Analytical SQL can make join_collapse_limit more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.
Small nodes On a small host, avoid increasing planning search or memory pressure through join_collapse_limit without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.

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

  • Treating join_collapse_limit as an executor resource limit rather than a planning assumption or policy.
  • Testing only one parameter set or one data distribution.
  • Expecting an already cached plan to be rewritten automatically.
  • Using a global override to hide stale statistics or fragile SQL structure.

Related parameters

from_collapse_limit · geqo_threshold · geqo · enable_hashjoin · enable_nestloop

References

9.46 - min_eager_agg_group_size

min_eager_agg_group_size — Sets the minimum average group size required to consider applying eager aggregation. Observed in PG19 Beta 3; its last measured boot default is 8 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the minimum average group size required to consider applying eager aggregation.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value8
8

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit 8e11859102f9 — Implement Eager Aggregation
Commit date 2025-10-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 8 — 8

How it works

PostgreSQL describes min_eager_agg_group_size as follows: “Sets the minimum average group size required to consider applying eager aggregation.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. 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.

This cost threshold represents the estimated average input rows per group needed before eager aggregation is considered worthwhile. A higher value demands more row reduction; a lower value explores more eager-aggregation paths but can spend planning and execution work on groups that barely shrink the join input.

Read it together with enable_eager_aggregate, enable_hashagg, enable_partitionwise_aggregate, work_mem. 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

Tip

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

Workload Guidance
OLTP Use a session-level experiment with EXPLAIN (ANALYZE, BUFFERS) and a representative parameter distribution. Keep the default unless eager aggregation consistently reduces rows and latency without plan instability.
OLAP Test joins with meaningful pre-aggregation opportunities, stale and fresh statistics, and spill pressure. Compare total CPU, peak memory, intermediate rows, and parallel plans, not just one query’s elapsed time.
Small nodes Leave planner switches and thresholds at their defaults until a repeatable regression is isolated. Fix cardinality statistics first; forcing a path globally can trade one improvement for many regressions.

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: 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 min_eager_agg_group_size as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports user 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

enable_eager_aggregate · enable_hashagg · enable_partitionwise_aggregate · work_mem · hash_mem_multiplier

References

9.47 - min_parallel_index_scan_size

min_parallel_index_scan_size — Sets the minimum amount of index data for a parallel scan. Observed in PG10–19 Beta 3; its last measured boot default is 512 KiB (64 × 8kB) in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the minimum amount of index data for a parallel scan.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value8kB
Raw unit
Range Value0 – 715827882
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value64
512 KiB (64 × 8kB)

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit 51ee6f3160d2 — Replace min_parallel_relation_size with two new GUCs.
Commit date 2017-02-15
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 64 8kB 512 KiB (64 × 8kB)

How it works

min_parallel_index_scan_size is a planner eligibility floor: parallel scan paths are not considered unless index pages estimated to be visited reaches the configured size.

Crossing this floor does not guarantee a parallel plan. The planner still compares costs, checks parallel safety, and requests workers subject to max_parallel_workers_per_gather and the cluster worker pools.

The index threshold also participates in deciding whether an index can be vacuumed in parallel. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP A higher min_parallel_index_scan_size can reduce parallel startup on short OLTP scans, but confirm that reports and maintenance do not regress. Pigsty’s OLTP/crit value is a policy bias, not a resource limit.
OLAP Keep the upstream threshold unless small but expensive scans are wrongly excluded. Lowering min_parallel_index_scan_size can raise planning and worker overhead when many queries run concurrently.
Small nodes Prefer a conservative or higher threshold on a small host where worker startup and memory contention dominate. Coordinate it with max_parallel_workers_per_gather rather than tuning it alone.

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 2MB different 2MB
OLAP Unmodified — —
CRIT 2MB different 2MB
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG10–19 Beta 3 = 2MB (dcs); OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 = 2MB (dcs); TINY: PG10–19 Beta 3 unmodified. Advice, pending human review — Editorial inference, pending maintainer review: The OLTP/crit value raises the index eligibility floor to reduce parallel tendency, while OLAP and tiny retain upstream behavior.

Common pitfalls

  • Assuming the threshold caps actual bytes read; it only controls planner eligibility.
  • Expecting a parallel plan merely because the size estimate crosses the threshold.
  • Lowering it without budgeting workers and per-node memory under concurrency.
  • Comparing the raw numeric value without applying its 8kB block unit.

Related parameters

max_parallel_workers_per_gather · parallel_setup_cost · parallel_tuple_cost · max_parallel_workers · enable_indexscan

References

9.48 - min_parallel_relation_size

min_parallel_relation_size — Sets the minimum size of relations to be considered for parallel scan. Observed in PG9.6; its last measured boot default is 8 MiB (1024 × 8kB) in PG9.6, with user context. It was removed in PG10.
Note

Fact — official short description: “Sets the minimum size of relations to be considered for parallel scan.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value8kB
Raw unit
Range Value0 – 715827882
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value1024
8 MiB (1024 × 8kB)

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6
Removed in PG10
Introduction commit 75be66464cb1 — Invent min_parallel_relation_size GUC to replace a hard-wired constant.
Commit date 2016-06-16
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6 1024 8kB 8 MiB (1024 × 8kB)

How it works

PostgreSQL describes min_parallel_relation_size as follows: “Sets the minimum size of relations to be considered for parallel scan.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. The atlas measures it in PG9.6; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

PostgreSQL 9.6 used one relation-size threshold when deciding whether a parallel scan was worth considering. PostgreSQL 10 split the control into min_parallel_table_scan_size and min_parallel_index_scan_size, allowing heap and index access paths to have different break-even points.

Read it together with min_parallel_table_scan_size, min_parallel_index_scan_size, max_parallel_workers_per_gather, enable_parallel_append. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.6; 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: PG9.6 unmodified; OLAP: PG9.6 unmodified; CRIT: PG9.6 unmodified; TINY: PG9.6 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for min_parallel_relation_size as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports user context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

min_parallel_table_scan_size · min_parallel_index_scan_size · max_parallel_workers_per_gather · enable_parallel_append

References

9.49 - min_parallel_table_scan_size

min_parallel_table_scan_size — Sets the minimum amount of table data for a parallel scan. Observed in PG10–19 Beta 3; its last measured boot default is 8 MiB (1024 × 8kB) in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the minimum amount of table data for a parallel scan.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value8kB
Raw unit
Range Value0 – 715827882
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value1024
8 MiB (1024 × 8kB)

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit 51ee6f3160d2 — Replace min_parallel_relation_size with two new GUCs.
Commit date 2017-02-15
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 1024 8kB 8 MiB (1024 × 8kB)

How it works

min_parallel_table_scan_size is a planner eligibility floor: parallel scan paths are not considered unless table data estimated to be scanned reaches the configured size.

Crossing this floor does not guarantee a parallel plan. The planner still compares costs, checks parallel safety, and requests workers subject to max_parallel_workers_per_gather and the cluster worker pools.

For a parallel sequential scan, the estimate is normally the whole relation size. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP A higher min_parallel_table_scan_size can reduce parallel startup on short OLTP scans, but confirm that reports and maintenance do not regress. Pigsty’s OLTP/crit value is a policy bias, not a resource limit.
OLAP Keep the upstream threshold unless small but expensive scans are wrongly excluded. Lowering min_parallel_table_scan_size can raise planning and worker overhead when many queries run concurrently.
Small nodes Prefer a conservative or higher threshold on a small host where worker startup and memory contention dominate. Coordinate it with max_parallel_workers_per_gather rather than tuning it alone.

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 32MB different 32MB
OLAP Unmodified — —
CRIT 32MB different 32MB
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG10–19 Beta 3 = 32MB (dcs); OLAP: PG10–19 Beta 3 unmodified; CRIT: PG10–19 Beta 3 = 32MB (dcs); TINY: PG10–19 Beta 3 unmodified. Advice, pending human review — Editorial inference, pending maintainer review: The OLTP/crit value raises the table eligibility floor to reduce parallel tendency, while OLAP and tiny retain upstream behavior.

Common pitfalls

  • Assuming the threshold caps actual bytes read; it only controls planner eligibility.
  • Expecting a parallel plan merely because the size estimate crosses the threshold.
  • Lowering it without budgeting workers and per-node memory under concurrency.
  • Comparing the raw numeric value without applying its 8kB block unit.

Related parameters

max_parallel_workers_per_gather · parallel_setup_cost · parallel_tuple_cost · max_parallel_workers · enable_seqscan

References

9.50 - parallel_setup_cost

parallel_setup_cost — Sets the planner’s estimate of the cost of starting up worker processes for parallel query. Observed in PG9.6–19 Beta 3; its last measured boot default is 1000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the cost of starting up worker processes for parallel query.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value1000
1000

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit 3bd909b22093 — Add a Gather executor node.
Commit date 2015-09-30
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 1000 — 1000

How it works

parallel_setup_cost models the fixed overhead of launching parallel workers for a plan. It is one term in estimated path cost and does not allocate resources or change executor behavior directly.

Planner cost units are arbitrary and only their ratios matter. Scaling all cost constants together leaves path ordering unchanged; changing one alters the balance between I/O, row processing, operators, and parallel overhead.

The value is consulted when a plan is built. Statistics, row-count estimates, cache assumptions, tablespace overrides, and enabled plan methods can outweigh a small change in this constant. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate parallel_setup_cost only from a representative workload, not one plan. First correct stale statistics and compare EXPLAIN (ANALYZE, BUFFERS) estimates with reality; use role or tablespace scope where possible.
OLAP Analytical workloads can justify a different CPU-versus-I/O balance, but change parallel_setup_cost together with the related cost model and validate the full scan/join/aggregate mix.
Small nodes Keep the upstream value unless repeated evidence shows a systematic modeling error. On small systems, concurrency and cache residency often matter more than fine-grained changes to parallel_setup_cost.

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 2000 different 2000
OLAP Unmodified — —
CRIT 2000 different 2000
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.6–19 Beta 3 = 2000 (dcs); OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 = 2000 (dcs); TINY: PG9.6–19 Beta 3 unmodified. Advice, pending human review — Editorial inference, pending maintainer review: Doubling the setup estimate in OLTP/crit is intended to reduce parallel-plan selection without disabling it; OLAP and tiny retain upstream behavior.

Common pitfalls

  • Interpreting the value as elapsed time or a hard resource limit.
  • Tuning it to repair one query and regressing the wider workload.
  • Changing cost constants before correcting statistics and cardinality estimates.
  • Forgetting that only relative values influence path choice.

Related parameters

parallel_tuple_cost · max_parallel_workers_per_gather · min_parallel_table_scan_size · max_parallel_workers

References

9.51 - parallel_tuple_cost

parallel_tuple_cost — Sets the planner’s estimate of the cost of passing each tuple (row) from worker to leader backend. Observed in PG9.6–19 Beta 3; its last measured boot default is 0.1 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the cost of passing each tuple (row) from worker to leader backend.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value0.1
0.1

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit 3bd909b22093 — Add a Gather executor node.
Commit date 2015-09-30
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 0.1 — 0.1

How it works

parallel_tuple_cost models the per-row overhead of moving tuples from parallel workers to another process. It is one term in estimated path cost and does not allocate resources or change executor behavior directly.

Planner cost units are arbitrary and only their ratios matter. Scaling all cost constants together leaves path ordering unchanged; changing one alters the balance between I/O, row processing, operators, and parallel overhead.

The value is consulted when a plan is built. Statistics, row-count estimates, cache assumptions, tablespace overrides, and enabled plan methods can outweigh a small change in this constant. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate parallel_tuple_cost only from a representative workload, not one plan. First correct stale statistics and compare EXPLAIN (ANALYZE, BUFFERS) estimates with reality; use role or tablespace scope where possible.
OLAP Analytical workloads can justify a different CPU-versus-I/O balance, but change parallel_tuple_cost together with the related cost model and validate the full scan/join/aggregate mix.
Small nodes Keep the upstream value unless repeated evidence shows a systematic modeling error. On small systems, concurrency and cache residency often matter more than fine-grained changes to parallel_tuple_cost.

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 0.2 different 0.2
OLAP Unmodified — —
CRIT 0.2 different 0.2
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.6–19 Beta 3 = 0.2 (dcs); OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 = 0.2 (dcs); TINY: PG9.6–19 Beta 3 unmodified. Advice, pending human review — Editorial inference, pending maintainer review: Doubling the tuple-transfer estimate in OLTP/crit is intended to reduce parallel-plan selection for tuple-heavy paths; OLAP and tiny retain upstream behavior.

Common pitfalls

  • Interpreting the value as elapsed time or a hard resource limit.
  • Tuning it to repair one query and regressing the wider workload.
  • Changing cost constants before correcting statistics and cardinality estimates.
  • Forgetting that only relative values influence path choice.

Related parameters

parallel_setup_cost · max_parallel_workers_per_gather · parallel_leader_participation · enable_gathermerge

References

9.52 - plan_cache_mode

plan_cache_mode — Controls the planner’s selection of custom or generic plan. Observed in PG12–19 Beta 3; its last measured boot default is auto in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Controls the planner’s selection of custom or generic plan.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueauto, force_generic_plan, force_custom_plan
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Valueauto
auto

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit f7cb2842bf47 — Add plan_cache_mode setting
Commit date 2018-07-16
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 auto — auto

How it works

Prepared statements can use a custom plan built with current parameter values or a generic plan independent of those values. plan_cache_mode overrides PostgreSQL’s normal cost-based choice with auto, force_custom_plan, or force_generic_plan.

The setting is checked when a cached statement is executed, not when PREPARE is issued. A custom plan pays planning cost repeatedly but can adapt to skew; a generic plan saves planning work but can be poor for parameter-sensitive predicates.

PL/pgSQL and protocol-level prepared statements are both affected. Forcing a mode is diagnostic or workload-specific policy, not a cure for bad statistics or missing indexes. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep plan_cache_mode at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.
OLAP Analytical SQL can make plan_cache_mode more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.
Small nodes On a small host, avoid increasing planning search or memory pressure through plan_cache_mode without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating plan_cache_mode as an executor resource limit rather than a planning assumption or policy.
  • Testing only one parameter set or one data distribution.
  • Expecting an already cached plan to be rewritten automatically.
  • Using a global override to hide stale statistics or fragile SQL structure.

Related parameters

default_statistics_target · cursor_tuple_fraction · join_collapse_limit · compute_query_id · jit_above_cost

References

9.53 - random_page_cost

A planner cost constant describing non-sequential page access relative to sequential access. Lowering it makes index and bitmap access paths look cheaper; it does not change storage behavior itself.
Note

Fact — official short description: “Sets the planner’s estimate of the cost of a nonsequentially fetched disk page.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value4
4

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 4 — 4

How it works

Planner cost units are arbitrary and meaningful mainly in relation to other cost constants. With seq_page_cost conventionally at 1.0, random_page_cost expresses the average penalty of random page access after accounting for expected caching and storage behavior.

Reducing the value relative to seq_page_cost favors index scans; increasing it makes such scans less attractive. Both values can also be overridden per tablespace, which is useful when a cluster spans storage tiers.

The official guidance treats these constants as workload-wide averages and warns against changing them from a few isolated experiments. Plan quality also depends on statistics, effective_cache_size, correlation, and query shape.

Tuning advice

Tip

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

Workload Guidance
OLTP On low-latency SSD with a high cache hit rate, 1.1 is a reasonable trial value, not a universal truth. Compare representative EXPLAIN (ANALYZE, BUFFERS) plans and tail latency before adopting it.
OLAP Do not lower it merely because storage is SSD; analytical scans may still favor sequential access. Calibrate with the full scan-versus-index workload mix and consider tablespace-specific values.
Small nodes If the entire database is usually cached, a value near seq_page_cost can be defensible. Avoid setting it below seq_page_cost and fix stale statistics before forcing index-heavy plans.

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 1.1 different 1.1
OLAP 1.1 different 1.1
CRIT 1.1 different 1.1
TINY 1.1 different 1.1
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 1.1 (dcs); OLAP: PG9.0–19 Beta 3 = 1.1 (dcs); CRIT: PG9.0–19 Beta 3 = 1.1 (dcs); TINY: PG9.0–19 Beta 3 = 1.1 (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: 1.1 models SSD random access and cache-heavy deployments as much closer to sequential access.

Common pitfalls

  • The number is a relative planner cost, not milliseconds or measured device latency.
  • Lowering it to repair one query can regress the wider workload.
  • Bad cardinality estimates can be mistaken for incorrect storage costs.
  • A value below seq_page_cost is normally physically implausible.
  • A global value can misrepresent mixed SSD, HDD, and network-attached tablespaces.

Related parameters

seq_page_cost · effective_cache_size · effective_io_concurrency · default_statistics_target · enable_indexscan · enable_bitmapscan

References

9.54 - recursive_worktable_factor

recursive_worktable_factor — Sets the planner’s estimate of the average size of a recursive query’s working table. Observed in PG15–19 Beta 3; its last measured boot default is 10 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the average size of a recursive query’s working table.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0.001 – 1e+06
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Other Planner Options
Upstream classification
Latest boot value Value10
10

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit 0bd7af082ace — Invent recursive_worktable_factor GUC to replace hard-wired constant.
Commit date 2022-03-24
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG15–19 Beta 3 10 — 10

How it works

recursive_worktable_factor estimates the average recursive working-table size as a multiple of the non-recursive seed term. The estimate feeds costs for joining the worktable to other relations.

It does not cap recursion, memory, rows, or iterations. A low-fan-out traversal can be modeled with a smaller value, while graph expansion with high fan-out may need a larger estimate.

The value is used during planning; actual recursive growth still depends on data and termination predicates. Misestimation can select an unsuitable join method inside the recursive term. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep recursive_worktable_factor at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.
OLAP Analytical SQL can make recursive_worktable_factor more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.
Small nodes On a small host, avoid increasing planning search or memory pressure through recursive_worktable_factor without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating recursive_worktable_factor as an executor resource limit rather than a planning assumption or policy.
  • Testing only one parameter set or one data distribution.
  • Expecting an already cached plan to be rewritten automatically.
  • Using a global override to hide stale statistics or fragile SQL structure.

Related parameters

work_mem · enable_nestloop · enable_hashjoin · default_statistics_target

References

9.55 - seq_page_cost

seq_page_cost — Sets the planner’s estimate of the cost of a sequentially fetched disk page. Observed in PG9.0–19 Beta 3; its last measured boot default is 1 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the planner’s estimate of the cost of a sequentially fetched disk page.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1.79769e+308
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueQuery Tuning / Planner Cost Constants
Upstream classification
Latest boot value Value1
1

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 1 — 1

How it works

seq_page_cost models a sequential page fetch and the conventional base of the planner’s arbitrary cost scale. It is one term in estimated path cost and does not allocate resources or change executor behavior directly.

Planner cost units are arbitrary and only their ratios matter. Scaling all cost constants together leaves path ordering unchanged; changing one alters the balance between I/O, row processing, operators, and parallel overhead.

The value is consulted when a plan is built. Statistics, row-count estimates, cache assumptions, tablespace overrides, and enabled plan methods can outweigh a small change in this constant. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate seq_page_cost only from a representative workload, not one plan. First correct stale statistics and compare EXPLAIN (ANALYZE, BUFFERS) estimates with reality; use role or tablespace scope where possible.
OLAP Analytical workloads can justify a different CPU-versus-I/O balance, but change seq_page_cost together with the related cost model and validate the full scan/join/aggregate mix.
Small nodes Keep the upstream value unless repeated evidence shows a systematic modeling error. On small systems, concurrency and cache residency often matter more than fine-grained changes to seq_page_cost.

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

  • Interpreting the value as elapsed time or a hard resource limit.
  • Tuning it to repair one query and regressing the wider workload.
  • Changing cost constants before correcting statistics and cardinality estimates.
  • Forgetting that only relative values influence path choice.

Related parameters

random_page_cost · cpu_tuple_cost · effective_cache_size · enable_seqscan · effective_io_concurrency

References

10 - Replication

Complete dossiers for 33 core PostgreSQL settings in Replication.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

10.1 - hot_standby

hot_standby — Allows connections and queries during recovery. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Allows connections and queries during recovery.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Standby Servers
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.6 off — off
PG10–19 Beta 3 on — on

How it works

Allows connections and queries during recovery. The value is fixed when the server starts, so changing it requires a restart.

When recovery has reached a consistent state, this permits read-only connections and queries. Replay still has priority: WAL records that conflict with snapshots or locks can cancel queries according to the standby-delay settings.

Monitor and change hot_standby together with primary_conninfo, primary_slot_name, restore_command. 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

Tip

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

Workload Guidance
OLTP Size hot_standby from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

primary_conninfo · primary_slot_name · restore_command · wal_receiver_timeout · wal_retrieve_retry_interval · max_standby_archive_delay

References

10.2 - hot_standby_feedback

hot_standby_feedback — Allows feedback from a hot standby to the primary that will avoid query conflicts. Observed in PG9.1–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Allows feedback from a hot standby to the primary that will avoid query conflicts.”

Identity

Type Valuebool
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 ValueReplication / Standby Servers
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit bca8b7f16a3e — Hot Standby feedback for avoidance of cleanup conflicts on standby. Standby optionally sends back information about oldestXmin of queries which is then checked and applied to the WALSender’s proc->xmin. GetOldestXmin() is modified slightly to agree with GetSnapshotData(), so that all backends on primary include WALSender within their snapshots. Note this does nothing to change the snapshot xmin on either master or standby. Feedback piggybacks on the standby reply message. vacuum_defer_cleanup_age is no longer used on standby, though parameter still exists on primary, since some use cases still exist.
Commit date 2011-02-16
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 off — off

How it works

A standby with feedback enabled reports information about snapshots needed by its running queries to the primary or upstream standby. The upstream can then avoid vacuum cleanup that would remove row versions still visible to those queries. Messages are not sent more frequently than wal_receiver_status_interval.

Avoiding cleanup conflicts transfers the cost to the primary: dead row versions can remain longer, increasing table and index bloat and vacuum work. In cascading replication feedback is passed upstream, so one old snapshot far downstream can affect the primary.

The mechanism addresses cleanup-record conflicts, not every hot-standby conflict. DDL locks, dropped objects, tablespace actions, and some page-level conflicts can still cancel queries. Feedback also has gaps while a non-slot standby is disconnected, and clock changes can disturb its timing.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable it only when reducing standby query cancellation is worth possible primary bloat. Bound standby query duration, monitor transaction age, dead tuples, table growth, vacuum progress, and pg_stat_database_conflicts; an HA-only standby often benefits more from timely replay than long query survival.
OLAP It is useful for reporting standbys with long reads, but pair it with workload timeouts and a bloat budget on the primary. Consider a dedicated reporting topology if analytical snapshots routinely block cleanup for hours.
Small nodes Start from off unless cancellations are a demonstrated problem. Limited storage makes primary bloat especially risky; if enabled, use short query limits and aggressive monitoring.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.1–19 Beta 3 = on (dcs); OLAP: PG9.1–19 Beta 3 = on (dcs); CRIT: PG9.1–19 Beta 3 = on (dcs); TINY: PG9.1–19 Beta 3 = on (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

  • Enabling it and ignoring table or index bloat on the primary.
  • Expecting it to prevent DDL, lock, database-drop, or tablespace conflicts.
  • Allowing an unbounded long query on a downstream standby to hold back cleanup upstream.
  • Assuming feedback remains effective while a slotless standby is disconnected.
  • Ignoring clock jumps and wal_receiver_status_interval when reasoning about feedback timing.

Related parameters

max_standby_streaming_delay · max_standby_archive_delay · wal_receiver_status_interval · primary_slot_name · autovacuum_vacuum_scale_factor · log_recovery_conflict_waits

References

10.3 - idle_replication_slot_timeout

idle_replication_slot_timeout — Sets the duration a replication slot can remain idle before it is invalidated. Observed in PG18–19 Beta 3; its last measured boot default is 0 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the duration a replication slot can remain idle before it is invalidated.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value0
0 s

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit ac0e33136abc — Invalidate inactive replication slots.
Commit date 2025-02-19
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 0 s 0 s

How it works

Sets the duration a replication slot can remain idle before it is invalidated. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

PostgreSQL 18 measures inactivity from pg_replication_slots.inactive_since and invalidates eligible slots at a checkpoint after the timeout. Zero disables the policy; slots that reserve no WAL and synchronized standby slots are outside this mechanism.

Monitor and change idle_replication_slot_timeout together with max_replication_slots, max_slot_wal_keep_size, primary_slot_name. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size idle_replication_slot_timeout from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 7d different 7d
OLAP 7d different 7d
CRIT 3d different 3d
TINY 7d different 7d
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 = 7d (dcs); OLAP: PG18–19 Beta 3 = 7d (dcs); CRIT: PG18–19 Beta 3 = 3d (dcs); TINY: PG18–19 Beta 3 = 7d (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to invalidate forgotten PG18 slots, with a stricter window in the CRIT profile; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Expecting invalidation exactly when the duration expires rather than at a later checkpoint.
  • Assuming synchronized standby slots are eligible.
  • Allowing an automatic invalidation without a subscriber rebootstrap runbook.
  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Related parameters

max_replication_slots · max_slot_wal_keep_size · primary_slot_name · wal_keep_size · checkpoint_timeout · max_wal_senders

References

10.4 - max_active_replication_origins

max_active_replication_origins — Sets the maximum number of active replication origins. Observed in PG18–19 Beta 3; its last measured boot default is 10 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of active replication origins.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Subscribers
Upstream classification
Latest boot value Value10
10

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 04ff636cbce4 — Add GUC option to control maximum active replication origins.
Commit date 2025-03-21
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 10 — 10

How it works

Sets the maximum number of active replication origins. The value is fixed when the server starts, so changing it requires a restart.

Each active logical replication origin tracks remote progress so apply can avoid replaying changes twice. The startup allocation effectively bounds concurrently active subscriptions/origins and consumes shared resources even though dormant catalog rows need not all be active.

Monitor and change max_active_replication_origins together with max_logical_replication_workers, max_replication_slots, track_commit_timestamp. 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

Tip

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

Workload Guidance
OLTP Size max_active_replication_origins from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_logical_replication_workers · max_replication_slots · track_commit_timestamp · max_parallel_apply_workers_per_subscription · max_sync_workers_per_subscription · hot_standby

References

10.5 - max_logical_replication_workers

max_logical_replication_workers — Maximum number of logical replication worker processes. Observed in PG10–19 Beta 3; its last measured boot default is 4 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Maximum number of logical replication worker processes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Subscribers
Upstream classification
Latest boot value Value4
4

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit 665d1fad99e7 — Logical replication
Commit date 2017-01-19
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 4 — 4

How it works

Maximum number of logical replication worker processes. The value is fixed when the server starts, so changing it requires a restart.

This reserves the logical-replication portion of the background-worker budget for apply, table synchronization, and related workers. The effective capacity is also bounded by max_worker_processes and by the per-subscription worker limits.

Monitor and change max_logical_replication_workers together with max_parallel_apply_workers_per_subscription, max_sync_workers_per_subscription, max_worker_processes. 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

Tip

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

Workload Guidance
OLTP Size max_logical_replication_workers from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 8 different 8
OLAP 8 different 8
CRIT 8 different 8
TINY 8 different 8
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG10–19 Beta 3 = 8 (dcs); OLAP: PG10–19 Beta 3 = 8 (dcs); CRIT: PG10–19 Beta 3 = 8 (dcs); TINY: PG10–19 Beta 3 = 8 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to leave headroom for several logical subscriptions and table synchronization jobs; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_parallel_apply_workers_per_subscription · max_sync_workers_per_subscription · max_worker_processes · max_replication_slots · max_active_replication_origins · track_commit_timestamp

References

10.6 - max_parallel_apply_workers_per_subscription

max_parallel_apply_workers_per_subscription sets the maximum number of parallel apply workers per subscription. It is a sighup setting present in PG16–18; the latest recorded boot default is 2.
Note

Fact — official short description: “Maximum number of parallel apply workers per subscription.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 1024
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Subscribers
Upstream classification
Latest boot value Value2
2

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 216a784829c2 — Perform apply of large transactions by parallel workers.
Commit date 2023-01-09
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 2 — 2

How it works

Maximum number of parallel apply workers per subscription. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

A subscription leader can use up to this many parallel workers to apply suitable in-progress transactions. More workers do not parallelize every transaction and consume the global logical-replication and background-worker pools.

Monitor and change max_parallel_apply_workers_per_subscription together with max_logical_replication_workers, max_sync_workers_per_subscription, max_worker_processes. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size max_parallel_apply_workers_per_subscription from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_logical_replication_workers · max_sync_workers_per_subscription · max_worker_processes · max_replication_slots · max_active_replication_origins · hot_standby

References

10.7 - max_repack_replication_slots

max_repack_replication_slots — Sets the maximum number of replication slots for use by REPACK. Observed in PG19 Beta 3; its last measured boot default is 5 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of replication slots for use by REPACK.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value5
5

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit e76d8c749c31 — Reserve replication slots specifically for REPACK
Commit date 2026-04-07
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 5 — 5

How it works

PostgreSQL describes max_repack_replication_slots as follows: “Sets the maximum number of replication slots for use by REPACK.” 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.

PostgreSQL 19’s REPACK command can use dedicated replication slots to reorganize a relation concurrently while tracking changes. This startup ceiling reserves how many such slots the server can support; it interacts with the overall replication-slot and WAL-sender budgets and with retained-WAL disk risk.

Read it together with max_replication_slots, max_wal_senders, wal_level, max_slot_wal_keep_size. 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

Tip

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

Workload Guidance
OLTP Model normal failover and worst-case lag before setting a bound. Observe sender state, retained WAL, shutdown time, and receiver catch-up; preserve enough capacity for monitoring and planned switchovers.
OLAP Account for large transactions, bulk loads, slow apply, and long-distance links. A short timeout can make shutdown faster but transfer recovery work and inconsistency risk to the next startup.
Small nodes Use few slots and senders, watch pg_wal disk consumption, and keep timeout behavior explicit. Test shutdown and restart with the receiver both healthy and unavailable.

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

max_replication_slots · max_wal_senders · wal_level · max_slot_wal_keep_size · wal_sender_shutdown_timeout

References

10.8 - max_replication_slots

max_replication_slots — Sets the maximum number of simultaneously defined replication slots. Observed in PG9.4–19 Beta 3; its last measured boot default is 10 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of simultaneously defined replication slots.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value10
10

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit 858ec11858a9 — Introduce replication slots.
Commit date 2014-01-31
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–9.6 0 — 0
PG10–19 Beta 3 10 — 10

How it works

PostgreSQL allocates replication-slot control capacity at server start. Physical slots can reserve WAL for standbys, while logical slots can reserve both WAL and catalog visibility information for decoding consumers.

The setting limits slot objects, not active WAL-sender connections; max_wal_senders is a separate limit. Slot use also requires wal_level = replica or higher. Reducing the setting below the number of existing slots prevents the server from starting.

An unused slot is not harmless merely because it has no active process. A persistent inactive slot can retain WAL, and a logical slot can hold catalog_xmin, so slot inventory and consumer lifecycle are as important as the numerical ceiling.

Tuning advice

Tip

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

Workload Guidance
OLTP Budget slots from named physical standbys, logical subscriptions, CDC consumers, backup or migration tools, failover slots, and provisioning headroom. Keep a small reserve, but pair a larger ceiling with ownership, expiry, and lag monitoring.
OLAP Allow for logical consumers and migration jobs, but remember that high-WAL batch periods magnify the cost of any abandoned slot. Monitor restart_lsn and confirmed_flush_lsn before and during bulk work.
Small nodes Keep the ceiling close to the real consumer count plus limited reserve. A large value does not itself retain WAL, but it makes unmanaged slot sprawl easier and can turn a small disk incident into an outage.

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 50 different 50
OLAP 50 different 50
CRIT 50 different 50
TINY 50 different 50
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.4–19 Beta 3 = 50 (dcs); OLAP: PG9.4–19 Beta 3 = 50 (dcs); CRIT: PG9.4–19 Beta 3 = 50 (dcs); TINY: PG9.4–19 Beta 3 = 50 (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

  • Confusing the slot limit with max_wal_senders, which limits concurrent sender processes.
  • Lowering the value below the current slot count and making PostgreSQL fail to start.
  • Assuming inactive slots cannot retain WAL or catalog row versions.
  • Raising the ceiling without monitoring restart_lsn, catalog_xmin, and consumer health.
  • Creating permanent slots during experiments and never dropping them.

Related parameters

max_wal_senders · max_slot_wal_keep_size · wal_level · idle_replication_slot_timeout · max_logical_replication_workers · primary_slot_name

References

10.9 - max_slot_wal_keep_size

A reloadable checkpoint-time limit on how much WAL replication slots may retain. It appears from PG13 in this catalog, defaults to -1 (unlimited), and Pigsty applies a finite disk-relative cap.
Note

Fact — official short description: “Sets the maximum WAL size that can be reserved by replication slots.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit ValueMB
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value-1
-1 MB

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit c6550776394e — Allow users to limit storage reserved by replication slots
Commit date 2020-04-07
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 -1 MB -1 MB

How it works

At checkpoint time PostgreSQL compares a slot’s restart_lsn with the current WAL position. With the default -1 there is no parameter-imposed maximum; a stalled consumer can therefore retain enough WAL to fill pg_wal.

With a finite limit, required segments can be released when a slot falls too far behind. The slot can move through unreserved to lost status, and its consumer may need a new base backup or logical resynchronization. The cap protects server storage by sacrificing the guarantee that an indefinitely lagging slot remains usable.

Enforcement is checkpoint-based, so it is neither instantaneous nor an exact byte ceiling. pg_replication_slots exposes restart_lsn, wal_status, invalidation_reason, and safe_wal_size; these are the operational signals needed before the slot reaches the limit.

Tuning advice

Tip

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

Workload Guidance
OLTP Set a finite limit within the pg_wal emergency budget and derive it from peak WAL generation times the maximum supported repair window. Alert while safe_wal_size is still positive, and document the resynchronization path for every consumer.
OLAP Allow for expected bulk-WAL bursts, but do not make the cap effectively unlimited. Schedule consumers and batch jobs together, verify archive availability, and pause or repair a lagging consumer before it consumes the disk budget.
Small nodes Use a stricter finite cap and a short repair objective. On a small volume, preserving the primary is usually more important than keeping a stale replica or CDC slot resumable forever.

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 30GB different {{ ([pg_size_twentieth * 6, 3000])|min }}GB
OLAP 30GB different {{ ([pg_size_twentieth * 6, 3000])|min }}GB
CRIT 30GB different {{ ([pg_size_twentieth * 6, 3000])|min }}GB
TINY 30GB different {{ ([pg_size_twentieth * 6, 3000])|min }}GB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG13–19 Beta 3 = 30GB (dcs); OLAP: PG13–19 Beta 3 = 30GB (dcs); CRIT: PG13–19 Beta 3 = 30GB (dcs); TINY: PG13–19 Beta 3 = 30GB (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

  • Leaving -1 and assuming a stalled slot cannot fill the disk.
  • Treating the finite value as an instantaneous hard ceiling despite checkpoint-based enforcement.
  • Setting it too low and invalidating a healthy consumer during a planned bulk load.
  • Assuming a consumer can always resume after its required WAL has been removed.
  • Confusing this per-slot retention cap with the wal_keep_size retention floor.

Related parameters

max_replication_slots · wal_keep_size · max_wal_size · idle_replication_slot_timeout · checkpoint_timeout · archive_mode

References

10.10 - max_standby_archive_delay

max_standby_archive_delay — Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data. Observed in PG9.0–19 Beta 3; its last measured boot default is 30 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Standby Servers
Upstream classification
Latest boot value Value30000
30 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 30000 ms 30 s

How it works

Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

While replaying WAL fetched from an archive, recovery may wait up to this accumulated delay for conflicting hot-standby queries before canceling them. It is measured against replay progress, not granted afresh to every query; -1 can let replay lag without bound.

Monitor and change max_standby_archive_delay together with max_standby_streaming_delay, hot_standby, hot_standby_feedback. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size max_standby_archive_delay from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 10min different 10min
OLAP 10min different 10min
CRIT 10min different 10min
TINY 10min different 10min
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 10min (dcs); OLAP: PG9.0–19 Beta 3 = 10min (dcs); CRIT: PG9.0–19 Beta 3 = 10min (dcs); TINY: PG9.0–19 Beta 3 = 10min (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to favor bounded read continuity while a standby catches up from archived WAL; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_standby_streaming_delay · hot_standby · hot_standby_feedback · recovery_min_apply_delay · primary_conninfo · primary_slot_name

References

10.11 - max_standby_streaming_delay

max_standby_streaming_delay — Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data. Observed in PG9.0–19 Beta 3; its last measured boot default is 30 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Standby Servers
Upstream classification
Latest boot value Value30000
30 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 30000 ms 30 s

How it works

Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

While replaying streamed WAL, recovery may wait up to this accumulated delay for conflicting queries before cancellation. Larger values favor read continuity but raise replication lag and recovery-point exposure; hot_standby_feedback addresses some snapshot conflicts with primary-side bloat risk.

Monitor and change max_standby_streaming_delay together with max_standby_archive_delay, hot_standby, hot_standby_feedback. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size max_standby_streaming_delay from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 3min different 3min
OLAP 3min different 3min
CRIT 3min different 3min
TINY 3min different 3min
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 3min (dcs); OLAP: PG9.0–19 Beta 3 = 3min (dcs); CRIT: PG9.0–19 Beta 3 = 3min (dcs); TINY: PG9.0–19 Beta 3 = 3min (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to allow short analytical reads on a streaming standby without permitting unbounded replay lag; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_standby_archive_delay · hot_standby · hot_standby_feedback · recovery_min_apply_delay · in_hot_standby · primary_conninfo

References

10.12 - max_sync_workers_per_subscription

max_sync_workers_per_subscription — Maximum number of workers per subscription for synchronizing tables and sequences. Observed in PG10–19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Maximum number of workers per subscription for synchronizing tables and sequences.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Subscribers
Upstream classification
Latest boot value Value2
2

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit 7c4f52409a8c — Logical replication support for initial data copy
Commit date 2017-03-23
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 2 — 2

How it works

Maximum number of table synchronization workers per subscription. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Initial table copies use synchronization workers up to this per-subscription ceiling. They share max_logical_replication_workers and max_worker_processes with apply workers, so the configured number is not a guaranteed concurrency level.

Monitor and change max_sync_workers_per_subscription together with max_logical_replication_workers, max_parallel_apply_workers_per_subscription, max_worker_processes. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size max_sync_workers_per_subscription from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 6 different 6
OLAP 6 different 6
CRIT 6 different 6
TINY 6 different 6
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG10–19 Beta 3 = 6 (dcs); OLAP: PG10–19 Beta 3 = 6 (dcs); CRIT: PG10–19 Beta 3 = 6 (dcs); TINY: PG10–19 Beta 3 = 6 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to accelerate initial logical-replication table copies within the global worker budget; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_logical_replication_workers · max_parallel_apply_workers_per_subscription · max_worker_processes · max_replication_slots · max_active_replication_origins · hot_standby

References

10.13 - max_wal_senders

max_wal_senders — Sets the maximum number of simultaneously running WAL sender processes. Observed in PG9.0–19 Beta 3; its last measured boot default is 10 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of simultaneously running WAL sender processes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value10
10

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.6 0 — 0
PG10–19 Beta 3 10 — 10

How it works

Sets the maximum number of simultaneously running WAL sender processes. The value is fixed when the server starts, so changing it requires a restart.

Each streaming standby, WAL-streaming base backup, or logical replication connection can occupy a WAL sender. Zero disables sending, disconnected clients may retain a slot until timeout, and a standby must reserve at least as many senders as its primary to accept hot-standby queries safely.

Monitor and change max_wal_senders together with wal_level, max_replication_slots, archive_mode. 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

Tip

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

Workload Guidance
OLTP Size max_wal_senders from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 50 different 50
OLAP 50 different 50
CRIT 50 different 50
TINY 50 different 50
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 50 (dcs); OLAP: PG9.0–19 Beta 3 = 50 (dcs); CRIT: PG9.0–19 Beta 3 = 50 (dcs); TINY: PG9.0–19 Beta 3 = 50 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to reserve connection headroom for replicas, backups, and logical clients; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

wal_level · max_replication_slots · archive_mode · wal_log_hints · output_plugin_libraries · wal_sender_timeout

References

10.14 - output_plugin_libraries

output_plugin_libraries lists libraries that may be named as logical decoding output plugins. It is a superuser setting present in PG14–18; the latest recorded boot default is pgoutput, test_decoding.
Note

Fact — official short description: “Lists libraries that may be named as logical decoding output plugins.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Valuepgoutput, test_decoding
pgoutput, test_decoding

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit bf3842a64f5d — Add an output_plugin_libraries GUC to bless trusted output plugins
Commit date 2026-08-10
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 pgoutput, test_decoding — pgoutput, test_decoding

How it works

Lists libraries that may be named as logical decoding output plugins. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

Logical decoding accepts only output-plugin library names on this server-side allowlist, using LOAD-style naming with an exact plugin-name match. Adding a library is a trust decision because plugin code executes inside the server process.

Monitor and change output_plugin_libraries together with wal_level, max_wal_senders, max_replication_slots. Validate on the relevant server role and real workload, then use its superuser context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP List only installed, audited output plugins with a real consumer. Test with a least-privilege replication role and include plugin upgrades in the server release process.
OLAP ETL decoding plugins are still in-process code; do not use broad paths for convenience. Test large-transaction memory, WAL retention, and plugin output.
Small nodes Keep the small built-in allowlist without logical decoding. Before adding wal2json or another plugin, establish package provenance, version compatibility, and maintenance ownership.

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 pgoutput, test_decoding, wal2json different 'pgoutput, test_decoding, wal2json'
OLAP pgoutput, test_decoding, wal2json different 'pgoutput, test_decoding, wal2json'
CRIT pgoutput, test_decoding, wal2json different 'pgoutput, test_decoding, wal2json'
TINY pgoutput, test_decoding, wal2json different 'pgoutput, test_decoding, wal2json'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs); OLAP: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs); CRIT: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs); TINY: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to make wal2json available while preserving a narrow explicit output-plugin allowlist; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

wal_level · max_wal_senders · max_replication_slots · archive_mode · wal_log_hints · shared_preload_libraries

References

10.15 - primary_conninfo

primary_conninfo sets the connection string to be used to connect to the sending server. It is a sighup setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the connection string to be used to connect to the sending server.”

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 ValueReplication / Standby Servers
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the connection string to be used to connect to the sending server. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The WAL receiver uses this libpq connection string to reach an upstream sender. Reloading a changed nonempty value restarts the receiver; credentials should come from a protected passfile where possible, and slot synchronization additionally requires dbname.

Monitor and change primary_conninfo together with max_wal_senders, max_replication_slots, wal_level. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size primary_conninfo from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Embedding a plaintext password in broadly readable configuration or process diagnostics.
  • Omitting dbname when slot synchronization needs it.
  • Changing upstream identity without coordinating timeline and slot state.
  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Related parameters

max_wal_senders · max_replication_slots · wal_level · wal_sender_timeout · max_slot_wal_keep_size · primary_slot_name

References

10.16 - primary_slot_name

primary_slot_name sets the name of the replication slot to use on the sending server. It is a sighup setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the name of the replication slot to use on the sending server.”

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 ValueReplication / Standby Servers
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the name of the replication slot to use on the sending server. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The receiver names an existing upstream physical slot so the sender retains WAL needed by this standby. It improves continuity across disconnects but transfers disk-retention risk to the primary and must match slot lifecycle during failover.

Monitor and change primary_slot_name together with wal_keep_segments, wal_keep_size, wal_segment_size. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size primary_slot_name from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Creating a slot without monitoring restart_lsn and primary disk usage.
  • Dropping or reusing the slot during failover without proving consumer position.
  • Assuming a slot alone archives or backs up WAL.
  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Related parameters

wal_keep_segments · wal_keep_size · wal_segment_size · max_slot_wal_keep_size · max_wal_size · idle_replication_slot_timeout

References

10.17 - promote_trigger_file

promote_trigger_file specifies a file name whose presence ends recovery in the standby. It appears in the PG12–15 evidence matrix and was removed in PG16. PostgreSQL 16 removed the trigger-file mechanism; use pg_ctl promote or pg_promote() through the HA controller.
Note

Fact — official short description: “Specifies a file name whose presence ends recovery in the standby.”

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 ValueReplication / Standby Servers
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–15
Removed in PG16
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Specifies a file name whose presence ends recovery in the standby. The parameter still exists in PG15 and is no longer recognized from PG16. PostgreSQL 16 removed the trigger-file mechanism; use pg_ctl promote or pg_promote() through the HA controller.

While present, the startup/recovery configuration watched for this path and promoted when the file appeared. File races, stale files, and shared-storage semantics made orchestration fragile; PostgreSQL 16 removed the setting.

Before upgrading, inspect hot_standby, hot_standby_feedback, max_standby_archive_delay, remove the old name from configuration, ALTER SYSTEM, role/database settings, and automation templates, and verify the replacement before starting PG16 or later.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or continue emitting promote_trigger_file on PG16+. PostgreSQL 16 removed the trigger-file mechanism; use pg_ctl promote or pg_promote() through the HA controller. Scan every configuration layer and regression-test the application before upgrade.
OLAP Use the same migration path as OLTP, and also verify long batches, standbys, or large-object/extension workflows; removal of the old switch does not promise identical legacy behavior.
Small nodes Delete the obsolete setting and adopt the supported replacement directly; do not emulate legacy behavior in scripts without a demonstrated compatibility requirement.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG15; 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: PG12–15 unmodified; OLAP: PG12–15 unmodified; CRIT: PG12–15 unmodified; TINY: PG12–15 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Continuing to emit unknown parameter promote_trigger_file on PG16+.
  • Deleting only the setting name without migrating dependent application behavior.
  • Assuming the historical default equals the replacement mechanism’s default.
  • Missing stale entries in ALTER SYSTEM, role/database settings, or automation templates.

Related parameters

hot_standby · hot_standby_feedback · max_standby_archive_delay · max_standby_streaming_delay · primary_conninfo · primary_slot_name

References

10.18 - recovery_min_apply_delay

recovery_min_apply_delay sets the minimum delay for applying changes during recovery. It is a sighup setting present in PG12–18; the latest recorded boot default is 0 ms.
Note

Fact — official short description: “Sets the minimum delay for applying changes during recovery.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Standby Servers
Upstream classification
Latest boot value Value0
0 ms

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 0 ms 0 ms

How it works

Sets the minimum delay for applying changes during recovery. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

A standby delays replay of each transaction commit until the configured time has elapsed since the primary’s commit timestamp. Network/cascade lag counts toward the delay, clocks matter, and synchronous_commit=remote_apply makes primary commits wait through the intentional delay.

Monitor and change recovery_min_apply_delay together with max_standby_archive_delay, max_standby_streaming_delay, hot_standby. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size recovery_min_apply_delay from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_standby_archive_delay · max_standby_streaming_delay · hot_standby · hot_standby_feedback · primary_conninfo · primary_slot_name

References

10.19 - replication_timeout

replication_timeout — Sets the maximum time to wait for WAL replication. Observed in PG9.1–9.2; its last measured boot default is 1 min in PG9.2, with sighup context. It was removed in PG9.3.
Note

Fact — official short description: “Sets the maximum time to wait for WAL replication.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value60000
1 min

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–9.2
Removed in PG9.3
Introduction commit 754baa21f723 — Automatically terminate replication connections that are idle for more than replication_timeout (a new GUC) milliseconds. The TCP timeout is often too long, you want the master to notice a dead connection much sooner. People complained about that in 9.0 too, but with synchronous replication it’s even more important to notice dead connections promptly.
Commit date 2011-03-30
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–9.2 60000 ms 1 min

How it works

PostgreSQL describes replication_timeout as follows: “Sets the maximum time to wait for WAL replication.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG9.1–9.2; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

This early streaming-replication timeout let a sender terminate an inactive connection. PostgreSQL 9.3 replaced the name with wal_sender_timeout; receiver-side failure detection is separately controlled by wal_receiver_timeout, so migration must preserve which side of the connection owns the timer.

Read it together with wal_sender_timeout, wal_receiver_timeout, wal_receiver_status_interval, max_wal_senders. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.2; 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: PG9.1–9.2 unmodified; OLAP: PG9.1–9.2 unmodified; CRIT: PG9.1–9.2 unmodified; TINY: PG9.1–9.2 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for replication_timeout as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

wal_sender_timeout · wal_receiver_timeout · wal_receiver_status_interval · max_wal_senders

References

10.20 - sync_replication_slots

sync_replication_slots enables a physical standby to synchronize logical failover replication slots from the primary server. It is a sighup setting present in PG17–18; the latest recorded boot default is off.
Note

Fact — official short description: “Enables a physical standby to synchronize logical failover replication slots from the primary server.”

Identity

Type Valuebool
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 ValueReplication / Standby Servers
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 93db6cbda037 — Add a new slot sync worker to synchronize logical slots.
Commit date 2024-02-22
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 off — off

How it works

Enables the slotsync worker on a physical standby to copy logical failover-slot state from its primary. A configuration reload applies a new value.

Synchronization requires a physical replication slot between primary and standby (primary_slot_name on the standby), hot_standby_feedback=on, and primary_conninfo containing a valid dbname. The logical source slots must have failover enabled.

Slot state is copied asynchronously. The primary should list the standby’s physical slot in synchronized_standby_slots so subscribers cannot outrun the failover standby, and operators must verify that every required slot is synchronized and ready before promotion.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable it only as part of a complete logical-failover design. Automate prerequisite checks and block planned promotion until all required failover slots report synchronized, non-conflicting state.
OLAP Large transactions and delayed standbys can increase synchronization lag. Monitor subscriber confirmed positions, standby replay, physical-slot retention, and catalog horizon together.
Small nodes Do not enable it merely because the switch is available. A small deployment still needs a permanent physical slot, hot_standby_feedback, dbname, retention limits, and a tested failover runbook.

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 true different on
OLAP true different on
CRIT true different on
TINY true different on
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG17–19 Beta 3 = True (dcs); OLAP: PG17–19 Beta 3 = True (dcs); CRIT: PG17–19 Beta 3 = True (dcs); TINY: PG17–19 Beta 3 = True (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to prepare logical failover slots on physical standbys for controlled failover; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Enabling it without primary_slot_name and therefore without the mandatory physical slot.
  • Leaving hot_standby_feedback off, which prevents safe catalog-row retention for synchronized logical slots.
  • Omitting dbname from primary_conninfo.
  • Synchronizing ordinary logical slots that were not created with failover enabled and expecting them to appear.
  • Promoting before checking that every required slot is synchronized and not behind its subscriber.

Related parameters

primary_slot_name · hot_standby_feedback · primary_conninfo · synchronized_standby_slots · max_replication_slots · max_slot_wal_keep_size

References

10.21 - synchronized_standby_slots

synchronized_standby_slots lists streaming replication standby server replication slot names that logical WAL sender processes will wait for. It is a sighup setting present in PG17–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Lists streaming replication standby server replication slot names that logical WAL sender processes will wait for.”

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 ValueReplication / Primary Server
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 0f934b0739ad — Rename standby_slot_names to synchronized_standby_slots.
Commit date 2024-07-01
Discussion thread 1

Default history

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

How it works

Lists streaming replication standby server replication slot names that logical WAL sender processes will wait for. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Logical senders on the primary wait until every listed physical standby slot has confirmed the relevant WAL before decoding sends changes. This protects failover-slot continuity, but a missing, invalid, or stalled listed slot can stop logical replication and slot-management functions.

Monitor and change synchronized_standby_slots together with sync_replication_slots, primary_slot_name, max_replication_slots. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size synchronized_standby_slots from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Listing a missing or invalid slot and blocking logical senders.
  • Confusing physical slot names with standby application_name values.
  • Failing to enable sync_replication_slots on the corresponding standbys.
  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Related parameters

sync_replication_slots · primary_slot_name · max_replication_slots · max_slot_wal_keep_size · synchronous_standby_names · vacuum_defer_cleanup_age

References

10.22 - synchronous_standby_names

synchronous_standby_names — Number of synchronous standbys and list of names of potential synchronous ones. Observed in PG9.1–19 Beta 3; its last measured boot default is empty string in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Number of synchronous standbys and list of names of potential synchronous ones.”

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 ValueReplication / Primary Server
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit a8a8a3e09652 — Efficient transaction-controlled synchronous replication. If a standby is broadcasting reply messages and we have named one or more standbys in synchronous_standby_names then allow users who set synchronous_replication to wait for commit, which then provides strict data integrity guarantees. Design avoids sending and receiving transaction state information so minimises bookkeeping overheads. We synchronize with the highest priority standby that is connected and ready to synchronize. Other standbys can be defined to takeover in case of standby failure.
Commit date 2011-03-06
Discussion —

Default history

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

How it works

Number of synchronous standbys and list of names of potential synchronous ones. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

This parses priority FIRST or quorum ANY syntax over standby application_name values. It only defines eligible acknowledgers; synchronous_commit selects what each transaction waits for, and duplicate or wildcard names can make the chosen standby surprising.

Monitor and change synchronous_standby_names together with synchronous_commit, wal_sender_timeout, max_wal_senders. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size synchronous_standby_names from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Assuming the list alone makes every transaction synchronous.
  • Using duplicate application_name values and getting nondeterministic priority.
  • Choosing ANY/FIRST counts that cannot be satisfied during planned maintenance.
  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Related parameters

synchronous_commit · wal_sender_timeout · max_wal_senders · application_name · synchronized_standby_slots · vacuum_defer_cleanup_age

References

10.23 - track_commit_timestamp

track_commit_timestamp — Collects transaction commit time. Observed in PG9.5–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Collects transaction commit time.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 73c986adde5d — Keep track of transaction commit timestamps
Commit date 2014-12-03
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–19 Beta 3 off — off

How it works

Collects transaction commit time. The value is fixed when the server starts, so changing it requires a restart.

PostgreSQL stores transaction commit timestamps in an auxiliary SLRU so SQL and replication-origin features can query them later. It must be enabled at startup before the history is collected and adds storage/I/O overhead; it cannot reconstruct older timestamps.

Monitor and change track_commit_timestamp together with max_active_replication_origins, max_logical_replication_workers, max_replication_slots. 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

Tip

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

Workload Guidance
OLTP Size track_commit_timestamp from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.5–19 Beta 3 = on (dcs); OLAP: PG9.5–19 Beta 3 = on (dcs); CRIT: PG9.5–19 Beta 3 = on (dcs); TINY: PG9.5–19 Beta 3 = on (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to make commit-time metadata available for diagnostics and replication workflows; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_active_replication_origins · max_logical_replication_workers · max_replication_slots · idle_replication_slot_timeout · max_slot_wal_keep_size · max_wal_senders

References

10.24 - vacuum_defer_cleanup_age

vacuum_defer_cleanup_age — Number of transactions by which VACUUM and HOT cleanup should be deferred, if any. Observed in PG9.0–15; its last measured boot default is 0 in PG15, with sighup context. It was removed in PG16.
Note

Fact — official short description: “Number of transactions by which VACUUM and HOT cleanup should be deferred, if any.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 1000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Primary Server
Upstream classification
Latest boot value Value0
0

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–15
Removed in PG16
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–15 0 — 0

How it works

Number of transactions by which VACUUM and HOT cleanup should be deferred, if any. The parameter still exists in PG15 and is no longer recognized from PG16. PostgreSQL 16 removed this transaction-count delay; use hot_standby_feedback, replication slots, and bounded standby-conflict policy according to the actual requirement.

This postponed removal of recently dead tuples by a fixed number of transactions on the primary, an imprecise way to protect standby queries. It could retain bloat without guaranteeing a wall-clock delay and was removed in PostgreSQL 16.

Before upgrading, inspect synchronized_standby_slots, synchronous_standby_names, hot_standby, remove the old name from configuration, ALTER SYSTEM, role/database settings, and automation templates, and verify the replacement before starting PG16 or later.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or continue emitting vacuum_defer_cleanup_age on PG16+. PostgreSQL 16 removed this transaction-count delay; use hot_standby_feedback, replication slots, and bounded standby-conflict policy according to the actual requirement. Scan every configuration layer and regression-test the application before upgrade.
OLAP Use the same migration path as OLTP, and also verify long batches, standbys, or large-object/extension workflows; removal of the old switch does not promise identical legacy behavior.
Small nodes Delete the obsolete setting and adopt the supported replacement directly; do not emulate legacy behavior in scripts without a demonstrated compatibility requirement.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG15; 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 500000 different 500000
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–15 unmodified; OLAP: PG9.0–15 unmodified; CRIT: PG9.0–15 = 500000 (dcs); TINY: PG9.0–15 unmodified. Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to historically protect CRIT standby reads by postponing cleanup, a policy that now requires migration; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Continuing to emit unknown parameter vacuum_defer_cleanup_age on PG16+.
  • Deleting only the setting name without migrating dependent application behavior.
  • Assuming the historical default equals the replacement mechanism’s default.
  • Missing stale entries in ALTER SYSTEM, role/database settings, or automation templates.

Related parameters

synchronized_standby_slots · synchronous_standby_names · hot_standby · hot_standby_feedback · idle_replication_slot_timeout · max_active_replication_origins

References

10.25 - wal_keep_segments

wal_keep_segments — Sets the number of WAL files held for standby servers. Observed in PG9.0–12; its last measured boot default is 0 in PG12, with sighup context. It was removed in PG13.
Note

Fact — official short description: “Sets the number of WAL files held for standby servers.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value0
0

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–12
Removed in PG13
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–12 0 — 0

How it works

Sets the number of WAL files held for standby servers. The parameter still exists in PG12 and is no longer recognized from PG13. PostgreSQL 13 replaced the segment-count interface with wal_keep_size, which expresses the retention floor in bytes rather than assuming a segment size.

This retained at least a count of old WAL segments for lagging standbys, so its byte effect changed with wal_segment_size. It was only a floor—not protection from every retention/removal condition—and PostgreSQL 13 replaced it with wal_keep_size.

Before upgrading, inspect wal_keep_size, wal_segment_size, max_slot_wal_keep_size, remove the old name from configuration, ALTER SYSTEM, role/database settings, and automation templates, and verify the replacement before starting PG13 or later.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or continue emitting wal_keep_segments on PG13+. PostgreSQL 13 replaced the segment-count interface with wal_keep_size, which expresses the retention floor in bytes rather than assuming a segment size. Scan every configuration layer and regression-test the application before upgrade.
OLAP Use the same migration path as OLTP, and also verify long batches, standbys, or large-object/extension workflows; removal of the old switch does not promise identical legacy behavior.
Small nodes Delete the obsolete setting and adopt the supported replacement directly; do not emulate legacy behavior in scripts without a demonstrated compatibility requirement.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG12; 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: PG9.0–12 unmodified; OLAP: PG9.0–12 unmodified; CRIT: PG9.0–12 unmodified; TINY: PG9.0–12 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Copying the old integer directly to wal_keep_size without multiplying by wal_segment_size.
  • Treating the retained count as a maximum rather than a minimum floor.
  • Leaving the removed name in PG13+ automation.
  • Continuing to emit unknown parameter wal_keep_segments on PG13+.
  • Deleting only the setting name without migrating dependent application behavior.

Related parameters

wal_keep_size · wal_segment_size · max_slot_wal_keep_size · max_wal_size · primary_slot_name · idle_replication_slot_timeout

References

10.26 - wal_keep_size

A reloadable minimum amount of old WAL retained for streaming standbys that might fall behind. It is present from PG13 in this catalog, defaults to 0 MB, and is unmodified by all Pigsty templates.
Note

Fact — official short description: “Sets the size of WAL files held for standby servers.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit ValueMB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value0
0 B

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit f5dff45962ec — Rename wal_keep_segments to wal_keep_size.
Commit date 2020-07-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 0 MB 0 B

How it works

The sender keeps at least wal_keep_size megabytes of past WAL in pg_wal so a lagging standby can continue streaming without an older segment disappearing. If the standby falls behind beyond the available files, streaming disconnects; an archive can supply the missing segment if one exists.

This is a retention floor, not an exact reservation or a maximum. Checkpoint recovery needs, archiving, replication slots, and recent WAL-usage estimates can retain more. A value of zero means PostgreSQL reserves no extra WAL specifically for standbys, not that pg_wal contains no old WAL.

Replication slots retain WAL according to an individual consumer’s confirmed position and are usually more precise. wal_keep_size is still useful as simple insurance for slotless or temporarily reconnecting standbys, but capacity should be based on peak WAL rate multiplied by the intended outage window.

Tuning advice

Tip

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

Workload Guidance
OLTP Prefer monitored replication slots plus a tested archive for durable protection. If a nonzero floor is needed, calculate it from peak WAL bytes per second and tolerated disconnection time, then add margin and alert on replication lag.
OLAP Static retention can be overwhelmed by a short bulk-load burst. Use slots or an archive for consumers that must survive such bursts, and size any wal_keep_size floor against peak rather than average WAL generation.
Small nodes Leave it at 0 when slots and archive recovery are reliable. Otherwise choose a modest bounded floor that cannot consume the disk budget during an unrelated archive or slot incident.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating wal_keep_size as a maximum for pg_wal usage.
  • Reading 0 as ‘retain no WAL’ rather than ‘retain no extra WAL for standby purposes’.
  • Sizing from average WAL rate and failing during batch-generated peaks.
  • Assuming it guarantees recovery after a standby exceeds the retained window.
  • Forgetting the predecessor parameter wal_keep_segments when comparing PG12 and PG13.

Related parameters

wal_keep_segments · max_replication_slots · max_slot_wal_keep_size · archive_mode · max_wal_size · primary_slot_name

References

10.27 - wal_receiver_create_temp_slot

wal_receiver_create_temp_slot sets whether a WAL receiver should create a temporary replication slot if no permanent slot is configured. It is a sighup setting present in PG13–18; the latest recorded boot default is off.
Note

Fact — official short description: “Sets whether a WAL receiver should create a temporary replication slot if no permanent slot is configured.”

Identity

Type Valuebool
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 ValueReplication / Standby Servers
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 329730827848 — walreceiver uses a temporary replication slot by default
Commit date 2020-01-14
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 off — off

How it works

Sets whether a WAL receiver should create a temporary replication slot if no permanent slot is configured. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

If primary_slot_name is empty, the receiver can create a temporary upstream slot for the lifetime of its connection. That prevents removal during the connection but vanishes on disconnect, so it cannot guarantee catch-up across an outage.

Monitor and change wal_receiver_create_temp_slot together with primary_slot_name, max_replication_slots, max_slot_wal_keep_size. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size wal_receiver_create_temp_slot from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

primary_slot_name · max_replication_slots · max_slot_wal_keep_size · wal_keep_size · hot_standby · hot_standby_feedback

References

10.28 - wal_receiver_status_interval

wal_receiver_status_interval — Sets the maximum interval between WAL receiver status reports to the sending server. Observed in PG9.1–19 Beta 3; its last measured boot default is 10 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum interval between WAL receiver status reports to the sending server.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value0 – 2147483
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Standby Servers
Upstream classification
Latest boot value Value10
10 s

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit b186523fd97c — Send status updates back from standby server to master, indicating how far the standby has written, flushed, and applied the WAL. At the moment, this is for informational purposes only, the values are only shown in pg_stat_replication system view, but in the future they will also be needed for synchronous replication.
Commit date 2011-02-10
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 10 s 10 s

How it works

Sets the maximum interval between WAL receiver status reports to the sending server. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The receiver sends write, flush, and replay positions upstream at most this far apart, with additional replies when requested. Lower values improve monitoring and feedback freshness but do not make WAL replay itself faster.

Monitor and change wal_receiver_status_interval together with wal_receiver_timeout, wal_sender_timeout, primary_conninfo. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size wal_receiver_status_interval from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 1s different 1s
OLAP 1s different 1s
CRIT 1s different 1s
TINY 1s different 1s
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.1–19 Beta 3 = 1s (dcs); OLAP: PG9.1–19 Beta 3 = 1s (dcs); CRIT: PG9.1–19 Beta 3 = 1s (dcs); TINY: PG9.1–19 Beta 3 = 1s (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to provide fresher replay/flush feedback to senders and monitoring; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

wal_receiver_timeout · wal_sender_timeout · primary_conninfo · hot_standby_feedback · hot_standby · max_standby_archive_delay

References

10.29 - wal_receiver_timeout

wal_receiver_timeout — Sets the maximum wait time to receive data from the sending server. Observed in PG9.3–19 Beta 3; its last measured boot default is 1 min in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum wait time to receive data from the sending server.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Standby Servers
Upstream classification
Latest boot value Value60000
1 min

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit 6f60fdd7015b — Improve replication connection timeouts.
Commit date 2012-10-11
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 60000 ms 1 min

How it works

Sets the maximum wait time to receive data from the sending server. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

A standby terminates its receiver after this period without sender data, then reconnects according to recovery behavior. It is failure detection, not an end-to-end failover deadline, and must tolerate expected network pauses.

Monitor and change wal_receiver_timeout together with primary_conninfo, primary_slot_name, restore_command. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size wal_receiver_timeout from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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 60s same as boot 60s
OLAP 60s same as boot 60s
CRIT 60s same as boot 60s
TINY 60s same as boot 60s
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.3–19 Beta 3 = 60s (dcs); OLAP: PG9.3–19 Beta 3 = 60s (dcs); CRIT: PG9.3–19 Beta 3 = 60s (dcs); TINY: PG9.3–19 Beta 3 = 60s (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to state a one-minute receiver failure-detection window explicitly; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

primary_conninfo · primary_slot_name · restore_command · wal_retrieve_retry_interval · hot_standby · wal_receiver_status_interval

References

10.30 - wal_retrieve_retry_interval

wal_retrieve_retry_interval — Sets the time to wait before retrying to retrieve WAL after a failed attempt. Observed in PG9.5–19 Beta 3; its last measured boot default is 5 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the time to wait before retrying to retrieve WAL after a failed attempt.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Standby Servers
Upstream classification
Latest boot value Value5000
5 s

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 5d2b45e3f78a — Add GUC to control the time to wait before retrieving WAL after failed attempt.
Commit date 2015-02-23
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–19 Beta 3 5000 ms 5 s

How it works

Sets the time to wait before retrying to retrieve WAL after a failed attempt. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

After archive, local pg_wal, and streaming retrieval fail, recovery waits this long before another attempt. Small values reduce recovery/standby reaction time but can hammer a missing archive or noisy network with retries.

Monitor and change wal_retrieve_retry_interval together with primary_conninfo, primary_slot_name, restore_command. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size wal_retrieve_retry_interval from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG9.5–19 Beta 3 unmodified; OLAP: PG9.5–19 Beta 3 unmodified; CRIT: PG9.5–19 Beta 3 unmodified; TINY: PG9.5–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

primary_conninfo · primary_slot_name · restore_command · wal_receiver_timeout · hot_standby · hot_standby_feedback

References

10.31 - wal_sender_delay

wal_sender_delay — WAL sender sleep time between WAL replications. Observed in PG9.0–9.1; its last measured boot default is 1 s in PG9.1, with sighup context. It was removed in PG9.2.
Note

Fact — official short description: “WAL sender sleep time between WAL replications.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value1 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Master Server
Upstream classification
Latest boot value Value1000
1 s

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.1
Removed in PG9.2
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 200 ms 200 ms
PG9.1 1000 ms 1 s

How it works

PostgreSQL describes wal_sender_delay as follows: “WAL sender sleep time between WAL replications.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG9.0–9.1; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

Early WAL senders slept for this interval between attempts to ship more WAL. It disappeared after PostgreSQL 9.1 as sender wakeup and streaming behavior evolved; modern latency and liveness controls are wal_sender_timeout, wal_receiver_status_interval, and wal_receiver_timeout, not a polling delay.

Read it together with wal_sender_timeout, wal_receiver_status_interval, wal_receiver_timeout, max_wal_senders. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.1; 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: PG9.0–9.1 unmodified; OLAP: PG9.0–9.1 unmodified; CRIT: PG9.0–9.1 unmodified; TINY: PG9.0–9.1 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for wal_sender_delay as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

wal_sender_timeout · wal_receiver_status_interval · wal_receiver_timeout · max_wal_senders

References

10.32 - wal_sender_shutdown_timeout

wal_sender_shutdown_timeout — Sets the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver. Observed in PG19 Beta 3; its last measured boot default is -1 ms in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value-1
-1 ms

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit a8f45dee9176 — Add wal_sender_shutdown_timeout GUC to limit shutdown wait for replication
Commit date 2026-04-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 -1 ms -1 ms

How it works

PostgreSQL describes wal_sender_shutdown_timeout as follows: “Sets the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. 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.

During shutdown a sender normally waits until outstanding WAL reaches its receiver. The default -1 waits without a timeout, zero stops immediately, and a positive interval bounds the wait at the cost of possible sender/receiver divergence; connection options can set different policies for physical and logical replication links.

Read it together with wal_sender_timeout, wal_receiver_timeout, synchronous_commit, synchronous_standby_names. 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

Tip

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

Workload Guidance
OLTP Model normal failover and worst-case lag before setting a bound. Observe sender state, retained WAL, shutdown time, and receiver catch-up; preserve enough capacity for monitoring and planned switchovers.
OLAP Account for large transactions, bulk loads, slow apply, and long-distance links. A short timeout can make shutdown faster but transfer recovery work and inconsistency risk to the next startup.
Small nodes Use few slots and senders, watch pg_wal disk consumption, and keep timeout behavior explicit. Test shutdown and restart with the receiver both healthy and unavailable.

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: 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 wal_sender_shutdown_timeout as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports user 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

wal_sender_timeout · wal_receiver_timeout · synchronous_commit · synchronous_standby_names · max_wal_senders

References

10.33 - wal_sender_timeout

wal_sender_timeout — Sets the maximum time to wait for WAL replication. Observed in PG9.3–19 Beta 3; its last measured boot default is 1 min in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum time to wait for WAL replication.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReplication / Sending Servers
Upstream classification
Latest boot value Value60000
1 min

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit 6f60fdd7015b — Improve replication connection timeouts.
Commit date 2012-10-11
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 60000 ms 1 min

How it works

Sets the maximum time to wait for WAL replication. It can be changed at session scope, so different sessions may observe different behavior.

A WAL sender terminates a replication connection that remains inactive for this interval. Each sender session may use a location-appropriate value; zero disables detection and very short settings cause churn across high-latency links.

Monitor and change wal_sender_timeout together with max_wal_senders, max_replication_slots, wal_level. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size wal_sender_timeout from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.
OLAP Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.
Small nodes Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.

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: PG9.3–19 Beta 3 unmodified; OLAP: PG9.3–19 Beta 3 unmodified; CRIT: PG9.3–19 Beta 3 unmodified; TINY: PG9.3–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing it on the wrong primary, standby, sender, or subscriber role.
  • Watching only configured bytes/time instead of actual lag, slot position, and worker state.
  • Failing over to a node that lacks the old primary’s capacity or prerequisites.
  • Using infinite waits or WAL retention to hide a failed consumer.

Related parameters

max_wal_senders · max_replication_slots · wal_level · primary_conninfo · max_slot_wal_keep_size · wal_receiver_status_interval

References

11 - Reporting and Logging

Complete dossiers for 47 core PostgreSQL settings in Reporting and Logging.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

11.1 - application_name

application_name is the PostgreSQL setting that defines the application name to be reported in statistics and logs.
Note

Fact — official short description: “Sets the application name to be reported in statistics and logs.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

application_name is client-supplied session metadata, usually set in the startup packet or later with SET. It appears in pg_stat_activity and CSV logs and can be inserted into text logs with the %a escape in log_line_prefix.

The value is shorter than NAMEDATALEN bytes (64 characters in a standard build). PostgreSQL permits printable ASCII; other characters are rendered as C-style hexadecimal escapes. Truncation and escaping mean log consumers must not assume the displayed value exactly matches an application’s original string.

It is a USER-context label and is not authenticated identity: any authorized client can claim a misleading value and a pooled session can retain or overwrite it. Correlate it with authenticated user, database, session ID, remote endpoint, and controlled pool checkout/reset behavior.

Tuning advice

Tip

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

Workload Guidance
OLTP Require each service and pooler to set a short, stable, non-secret application_name at checkout and reset it before reuse. Use controlled naming conventions, but never authorize or audit solely from this value.
OLAP Set a stable job or tool family label and place run-specific high-cardinality identity elsewhere. Correlate long analytical sessions with authenticated role and session ID.
Small nodes Keep labels compact and useful; node size is irrelevant. Avoid embedding tenant IDs, tokens, SQL, or unbounded request identifiers in a 64-character client-controlled field.

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

  • Treating application_name as authenticated identity or using it alone for authorization, billing, or audit attribution.
  • Exceeding NAMEDATALEN and silently losing distinguishing suffixes through truncation.
  • Assuming arbitrary Unicode is preserved rather than escaped to printable C-style hexadecimal sequences.
  • Leaking secrets or creating unbounded cardinality in logs and pg_stat_activity, or failing to reset the value in a connection pool.

Related parameters

cluster_name · update_process_title · log_line_prefix · log_timezone · log_hostname

References

11.2 - cluster_name

cluster_name is the PostgreSQL setting that defines the name of the cluster, which is included in the process title.
Note

Fact — official short description: “Sets the name of the cluster, which is included in the process title.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Process Title
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 51adcaa0df81 — Add cluster_name GUC which is included in process titles if set.
Commit date 2014-06-29
Discussion —

Default history

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

How it works

cluster_name sets the name of the cluster, which is included in the process title. It is an operator-facing label included in process titles and can distinguish several clusters running on one host; it is not a database identifier.

cluster_name is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

Process titles complement application_name, cluster_name, pg_stat_activity, and log_line_prefix, allowing operating-system observations to be joined with database activity.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep cluster_name enabled or populated for operator clarity unless profiling proves material overhead. Use stable, non-secret labels that match monitoring inventory.
OLAP Preserve cluster_name so long jobs can be attributed from operating-system and PostgreSQL views; use application_name for finer job identity.
Small nodes Do not tune cluster_name for capacity. Its observability value normally outweighs negligible overhead, but avoid high-cardinality or sensitive labels.

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: PG9.5–19 Beta 3 unmodified; OLAP: PG9.5–19 Beta 3 unmodified; CRIT: PG9.5–19 Beta 3 unmodified; TINY: PG9.5–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Expecting a reload or SET to activate cluster_name, although it requires a controlled server restart.
  • Putting secrets or unbounded high-cardinality data into operator-visible process labels.
  • Using inconsistent cluster, application, and process labels that cannot be joined across monitoring systems.
  • Changing cluster_name globally without a rollback plan and a client or operational compatibility test.

Related parameters

application_name · update_process_title · log_line_prefix · log_timezone · log_hostname

References

11.3 - debug_pretty_print

debug_pretty_print is the PostgreSQL setting that indents parse and plan tree displays.
Note

Fact — official short description: “Indents parse and plan tree displays.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

debug_pretty_print indents parse and plan tree displays. It changes only the indentation of internal parse and plan tree dumps produced by the debug_print_* switches.

debug_pretty_print is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The debug_print_* switches feed the normal server logging path, so log_min_messages, log_destination, and collector capacity determine whether the output is retained safely.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or enable debug_pretty_print globally in production. If server-developer diagnostics require it, isolate one session, bound its duration, and route the resulting logs safely.
OLAP Do not use debug_pretty_print as a substitute for EXPLAIN on analytical SQL; capture a targeted plan instead of dumping every internal tree.
Small nodes Leave debug_pretty_print at its normal default. Verbose internal trees can exhaust a small node’s log I/O and disk unexpectedly.

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

  • Changing debug_pretty_print in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Leaving an internal-tree dump enabled globally and overwhelming log I/O, storage, or ingestion.
  • Treating debug output as a stable public format or as a substitute for targeted EXPLAIN diagnostics.
  • Changing debug_pretty_print globally without a rollback plan and a client or operational compatibility test.

Related parameters

debug_print_parse · debug_print_plan · debug_print_rewritten · log_min_messages · client_min_messages

References

11.4 - debug_print_parse

debug_print_parse is the PostgreSQL setting that controls whether PostgreSQL logs each query’s parse tree.
Note

Fact — official short description: “Logs each query’s parse tree.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

debug_print_parse logs each query’s parse tree. The output is PostgreSQL’s internal parse-tree representation for every parsed query, not normalized SQL text.

debug_print_parse is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The debug_print_* switches feed the normal server logging path, so log_min_messages, log_destination, and collector capacity determine whether the output is retained safely.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or enable debug_print_parse globally in production. If server-developer diagnostics require it, isolate one session, bound its duration, and route the resulting logs safely.
OLAP Do not use debug_print_parse as a substitute for EXPLAIN on analytical SQL; capture a targeted plan instead of dumping every internal tree.
Small nodes Leave debug_print_parse at its normal default. Verbose internal trees can exhaust a small node’s log I/O and disk unexpectedly.

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

  • Changing debug_print_parse in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Leaving an internal-tree dump enabled globally and overwhelming log I/O, storage, or ingestion.
  • Treating debug output as a stable public format or as a substitute for targeted EXPLAIN diagnostics.
  • Changing debug_print_parse globally without a rollback plan and a client or operational compatibility test.

Related parameters

debug_pretty_print · debug_print_plan · debug_print_rewritten · log_min_messages · client_min_messages

References

11.5 - debug_print_plan

debug_print_plan is the PostgreSQL setting that controls whether PostgreSQL logs each query’s execution plan.
Note

Fact — official short description: “Logs each query’s execution plan.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

debug_print_plan logs each query’s execution plan. The output is an internal plan tree for every query and is much more verbose than a targeted EXPLAIN; it is intended for server debugging.

debug_print_plan is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The debug_print_* switches feed the normal server logging path, so log_min_messages, log_destination, and collector capacity determine whether the output is retained safely.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or enable debug_print_plan globally in production. If server-developer diagnostics require it, isolate one session, bound its duration, and route the resulting logs safely.
OLAP Do not use debug_print_plan as a substitute for EXPLAIN on analytical SQL; capture a targeted plan instead of dumping every internal tree.
Small nodes Leave debug_print_plan at its normal default. Verbose internal trees can exhaust a small node’s log I/O and disk unexpectedly.

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

  • Changing debug_print_plan in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Leaving an internal-tree dump enabled globally and overwhelming log I/O, storage, or ingestion.
  • Treating debug output as a stable public format or as a substitute for targeted EXPLAIN diagnostics.
  • Changing debug_print_plan globally without a rollback plan and a client or operational compatibility test.

Related parameters

debug_pretty_print · debug_print_parse · debug_print_rewritten · log_min_messages · client_min_messages

References

11.6 - debug_print_raw_parse

debug_print_raw_parse — Logs each query’s raw parse tree. Observed in PG19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Logs each query’s raw parse tree.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit 06473f5a344d — Allow to log raw parse tree.
Commit date 2025-09-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 off — off

How it works

PostgreSQL describes debug_print_raw_parse as follows: “Logs each query’s raw parse tree.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. 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 raw parse tree is emitted before parse analysis, rewriting, planning, and execution. Messages use LOG level; debug_pretty_print changes formatting, while client_min_messages and log_min_messages determine where they are visible. Output can be very large and can expose query text structure.

Read it together with debug_print_parse, debug_print_rewritten, debug_print_plan, debug_pretty_print. 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

Tip

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

Workload Guidance
OLTP Keep the upstream default until a reproducible operational need is demonstrated. Test under representative concurrency and inspect logs, latency, and the related settings before changing cluster-wide policy.
OLAP Evaluate the setting with representative long-running and batch work. Measure total runtime, resource use, log volume, and failure behavior across the whole job rather than one isolated operation.
Small nodes Minimize overrides and document rollback. A small system has less room for extra logging, workers, memory, or retained WAL, so validate the change with explicit resource limits.

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: 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 debug_print_raw_parse as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports user 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

debug_print_parse · debug_print_rewritten · debug_print_plan · debug_pretty_print · log_min_messages

References

11.7 - debug_print_rewritten

debug_print_rewritten is the PostgreSQL setting that controls whether PostgreSQL logs each query’s rewritten parse tree.
Note

Fact — official short description: “Logs each query’s rewritten parse tree.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

debug_print_rewritten logs each query’s rewritten parse tree. It exposes the query tree after rule rewriting, which is useful for diagnosing views and rules but can generate very large logs.

debug_print_rewritten is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

The debug_print_* switches feed the normal server logging path, so log_min_messages, log_destination, and collector capacity determine whether the output is retained safely.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or enable debug_print_rewritten globally in production. If server-developer diagnostics require it, isolate one session, bound its duration, and route the resulting logs safely.
OLAP Do not use debug_print_rewritten as a substitute for EXPLAIN on analytical SQL; capture a targeted plan instead of dumping every internal tree.
Small nodes Leave debug_print_rewritten at its normal default. Verbose internal trees can exhaust a small node’s log I/O and disk unexpectedly.

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

  • Changing debug_print_rewritten in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Leaving an internal-tree dump enabled globally and overwhelming log I/O, storage, or ingestion.
  • Treating debug output as a stable public format or as a substitute for targeted EXPLAIN diagnostics.
  • Changing debug_print_rewritten globally without a rollback plan and a client or operational compatibility test.

Related parameters

debug_pretty_print · debug_print_parse · debug_print_plan · log_min_messages · client_min_messages

References

11.8 - event_source

event_source is the PostgreSQL setting that defines the application name used to identify PostgreSQL messages in the event log.
Note

Fact — official short description: “Sets the application name used to identify PostgreSQL messages in the event log.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value ValuePostgreSQL
PostgreSQL

Lifecycle

Fact Value
First observed PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit d8ea33f2c027 — Support configurable eventlog application names on Windows
Commit date 2011-10-25
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.2–19 Beta 3 PostgreSQL — PostgreSQL

How it works

event_source sets the application name used to identify PostgreSQL messages in the event log. This is a Windows event-log identifier and has no effect unless eventlog is an active log destination.

event_source is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

event_source is consulted only on Windows when eventlog is selected in log_destination; Windows Event Log registration, permissions, routing, and retention supply the rest of the pipeline.

Tuning advice

Tip

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

Workload Guidance
OLTP Set event_source only for a Windows eventlog deployment, using a stable non-secret identity registered and routed by the host logging policy.
OLAP Keep the same event source across workload classes so Windows collection rules and dashboards do not fragment by profile.
Small nodes Leave event_source at its default unless eventlog is selected; changing a dormant label provides no capacity or observability 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 — —
Caution

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

Common pitfalls

  • Expecting a reload or SET to activate event_source, although it requires a controlled server restart.
  • Changing the source name without registering or updating Windows Event Log routing and access policy.
  • Expecting event_source to have any effect when eventlog is not an active log destination or the platform is not Windows.
  • Changing event_source globally without a rollback plan and a client or operational compatibility test.

Related parameters

logging_collector · log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

References

11.9 - log_autoanalyze_min_duration

log_autoanalyze_min_duration — Sets the minimum execution time above which analyze actions by autovacuum will be logged. Observed in PG19 Beta 3; its last measured boot default is 10 min in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the minimum execution time above which analyze actions by autovacuum will be logged.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value600000
10 min

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit dd3ae378301f — Add log_autoanalyze_min_duration
Commit date 2025-10-15
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 600000 ms 10 min

How it works

PostgreSQL describes log_autoanalyze_min_duration as follows: “Sets the minimum execution time above which analyze actions by autovacuum will be logged.” A configuration reload applies the value to the server without a full 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.

Zero logs every automatic ANALYZE, -1 disables these duration messages, and a positive value logs actions meeting the threshold plus relevant skips caused by locks or dropped relations. Per-table storage parameters can override it, independently from log_autovacuum_min_duration for VACUUM actions.

Read it together with log_autovacuum_min_duration, autovacuum, autovacuum_analyze_threshold, autovacuum_analyze_scale_factor. 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

Tip

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

Workload Guidance
OLTP Keep the upstream default until a reproducible operational need is demonstrated. Test under representative concurrency and inspect logs, latency, and the related settings before changing cluster-wide policy.
OLAP Evaluate the setting with representative long-running and batch work. Measure total runtime, resource use, log volume, and failure behavior across the whole job rather than one isolated operation.
Small nodes Minimize overrides and document rollback. A small system has less room for extra logging, workers, memory, or retained WAL, so validate the change with explicit resource limits.

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: 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 log_autoanalyze_min_duration as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

log_autovacuum_min_duration · autovacuum · autovacuum_analyze_threshold · autovacuum_analyze_scale_factor · log_min_messages

References

11.10 - log_autovacuum_min_duration

log_autovacuum_min_duration is the PostgreSQL setting that defines the minimum execution time above which autovacuum actions will be logged.
Note

Fact — official short description: “Sets the minimum execution time above which vacuum actions by autovacuum will be logged.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value600000
10 min

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–14 -1 ms -1 ms
PG15–19 Beta 3 600000 ms 10 min

How it works

log_autovacuum_min_duration sets the minimum execution time above which autovacuum actions will be logged. -1 disables logging autovacuum actions. 0 means log all autovacuum actions. Each qualifying automatic VACUUM or ANALYZE emits timing and work details; -1 disables these completion records and zero records every action.

log_autovacuum_min_duration is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_autovacuum_min_duration against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_autovacuum_min_duration telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_autovacuum_min_duration useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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 1s different 1s
OLAP 1s different 1s
CRIT 1s different 1s
TINY 1s different 1s
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 1s (dcs); OLAP: PG9.0–19 Beta 3 = 1s (dcs); CRIT: PG9.0–19 Beta 3 = 1s (dcs); TINY: PG9.0–19 Beta 3 = 1s (dcs). Advice, pending human review — Editorial inference: A one-second threshold makes unexpectedly slow vacuum maintenance visible across profiles without logging every fast action.

Common pitfalls

  • Editing log_autovacuum_min_duration without reloading configuration and verifying the effective value and subsequent behavior.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_autovacuum_min_duration globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_checkpoints · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

References

11.11 - log_checkpoints

log_checkpoints is the PostgreSQL setting that controls whether PostgreSQL logs each checkpoint.
Note

Fact — official short description: “Logs each checkpoint.”

Identity

Type Valuebool
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 ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–14 off — off
PG15–19 Beta 3 on — on

How it works

log_checkpoints logs each checkpoint. A checkpoint record includes elapsed phases and buffer or WAL work, exposing checkpoint cadence and write pressure rather than merely a marker.

log_checkpoints is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_checkpoints against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_checkpoints telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_checkpoints useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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 on same as boot 'on'
OLAP on same as boot 'on'
CRIT on same as boot 'on'
TINY on same as boot 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = on (dcs); OLAP: PG9.0–19 Beta 3 = on (dcs); CRIT: PG9.0–19 Beta 3 = on (dcs); TINY: PG9.0–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference: Explicit checkpoint logging preserves write-volume and timing evidence consistently, including releases where the upstream default was off.

Common pitfalls

  • Editing log_checkpoints without reloading configuration and verifying the effective value and subsequent behavior.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_checkpoints globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

References

11.12 - log_connections

log_connections is the PostgreSQL setting that controls whether PostgreSQL logs specified aspects of connection establishment and setup.
Note

Fact — official short description: “Logs specified aspects of connection establishment and setup.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser-backend
Fixed when a superuser backend starts
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

In PostgreSQL 10–17, log_connections is a Boolean that logs successful connections when enabled. PostgreSQL 18 changed it to a string list whose exact options are receipt, authentication, authorization, setup_durations, and all; the empty string disables connection logging. For compatibility, on, true, yes, and 1 mean receipt,authentication,authorization, while off, false, no, and 0 mean the empty list. Failed authentication is logged regardless of this setting.

log_connections has SUPERUSER_BACKEND context: it may be selected by a superuser or a role with the appropriate SET privilege at session start, but it cannot be changed after the backend session has started. A configuration change therefore affects new sessions only.

receipt records arrival, authentication records the original identity presented by the authentication method, authorization records successful authorization with user/database/application context, and setup_durations records total setup, backend-fork, and authentication timing. log_disconnections controls session-end records separately; connection identities and topology remain sensitive log data.

Tuning advice

Tip

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

Workload Guidance
OLTP For routine OLTP, log only the stages required by an audit or latency question; authorization is a lower-volume successful-connection trail, while receipt and authentication add pre-authorization evidence. Add setup_durations only when connection startup latency is being investigated.
OLAP Analytical sessions are fewer but longer, so authorization plus setup_durations can be useful for attributing expensive connection setup; do not use all merely because query volume is lower.
Small nodes Keep the list minimal and retain failed-authentication monitoring, which is independent of this setting. Verify that log storage and redaction can safely retain original identities and application names.

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 authorization different 'authorization'
OLAP authorization different 'authorization'
CRIT receipt,authentication,authorization different 'receipt,authentication,authorization'
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–17 unmodified, PG18–19 Beta 3 = authorization (dcs); OLAP: PG9.0–17 unmodified, PG18–19 Beta 3 = authorization (dcs); CRIT: PG9.0–17 = on (dcs), PG18–19 Beta 3 = receipt,authentication,authorization (dcs); TINY: PG9.0–19 Beta 3 unmodified. Advice, pending human review — Editorial inference: CRIT captures a fuller authentication audit trail, while PostgreSQL 18 OLTP and OLAP retain successful authorization events with lower volume; migration semantics require review.

Common pitfalls

  • Using setup instead of the valid PostgreSQL 18 option setup_durations.
  • Assuming the compatibility value on means all; it omits setup_durations and maps only to receipt, authentication, and authorization.
  • Expecting existing sessions to inherit a changed value even though the setting is fixed at backend startup.
  • Treating duplicate receipt records as attacks without accounting for clients such as psql that can probe twice, or retaining original identities without an access-control policy.

Related parameters

log_statement · log_duration · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

References

11.13 - log_destination

log_destination is the PostgreSQL setting that defines the destination for server log output.
Note

Fact — official short description: “Sets the destination for server log output.”

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 ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valuestderr
stderr

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 stderr — stderr

How it works

log_destination sets the destination for server log output. Valid values are combinations of “stderr”, “syslog”, “csvlog”, “jsonlog”, and “eventlog”, depending on the platform. Several destinations can be active at once; csvlog and jsonlog require logging_collector, while stderr, syslog, and Windows eventlog follow different transport paths.

log_destination is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The active path is composed from log_destination, logging_collector or syslog/eventlog, file naming and permissions, rotation triggers, and external shipping or retention.

Tuning advice

Tip

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

Workload Guidance
OLTP Set log_destination as part of one end-to-end logging design. Validate collector behavior, rotation, ownership, shipping, retention, and recovery from a full destination.
OLAP Size the log_destination path for bursty analytical output and verify that rotation or downstream ingestion cannot stall database processes.
Small nodes Use a bounded, easily rotated log_destination configuration and monitor free space; a small node should not retain redundant formats or unlimited files.

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 csvlog different csvlog
OLAP csvlog different csvlog
CRIT csvlog different csvlog
TINY csvlog different csvlog
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = csvlog (dcs); OLAP: PG9.0–19 Beta 3 = csvlog (dcs); CRIT: PG9.0–19 Beta 3 = csvlog (dcs); TINY: PG9.0–19 Beta 3 = csvlog (dcs). Advice, pending human review — Editorial inference: csvlog provides a stable structured record for collection and SQL-oriented analysis across every profile.

Common pitfalls

  • Editing log_destination without reloading configuration and verifying the effective value and subsequent behavior.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Changing log_destination globally without a rollback plan and a client or operational compatibility test.

Related parameters

logging_collector · log_directory · log_filename · log_rotation_age · log_rotation_size

References

11.14 - log_directory

log_directory is the PostgreSQL setting that defines the destination directory for log files.
Note

Fact — official short description: “Sets the destination directory for log files.”

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 ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valuelog
log

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.6 pg_log — pg_log
PG10–19 Beta 3 log — log

How it works

log_directory sets the destination directory for log files. Can be specified as relative to the data directory or as absolute path. A relative path is resolved below the data directory, while an absolute path can place collector-managed files on a separate filesystem.

log_directory is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The active path is composed from log_destination, logging_collector or syslog/eventlog, file naming and permissions, rotation triggers, and external shipping or retention.

Tuning advice

Tip

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

Workload Guidance
OLTP Set log_directory as part of one end-to-end logging design. Validate collector behavior, rotation, ownership, shipping, retention, and recovery from a full destination.
OLAP Size the log_directory path for bursty analytical output and verify that rotation or downstream ingestion cannot stall database processes.
Small nodes Use a bounded, easily rotated log_directory configuration and monitor free space; a small node should not retain redundant formats or unlimited files.

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 /pg/log/postgres different {{ pg_log_dir }}
OLAP /pg/log/postgres different {{ pg_log_dir }}
CRIT /pg/log/postgres different {{ pg_log_dir }}
TINY /pg/log/postgres different {{ pg_log_dir }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = /pg/log/postgres (dcs); OLAP: PG9.0–19 Beta 3 = /pg/log/postgres (dcs); CRIT: PG9.0–19 Beta 3 = /pg/log/postgres (dcs); TINY: PG9.0–19 Beta 3 = /pg/log/postgres (dcs). Advice, pending human review — Editorial inference: A dedicated /pg/log/postgres path separates PostgreSQL logs from the data directory and matches the managed filesystem layout.

Common pitfalls

  • Editing log_directory without reloading configuration and verifying the effective value and subsequent behavior.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Changing log_directory globally without a rollback plan and a client or operational compatibility test.

Related parameters

logging_collector · log_destination · log_filename · log_rotation_age · log_rotation_size

References

11.15 - log_disconnections

log_disconnections is the PostgreSQL setting that controls whether PostgreSQL logs end of a session, including duration.
Note

Fact — official short description: “Logs end of a session, including duration.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser-backend
Fixed when a superuser backend starts
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_disconnections logs end of a session, including duration. The record is emitted at session end and includes session duration, pairing naturally with connection-start identity but not proving that every abrupt failure reached the logger.

log_disconnections has SUPERUSER_BACKEND context: configuration changes apply when a new backend session starts and require superuser-level authority; established sessions keep their startup value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_disconnections against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_disconnections telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_disconnections useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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 on different 'on'
TINY Unmodified — —
Caution

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 = on (dcs); TINY: PG9.0–19 Beta 3 unmodified. Advice, pending human review — Editorial inference: CRIT records session endings and durations to complete its connection audit trail, accepting additional volume only in that profile.

Common pitfalls

  • Expecting existing sessions to inherit a new log_disconnections value even though it is fixed when each backend starts.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_disconnections globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_statement · log_duration · log_connections · log_parameter_max_length · log_parameter_max_length_on_error

References

11.16 - log_duration

log_duration is the PostgreSQL setting that controls whether PostgreSQL logs the duration of each completed SQL statement.
Note

Fact — official short description: “Logs the duration of each completed SQL statement.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_duration logs the duration of each completed SQL statement. It emits a duration for every completed statement but does not itself emit statement text; log_statement or a duration threshold supplies text when required.

log_duration is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_duration against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_duration telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_duration useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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

  • Changing log_duration in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Expecting duration records to contain SQL text when no statement-logging setting emits that text.

Related parameters

log_statement · log_connections · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

References

11.17 - log_error_verbosity

log_error_verbosity is the PostgreSQL setting that defines the verbosity of logged messages.
Note

Fact — official short description: “Sets the verbosity of logged messages.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueterse, default, verbose
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valuedefault
default

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 default — default

How it works

log_error_verbosity sets the verbosity of logged messages. TERSE suppresses detail and hints, DEFAULT retains normal diagnostics, and VERBOSE adds SQLSTATE plus source file, function, and line information.

log_error_verbosity is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_error_verbosity against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_error_verbosity telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_error_verbosity useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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

  • Changing log_error_verbosity in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_error_verbosity globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_statement · log_duration · log_connections · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

References

11.18 - log_file_mode

log_file_mode is the PostgreSQL setting that defines the file permissions for log files.
Note

Fact — official short description: “Sets the file permissions for log files.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 511
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Value384
384

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit 3ec694e17bc0 — Add a log_file_mode GUC that allows control of the file permissions set on log files created by the syslogger process.
Commit date 2010-07-16
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 384 — 384

How it works

log_file_mode is a chmod-style numeric mode for files newly created by logging_collector. Use a leading zero for customary octal notation: 0640 is not the same numeric value as decimal 640. The setting does not apply to syslog/eventlog output and does not change existing files.

It has SIGHUP context. After a reload, the new mode is used the next time logging_collector creates a file; reloading does not chmod the file that is currently open or historical files.

The effective access boundary also includes the PostgreSQL service account, file group, log_directory ownership and traversal permissions, shipping-agent group membership, and external retention copies. A group-readable mode is safe only when that group is controlled.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose the least-privileged mode that still lets the approved collector or shipping group read new files. Verify ownership after a real rotation and explicitly remediate existing files if policy changes.
OLAP Analytical logs often contain query text and identifiers, so use the same or stricter mode; larger log volume is not a reason to broaden file access.
Small nodes Keep 0600 unless a controlled local group must ship logs; if 0640 is used, audit group membership and directory permissions rather than making files world-readable.

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 0640 different '0640'
OLAP 0640 different '0640'
CRIT 0640 different '0640'
TINY 0640 different '0640'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.1–19 Beta 3 = 0640 (dcs); OLAP: PG9.1–19 Beta 3 = 0640 (dcs); CRIT: PG9.1–19 Beta 3 = 0640 (dcs); TINY: PG9.1–19 Beta 3 = 0640 (dcs). Advice, pending human review — Editorial inference: 0640 keeps log files private from other users while allowing an operational group to read and ship them.

Common pitfalls

  • Editing log_file_mode without reloading configuration and verifying the effective value and subsequent behavior.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Writing 640 instead of octal 0640 and producing a different numeric permission mode.

Related parameters

logging_collector · log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

References

11.19 - log_filename

log_filename is the PostgreSQL setting that defines the file name pattern for log files.
Note

Fact — official short description: “Sets the file name pattern for log files.”

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 ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valuepostgresql-%Y-%m-%d_%H%M%S.log
postgresql-%Y-%m-%d_%H%M%S.log

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 postgresql-%Y-%m-%d_%H%M%S.log — postgresql-%Y-%m-%d_%H%M%S.log

How it works

log_filename sets the file name pattern for log files. logging_collector expands strftime escapes using log_timezone whenever it opens a new file, so repeating names must be coordinated with rotation and truncation.

log_filename is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The active path is composed from log_destination, logging_collector or syslog/eventlog, file naming and permissions, rotation triggers, and external shipping or retention.

Tuning advice

Tip

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

Workload Guidance
OLTP Use a filename pattern whose uniqueness matches rotation policy. If names repeat, combine time-based rotation, log_truncate_on_rotation, and confirmed shipping so a reused name cannot mix periods or overwrite uncollected data.
OLAP Choose a predictable period boundary for large analytical logs and ensure downstream ingestion closes the previous file before the pattern repeats; do not rely on size rotation with a non-unique name.
Small nodes A bounded weekday or date pattern is reasonable only with matching retention and free-space monitoring. Keep enough time components to prevent accidental collisions after restart or manual rotation.

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 postgresql-%a.log different 'postgresql-%a.log'
OLAP postgresql-%a.log different 'postgresql-%a.log'
CRIT postgresql-%a.log different 'postgresql-%a.log'
TINY postgresql-%a.log different 'postgresql-%a.log'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = postgresql-%a.log (dcs); OLAP: PG9.0–19 Beta 3 = postgresql-%a.log (dcs); CRIT: PG9.0–19 Beta 3 = postgresql-%a.log (dcs); TINY: PG9.0–19 Beta 3 = postgresql-%a.log (dcs). Advice, pending human review — Editorial inference: A weekday filename creates a predictable seven-name cycle intended to work with daily rotation and truncation.

Common pitfalls

  • Editing log_filename without reloading configuration and verifying the effective value and subsequent behavior.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Using a repeating strftime name without matching rotation and truncation policy, causing append growth or overwrite surprises.

Related parameters

logging_collector · log_destination · log_directory · log_rotation_age · log_rotation_size

References

11.20 - log_hostname

log_hostname is the PostgreSQL setting that controls whether PostgreSQL logs the host name in the connection logs.
Note

Fact — official short description: “Logs the host name in the connection logs.”

Identity

Type Valuebool
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 ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_hostname logs the host name in the connection logs. By default, connection logs only show the IP address of the connecting host. If you want them to show the host name you can turn this on, but depending on your host name resolution setup it might impose a non-negligible performance penalty. Reverse DNS is performed to turn client addresses into names, which can add connection latency or stalls when name service is slow.

log_hostname is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_hostname against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_hostname telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_hostname useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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

  • Editing log_hostname without reloading configuration and verifying the effective value and subsequent behavior.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Turning on reverse DNS where resolver latency lies on the connection path.

Related parameters

application_name · cluster_name · update_process_title · log_line_prefix · log_timezone

References

11.21 - log_line_prefix

log_line_prefix is the PostgreSQL setting that controls information prefixed to each log line.
Note

Fact — official short description: “Controls information prefixed to each log line.”

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 ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value%m [%p]
%m [%p]

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.6 "" — empty string
PG10–19 Beta 3 %m [%p] — %m [%p]

How it works

log_line_prefix controls information prefixed to each log line. An empty string means no prefix. Percent escapes add session, user, database, process, application, and timing context; csvlog and jsonlog already carry structured fields separately.

log_line_prefix is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_line_prefix against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_line_prefix telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_line_prefix useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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

  • Editing log_line_prefix without reloading configuration and verifying the effective value and subsequent behavior.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Omitting process, session, database, user, or application identity needed to correlate multiline text logs.

Related parameters

application_name · cluster_name · update_process_title · log_timezone · log_hostname

References

11.22 - log_lock_failures

log_lock_failures is the PostgreSQL setting that controls whether PostgreSQL logs lock failures.
Note

Fact — official short description: “Logs lock failures.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 73bdcfab35ec — Rename log_lock_failure GUC to log_lock_failures for consistency.
Commit date 2025-06-03
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 off — off

How it works

log_lock_failures was introduced in PostgreSQL 18 to emit a detailed message when a supported lock acquisition fails. In PostgreSQL 18 the supported scope is specifically lock failure caused by SELECT … NOWAIT; it is not a general logger for every NOWAIT-like command or every lock error.

It is a SUPERUSER-context setting. A superuser or a role with the appropriate SET privilege can change it per session, so role/database defaults and connection-pool reset behavior determine which sessions produce records.

It complements log_lock_waits: log_lock_waits reports waits that cross deadlock_timeout, whereas SELECT … NOWAIT fails immediately and can be reported here. The detailed message can expose relation, lock, and statement context and must follow the normal log access policy.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable it for sessions where SELECT … NOWAIT failure explains latency or retry behavior, and correlate records with application retries and lock holders. Do not expect coverage of unrelated lock errors.
OLAP Analytical readers using SELECT … NOWAIT can use it during contention investigations; leave it off if those commands are absent because it supplies no broader wait telemetry.
Small nodes The normal volume is low, but verify log access and retention before enabling. Pair it with log_lock_waits and deadlock diagnostics rather than treating it as a replacement.

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 on different 'on'
OLAP Unmodified — —
CRIT on different 'on'
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 = on (dcs); OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 = on (dcs); TINY: PG18–19 Beta 3 unmodified. Advice, pending human review — Editorial inference: the override appears intended to retain detailed evidence for SELECT … NOWAIT failures in the profiles where immediate lock-failure retries or audit diagnostics are expected to be most valuable; PostgreSQL 18 does not provide broader lock-failure coverage through this GUC.

Common pitfalls

  • Assuming PostgreSQL 18 logs every lock acquisition failure; currently only SELECT … NOWAIT is supported.
  • Using it instead of log_lock_waits even though immediate failure and a wait exceeding deadlock_timeout are different events.
  • Enabling it in one pooled session and assuming other sessions inherited the value.
  • Retaining detailed lock and statement context without appropriate log access, redaction, and retention controls.

Related parameters

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_temp_files · log_replication_commands

References

11.23 - log_lock_waits

log_lock_waits is the PostgreSQL setting that controls whether PostgreSQL logs long lock waits.
Note

Fact — official short description: “Logs long lock waits.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–18 off — off
PG19 Beta 3 on — on

How it works

log_lock_waits logs long lock waits. A wait is logged after deadlock_timeout, so the diagnostic threshold and deadlock detector cadence are coupled.

log_lock_waits is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_lock_waits against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_lock_waits telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_lock_waits useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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 on same as boot 'on'
OLAP on same as boot 'on'
CRIT on same as boot 'on'
TINY on same as boot 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = on (dcs); OLAP: PG9.0–19 Beta 3 = on (dcs); CRIT: PG9.0–19 Beta 3 = on (dcs); TINY: PG9.0–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference: All profiles retain long-lock-wait evidence because it is high-value for diagnosing latency and blockers at modest normal volume.

Common pitfalls

  • Changing log_lock_waits in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing deadlock_timeout without realizing it also changes when lock-wait diagnostics appear.

Related parameters

log_checkpoints · log_autovacuum_min_duration · log_lock_failures · log_temp_files · log_replication_commands

References

11.24 - log_min_duration_sample

log_min_duration_sample is the PostgreSQL setting that defines the minimum execution time above which a sample of statements will be logged. Sampling is determined by “log_statement_sample_rate”.
Note

Fact — official short description: “Sets the minimum execution time above which a sample of statements will be logged. Sampling is determined by “log_statement_sample_rate”.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Valuems
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / When to Log
Upstream classification
Latest boot value Value-1
-1 ms

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 6e3e6cc0e884 — Allow sampling of statements depending on duration
Commit date 2019-11-04
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 -1 ms -1 ms

How it works

log_min_duration_sample admits completed statements at or above its duration threshold into stochastic logging controlled by log_statement_sample_rate. -1 disables this path, zero admits every completed statement, and the sample rate then decides which admitted statements are emitted.

log_min_duration_statement has higher priority. A statement that reaches its threshold is always logged and is not sampled, even if it also exceeds log_min_duration_sample. Under the extended query protocol, Parse, Bind, and Execute durations are logged separately.

It is a SUPERUSER-context session setting. Sampled entries have the same statement-text, Bind-value, correlation, overhead, and security considerations as log_min_duration_statement, so log_line_prefix and log_parameter_max_length still determine usefulness and exposure.

Tuning advice

Tip

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

Workload Guidance
OLTP Set an always-log threshold first with log_min_duration_statement, then use a lower sample threshold and measured rate for the high-volume middle band. Verify actual sample counts and sensitive-data handling under peak OLTP traffic.
OLAP Long analytical queries often exceed the always-log threshold, so sampling may provide no reduction for them. Choose thresholds from the duration distribution rather than copying OLTP values.
Small nodes Use a conservative rate and bounded statement text. A small node should avoid zero with rate 1 unless it intentionally wants every statement-duration entry.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Expecting sampling to affect statements already captured by the higher-priority log_min_duration_statement threshold.
  • Forgetting that Parse, Bind, and Execute are timed and logged separately with the extended query protocol.
  • Setting zero with log_statement_sample_rate = 1 and unintentionally logging every completed statement duration.
  • Sampling SQL and Bind values without correlation identifiers, redaction, access control, and a measured volume budget.

Related parameters

log_min_messages · log_min_error_statement · log_min_duration_statement · log_statement_sample_rate · log_transaction_sample_rate

References

11.25 - log_min_duration_statement

Logs every completed statement whose duration reaches a threshold. It is a deterministic slow-query capture control, distinct from sampling and from statement cancellation.
Note

Fact — official short description: “Sets the minimum execution time above which all statements will be logged.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Valuems
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / When to Log
Upstream classification
Latest boot value Value-1
-1 ms

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 -1 ms -1 ms

How it works

The value is a duration in milliseconds when no unit is written. A value of -1 disables duration-based statement logging, zero logs every completed statement, and a positive value logs statements at or above the threshold.

Statements selected by this setting are always logged rather than sampled, so it takes priority over log_min_duration_sample. Under the extended query protocol, Parse, Bind, and Execute durations can appear separately.

This parameter observes and records completed work; it does not stop slow statements. statement_timeout is the separate execution-cancellation control.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose a threshold from the application’s latency objective and expected log volume. At high QPS, combine a meaningful hard threshold with sampled logging for the faster population.
OLAP Use a higher threshold so normal long analytical work does not flood logs. Pair logs with query identifiers and workload labels so repeated reports remain actionable.
Small nodes A low threshold can be useful while tuning, but watch disk use and rotation. Raise it or switch to sampling when logging becomes a measurable part of the workload.

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 100 different 100
OLAP 1000 different 1000
CRIT 100 different 100
TINY 100 different 100
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 100 (dcs); OLAP: PG9.0–19 Beta 3 = 1000 (dcs); CRIT: PG9.0–19 Beta 3 = 100 (dcs); TINY: PG9.0–19 Beta 3 = 100 (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: Pigsty opts into deterministic slow-query evidence, while OLAP uses a looser threshold to accommodate naturally longer analytical statements.

Common pitfalls

  • Low thresholds on high-throughput systems can create extreme log volume and I/O.
  • SQL text can contain sensitive literals and must be protected like application data.
  • It logs slow statements but does not cancel them; use statement_timeout for that goal.
  • Extended-protocol phases may be logged separately and need session or PID correlation.
  • Interactions with log_statement, sampling, and log_line_prefix can confuse duplicate or fragmented entries.

Related parameters

log_min_duration_sample · log_statement_sample_rate · log_statement · log_duration · log_line_prefix · statement_timeout

References

11.26 - log_min_error_statement

log_min_error_statement is the PostgreSQL setting that causes all statements generating error at or above this level to be logged.
Note

Fact — official short description: “Causes all statements generating error at or above this level to be logged.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuedebug5, debug4, debug3, debug2, debug1, info, notice, warning, error, log, fatal, panic
— for non-enum types
Category ValueReporting and Logging / When to Log
Upstream classification
Latest boot value Valueerror
error

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 error — error

How it works

log_min_error_statement causes all statements generating error at or above this level to be logged. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. It governs whether the SQL statement associated with an error-level message is included; log_min_messages separately decides whether the message itself is emitted.

log_min_error_statement is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_min_error_statement against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_min_error_statement telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_min_error_statement useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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

  • Changing log_min_error_statement in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_min_error_statement globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_min_messages · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate · log_transaction_sample_rate

References

11.27 - log_min_messages

log_min_messages is the PostgreSQL setting that defines the message levels that are logged.
Note

Fact — official short description: “Sets the message levels that are logged.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / When to Log
Upstream classification
Latest boot value Valuewarning
warning

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 warning — warning

How it works

log_min_messages sets the message levels that are logged. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. The server-log severity ordering has special placement for LOG and differs from client_min_messages, so a threshold name cannot be copied blindly between them.

log_min_messages is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_min_messages against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_min_messages telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_min_messages useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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

  • Changing log_min_messages in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_min_messages globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate · log_transaction_sample_rate

References

11.28 - log_parameter_max_length

log_parameter_max_length is the PostgreSQL setting that defines the maximum length in bytes of data logged for bind parameter values when logging statements.
Note

Fact — official short description: “Sets the maximum length in bytes of data logged for bind parameter values when logging statements.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit ValueB
Raw unit
Range Value-1 – 1073741823
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value-1
-1 B

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 0b34e7d307e6 — Improve user control over truncation of logged bind-parameter values.
Commit date 2020-04-02
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 -1 B -1 B

How it works

log_parameter_max_length controls Bind values attached to non-error statement-logging messages. Zero suppresses them, -1 allows full values, and a positive byte count truncates each textual value to that limit.

It applies to messages produced by log_statement, log_min_duration_statement, and related statement-logging settings. Any nonzero value adds work; parameters sent in binary form must be converted to text before they can be logged.

It is a SUPERUSER-context session setting and is independent of log_parameter_max_length_on_error. The normal and error paths therefore need separate confidentiality and overhead decisions.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep zero when Bind values may contain credentials or regulated data. If diagnostics require values, choose the smallest useful positive limit and measure binary-bind conversion cost under peak OLTP traffic.
OLAP Analytical parameters can be large arrays or predicates; use a bounded positive limit for a short diagnostic window rather than -1, and verify logs remain useful after truncation.
Small nodes Use zero by default. Full values consume disk and conversion CPU that a small node cannot absorb safely, and truncation is not redaction.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Using -1 and exposing complete credentials, tokens, or large payloads in normal statement logs.
  • Treating truncation as redaction; a sensitive prefix can remain fully visible.
  • Ignoring text-conversion overhead for binary Bind parameters when the value is nonzero.
  • Assuming this setting also limits error-path parameters controlled by log_parameter_max_length_on_error.

Related parameters

log_statement · log_duration · log_connections · log_disconnections · log_parameter_max_length_on_error

References

11.29 - log_parameter_max_length_on_error

log_parameter_max_length_on_error is the PostgreSQL setting that defines the maximum length in bytes of data logged for bind parameter values when logging statements, on error.
Note

Fact — official short description: “Sets the maximum length in bytes of data logged for bind parameter values when logging statements, on error.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValueB
Raw unit
Range Value-1 – 1073741823
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value0
0 B

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 0b34e7d307e6 — Improve user control over truncation of logged bind-parameter values.
Commit date 2020-04-02
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 0 B 0 B

How it works

log_parameter_max_length_on_error controls Bind values included in error reports. Zero, the default, suppresses them; -1 permits complete values; a positive byte count truncates each textual value to that limit.

For any nonzero value PostgreSQL must preserve textual parameter representations at the start of every statement in case an error occurs. That overhead is paid even by successful statements, and binary parameters require conversion rather than a simple text copy.

It is a USER-context session setting and is independent of log_parameter_max_length, so an application can accidentally expose values on errors even when normal statement logging suppresses them. Error detail, access, redaction, and retention must be reviewed together.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep zero unless error diagnosis specifically requires bind values. Any nonzero value adds conversion and retained-memory work to every statement, so prefer a bounded positive value scoped by role, database, or session.
OLAP Use a bounded positive limit only during controlled diagnosis of parameterized analytical jobs. Budget textual conversion and retained parameter memory for successful statements as well as failures.
Small nodes Prefer zero. If error-path binds are essential, choose a short limit, scope it narrowly, and verify both memory overhead and secret-redaction policy before enabling it.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Assuming the conversion and memory cost is paid only when a statement fails; every statement pays it when the value is nonzero.
  • Using -1 and exposing complete secrets or large payloads in error reports.
  • Ignoring textual conversion cost for binary Bind values and retained representations for successful statements.
  • Assuming log_parameter_max_length also protects error paths; the two limits are independent.

Related parameters

log_statement · log_duration · log_connections · log_disconnections · log_parameter_max_length

References

11.30 - log_recovery_conflict_waits

log_recovery_conflict_waits is the PostgreSQL setting that controls whether PostgreSQL logs standby recovery conflict waits.
Note

Fact — official short description: “Logs standby recovery conflict waits.”

Identity

Type Valuebool
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 ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 0650ff23038b — Add GUC to log long wait times on recovery conflicts.
Commit date 2021-01-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 off — off

How it works

log_recovery_conflict_waits logs standby recovery conflict waits. On a standby, recovery conflict waits are reported after deadlock_timeout, exposing replay delays before cancellation is necessarily required.

log_recovery_conflict_waits is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_recovery_conflict_waits against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_recovery_conflict_waits telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_recovery_conflict_waits useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing log_recovery_conflict_waits without reloading configuration and verifying the effective value and subsequent behavior.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_recovery_conflict_waits globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

References

11.31 - log_replication_commands

log_replication_commands is the PostgreSQL setting that controls whether PostgreSQL logs each replication command.
Note

Fact — official short description: “Logs each replication command.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 4ad2a548050f — Add GUC to enable logging of replication commands.
Commit date 2014-09-13
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–19 Beta 3 off — off

How it works

log_replication_commands logs each replication command. It covers replication-protocol commands as well as SQL replication commands and can therefore expose replication topology and slot activity.

log_replication_commands is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_replication_commands against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_replication_commands telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_replication_commands useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.5–19 Beta 3 = on (dcs); OLAP: PG9.5–19 Beta 3 = on (dcs); CRIT: PG9.5–19 Beta 3 = on (dcs); TINY: PG9.5–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference: Replication command history supports diagnosing slots, senders, failover, and topology changes across managed clusters.

Common pitfalls

  • Changing log_replication_commands in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_replication_commands globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files

References

11.32 - log_rotation_age

log_rotation_age is the PostgreSQL setting that defines the amount of time to wait before forcing log file rotation.
Note

Fact — official short description: “Sets the amount of time to wait before forcing log file rotation.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuemin
Raw unit
Range Value0 – 35791394
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Value1440
1 d

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 1440 min 1 d

How it works

log_rotation_age sets the amount of time to wait before forcing log file rotation. 0 disables time-based creation of new log files. The collector opens a new file after the interval; zero disables this trigger but leaves size-based or external rotation possible.

log_rotation_age is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The active path is composed from log_destination, logging_collector or syslog/eventlog, file naming and permissions, rotation triggers, and external shipping or retention.

Tuning advice

Tip

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

Workload Guidance
OLTP Set log_rotation_age from the maximum time a file may remain open and the shipping/retention boundary. Confirm that the filename pattern creates a distinct or intentionally reusable name at that interval.
OLAP Long analytical bursts do not require a different clock by themselves; choose an interval that lets downstream systems close and ingest files predictably without producing impractically large objects.
Small nodes Prefer a simple daily or shorter interval that keeps failure blast radius bounded. Zero disables time rotation and is safe only when size-based or external rotation is authoritative and tested.

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 1d same as boot '1d'
OLAP 1d same as boot '1d'
CRIT 1d same as boot '1d'
TINY 1d same as boot '1d'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 1d (dcs); OLAP: PG9.0–19 Beta 3 = 1d (dcs); CRIT: PG9.0–19 Beta 3 = 1d (dcs); TINY: PG9.0–19 Beta 3 = 1d (dcs). Advice, pending human review — Editorial inference: Daily rotation matches the weekday filename cycle and creates predictable operational boundaries.

Common pitfalls

  • Editing log_rotation_age without reloading configuration and verifying the effective value and subsequent behavior.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Changing log_rotation_age globally without a rollback plan and a client or operational compatibility test.

Related parameters

logging_collector · log_destination · log_directory · log_filename · log_rotation_size

References

11.33 - log_rotation_size

log_rotation_size is the PostgreSQL setting that defines the maximum size a log file can reach before being rotated.
Note

Fact — official short description: “Sets the maximum size a log file can reach before being rotated.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit ValuekB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Value10240
10 MiB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 10240 kB 10 MiB

How it works

log_rotation_size sets the maximum size a log file can reach before being rotated. 0 disables size-based creation of new log files. The collector rotates when the current file reaches approximately this size; zero disables the size trigger but not time-based rotation.

log_rotation_size is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The active path is composed from log_destination, logging_collector or syslog/eventlog, file naming and permissions, rotation triggers, and external shipping or retention.

Tuning advice

Tip

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

Workload Guidance
OLTP Use a nonzero log_rotation_size when file size itself must be bounded, and coordinate it with a filename that cannot collide during multiple rotations in one time period. If set to zero, verify that time-based rotation and disk alerts provide the bound instead.
OLAP Analytical bursts can cross a size threshold repeatedly; test the resulting filename suffixes, shipping throughput, and maximum single-file size rather than choosing a larger number by habit.
Small nodes A modest size cap limits damage from a logging spike, but too-small files increase metadata and shipping overhead. Zero is acceptable only with a proven time-based cycle and free-space guardrail.

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 0 different '0'
OLAP 0 different '0'
CRIT 0 different '0'
TINY 0 different '0'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 0 (dcs); OLAP: PG9.0–19 Beta 3 = 0 (dcs); CRIT: PG9.0–19 Beta 3 = 0 (dcs); TINY: PG9.0–19 Beta 3 = 0 (dcs). Advice, pending human review — Editorial inference: Disabling size rotation appears intended to make daily time rotation the single file-cycle authority; disk safeguards still need independent verification.

Common pitfalls

  • Editing log_rotation_size without reloading configuration and verifying the effective value and subsequent behavior.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Setting zero without a working time-based or external rotation policy and allowing unbounded growth.

Related parameters

logging_collector · log_destination · log_directory · log_filename · log_rotation_age

References

11.34 - log_startup_progress_interval

log_startup_progress_interval is the PostgreSQL setting that defines the interval between progress updates for long-running startup operations.
Note

Fact — official short description: “Time between progress updates for long-running startup operations.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / When to Log
Upstream classification
Latest boot value Value10000
10 s

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit 9ce346eabf35 — Report progress of startup operations that take a long time.
Commit date 2021-10-25
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG15–19 Beta 3 10000 ms 10 s

How it works

log_startup_progress_interval defines the interval between progress updates for long-running startup operations. 0 disables progress updates. Startup processes emit periodic progress for operations such as WAL replay when they exceed the interval; zero disables these updates.

log_startup_progress_interval is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_startup_progress_interval against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_startup_progress_interval telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_startup_progress_interval useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing log_startup_progress_interval without reloading configuration and verifying the effective value and subsequent behavior.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_startup_progress_interval globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

References

11.35 - log_statement

log_statement is the PostgreSQL setting that defines the type of statements logged.
Note

Fact — official short description: “Sets the type of statements logged.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuenone, ddl, mod, all
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Valuenone
none

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 none — none

How it works

log_statement selects none, ddl, mod, or all. ddl logs data-definition commands; mod adds data-changing commands; all logs every statement that reaches the logging point. PREPARE, EXECUTE, and EXPLAIN ANALYZE follow the contained command’s class.

With the extended query protocol, logging occurs when Execute is received and includes Bind parameter values. Even all does not log a simple statement that fails basic parsing, nor an extended-protocol statement that fails before Execute during parse analysis or planning; log_min_error_statement is required for those error paths.

It is a SUPERUSER-context session setting. Statement text and Bind values can expose personal data, tokens, and even plaintext passwords, so selection, access, redaction, transport, and retention must be treated as a security control as well as an observability choice.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep none or ddl as the routine OLTP baseline and use duration thresholds or sampling for query performance. Before enabling mod/all, test volume and a concrete redaction/access policy for SQL text and Bind values.
OLAP Use a role- or session-scoped window for analytical troubleshooting rather than all cluster-wide. Long generated SQL and large Bind values can dominate logs and expose source data.
Small nodes Prefer ddl or targeted thresholds; all can overwhelm disk and reveal secrets even on a quiet node. Keep log_min_error_statement configured for syntax/parse failures that log_statement misses.

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 ddl different ddl
OLAP ddl different ddl
CRIT ddl different ddl
TINY ddl different ddl
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = ddl (dcs); OLAP: PG9.0–19 Beta 3 = ddl (dcs); CRIT: PG9.0–19 Beta 3 = ddl (dcs); TINY: PG9.0–19 Beta 3 = ddl (dcs). Advice, pending human review — Editorial inference: Logging DDL gives every profile a schema-change trail without paying the confidentiality and volume cost of all statements.

Common pitfalls

  • Assuming all captures syntax errors or extended-protocol failures before Execute; use log_min_error_statement for those paths.
  • Forgetting that extended-protocol Execute logging includes Bind parameter values.
  • Logging SQL that contains plaintext passwords, bearer tokens, personal data, or application secrets without redaction and strict access controls.
  • Enabling mod or all cluster-wide without bounding log throughput, disk, shipping, and retention.

Related parameters

log_duration · log_connections · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

References

11.36 - log_statement_sample_rate

log_statement_sample_rate is the PostgreSQL setting that defines the fraction of statements exceeding “log_min_duration_sample” to be logged.
Note

Fact — official short description: “Fraction of statements exceeding “log_min_duration_sample” to be logged.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value0 – 1
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / When to Log
Upstream classification
Latest boot value Value1
1

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 88bdbd3f7460 — Add log_statement_sample_rate parameter
Commit date 2018-11-29
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 1 — 1

How it works

log_statement_sample_rate sets the fraction of statements exceeding “log_min_duration_sample” to be logged. Use a value between 0.0 (never log) and 1.0 (always log). This probability is evaluated only for statements admitted by log_min_duration_sample; it does not sample log_statement or log_min_duration_statement output.

log_statement_sample_rate is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_statement_sample_rate against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_statement_sample_rate telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_statement_sample_rate useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing log_statement_sample_rate in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Expecting it to sample all statement logging even though it only gates log_min_duration_sample.

Related parameters

log_min_messages · log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_transaction_sample_rate

References

11.37 - log_temp_files

log_temp_files is the PostgreSQL setting that controls whether PostgreSQL logs the use of temporary files larger than this number of kilobytes.
Note

Fact — official short description: “Log the use of temporary files larger than this number of kilobytes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit ValuekB
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / What to Log
Upstream classification
Latest boot value Value-1
-1 kB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 -1 kB -1 kB

How it works

log_temp_files logs the use of temporary files larger than this number of kilobytes. -1 disables logging temporary files. 0 means log all temporary files. A temporary file is reported when it is deleted, with its name and size; -1 disables records and zero includes every file.

log_temp_files is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_temp_files against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_temp_files telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_temp_files useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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 1024 different 1024
OLAP 1024 different 1024
CRIT 1024 different 1024
TINY 1024 different 1024
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 1024 (dcs); OLAP: PG9.0–19 Beta 3 = 1024 (dcs); CRIT: PG9.0–19 Beta 3 = 1024 (dcs); TINY: PG9.0–19 Beta 3 = 1024 (dcs). Advice, pending human review — Editorial inference: A 1 MiB threshold surfaces meaningful executor spills while filtering very small temporary files.

Common pitfalls

  • Changing log_temp_files in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_temp_files globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_replication_commands

References

11.38 - log_timezone

log_timezone is the PostgreSQL setting that defines the time zone to use in log messages.
Note

Fact — official short description: “Sets the time zone to use in log messages.”

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 ValueReporting and Logging / What to Log
Upstream classification
Latest boot value ValueGMT
GMT

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 UNKNOWN — UNKNOWN
PG9.1 — — not set
PG9.2–19 Beta 3 GMT — GMT

How it works

log_timezone sets the time zone to use in log messages. It affects timestamps rendered by the logging system, including filename expansion context, but does not change session TimeZone or stored timestamps.

log_timezone is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Use one cluster-wide timezone, normally UTC, so every session’s server-log timestamps correlate across hosts, replicas, failovers, and centralized ingestion. Test parsers and log_filename expansion before changing it.
OLAP Analytical workload type does not justify a separate log timezone. Keep UTC or the fleet standard and convert to local civil time only in reporting tools, especially across DST transitions.
Small nodes Keep UTC unless an existing operational pipeline requires another stable zone. Changing log_timezone does not reduce log volume; it changes timestamp interpretation and potentially rotated filenames.

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 UTC different 'UTC'
OLAP UTC different 'UTC'
CRIT UTC different 'UTC'
TINY UTC different 'UTC'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = UTC (dcs); OLAP: PG9.0–19 Beta 3 = UTC (dcs); CRIT: PG9.0–19 Beta 3 = UTC (dcs); TINY: PG9.0–19 Beta 3 = UTC (dcs). Advice, pending human review — Editorial inference: UTC makes timestamps comparable across hosts, regions, failovers, and centralized log systems.

Common pitfalls

  • Editing log_timezone without reloading configuration and verifying the effective value and subsequent behavior.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Changing log_timezone globally without a rollback plan and a client or operational compatibility test.

Related parameters

DateStyle · IntervalStyle · TimeZone · lc_time · timezone_abbreviations

References

11.39 - log_transaction_sample_rate

log_transaction_sample_rate is the PostgreSQL setting that defines the fraction of transactions from which to log all statements.
Note

Fact — official short description: “Sets the fraction of transactions from which to log all statements.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value0 – 1
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / When to Log
Upstream classification
Latest boot value Value0
0

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 799e220346f1 — Log all statements from a sample of transactions
Commit date 2019-04-03
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 0 — 0

How it works

log_transaction_sample_rate sets the fraction of transactions from which to log all statements. Use a value between 0.0 (never log) and 1.0 (log all statements for all transactions). A sampled transaction logs every statement, preserving transaction context but potentially creating bursts from long or chatty transactions.

log_transaction_sample_rate is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

It changes emitted diagnostic data rather than query semantics, but volume, sensitive content, log_line_prefix, destinations, collector throughput, and retention determine operational cost and usefulness.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune log_transaction_sample_rate against an explicit observability question and a measured log-volume budget. Prefer selective thresholds, sampling, or role-level overrides over indiscriminate capture.
OLAP Analytical jobs can justify richer log_transaction_sample_rate telemetry, but account for long statements, large bind values, and bursty completion patterns in the log pipeline.
Small nodes Keep log_transaction_sample_rate useful but bounded: verify disk, collector, retention, and redaction capacity before increasing detail or frequency.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing log_transaction_sample_rate in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Enabling richer logging without budgeting collector throughput, storage, retention, and downstream query cost.
  • Writing SQL text, bind values, identities, or host data without a redaction and access-control policy.
  • Underestimating bursts when one sampled, chatty transaction causes every statement to be logged.

Related parameters

log_min_messages · log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate

References

11.40 - log_truncate_on_rotation

log_truncate_on_rotation is the PostgreSQL setting that controls whether PostgreSQL truncates existing log files of same name during log rotation.
Note

Fact — official short description: “Truncate existing log files of same name during log rotation.”

Identity

Type Valuebool
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 ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_truncate_on_rotation truncates existing log files of same name during log rotation. Truncation occurs when time-based rotation reuses an existing filename; size rotation and other causes do not apply the same overwrite rule.

log_truncate_on_rotation is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

The active path is composed from log_destination, logging_collector or syslog/eventlog, file naming and permissions, rotation triggers, and external shipping or retention.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable log_truncate_on_rotation only when time-based rotation intentionally reuses a filename and the previous file has been durably shipped or is meant to be replaced. Leave it off for unique timestamped names.
OLAP For analytical logs, confirm that long-running ingestion has finished before a repeating name is truncated; use unique names when completion cannot be guaranteed.
Small nodes A short repeating cycle can bound disk use, but truncation is not retention management. Monitor shipping and backups so the next time rotation cannot erase the only copy.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = on (dcs); OLAP: PG9.0–19 Beta 3 = on (dcs); CRIT: PG9.0–19 Beta 3 = on (dcs); TINY: PG9.0–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference: Truncation closes the weekday filename cycle so a reused daily name replaces the prior week’s file instead of appending forever.

Common pitfalls

  • Editing log_truncate_on_rotation without reloading configuration and verifying the effective value and subsequent behavior.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Expecting truncation on every rotation path; it is tied to time-based reuse of an existing filename.

Related parameters

logging_collector · log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

References

11.41 - logging_collector

logging_collector is the PostgreSQL setting that controls whether PostgreSQL starts a subprocess to capture stderr, csvlog and/or jsonlog into log files.
Note

Fact — official short description: “Start a subprocess to capture stderr, csvlog and/or jsonlog into log files.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

logging_collector starts a subprocess to capture stderr, csvlog and/or jsonlog into log files. The collector drains server stderr through a pipe and writes configured file formats; it is designed not to lose messages, so extreme backpressure can block emitters.

logging_collector is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

The active path is composed from log_destination, logging_collector or syslog/eventlog, file naming and permissions, rotation triggers, and external shipping or retention.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable logging_collector when csvlog/jsonlog or collector-managed stderr files are required, then load-test pipe throughput, rotation, disk-full behavior, shipping, and restart. It is a POSTMASTER setting and needs a controlled restart.
OLAP Analytical workloads can emit large bursts at query completion; size collector and destination I/O for that burst and verify database processes do not stall behind collector backpressure.
Small nodes Use one required format and bounded retention. A small node still needs disk alerts because the collector is designed not to lose messages and can propagate backpressure when its destination is slow or full.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = on (dcs); OLAP: PG9.0–19 Beta 3 = on (dcs); CRIT: PG9.0–19 Beta 3 = on (dcs); TINY: PG9.0–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference: The collector is required for the configured csvlog file pipeline and gives all profiles managed local log files.

Common pitfalls

  • Expecting a reload or SET to activate logging_collector, although it requires a controlled server restart.
  • Combining incompatible destination, collector, filename, and rotation assumptions and then losing or overwriting logs.
  • Failing to monitor a full or unwritable log target, which can block logging or database activity depending on the path.
  • Enabling file-oriented destinations without the collector, or starting the collector without a disk and retention plan.

Related parameters

log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

References

11.42 - silent_mode

silent_mode — Runs the server silently. Observed in PG9.0–9.1; its last measured boot default is off in PG9.1, with postmaster context. It was removed in PG9.2.
Note

Fact — official short description: “Runs the server silently.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.1
Removed in PG9.2
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.1 off — off

How it works

PostgreSQL describes silent_mode as follows: “Runs the server silently.” The value is fixed when the server starts, so changing it requires a controlled restart. The atlas measures it in PG9.0–9.1; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

Silent mode was an early background-server convenience that redirected or suppressed terminal-facing output. It was removed in PostgreSQL 9.2; service managers and PostgreSQL’s logging_collector, log_destination, and log_directory settings now provide explicit process and log ownership.

Read it together with logging_collector, log_destination, log_directory, log_filename. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.1; 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: PG9.0–9.1 unmodified; OLAP: PG9.0–9.1 unmodified; CRIT: PG9.0–9.1 unmodified; TINY: PG9.0–9.1 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for silent_mode 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.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

logging_collector · log_destination · log_directory · log_filename

References

11.43 - syslog_facility

syslog_facility is the PostgreSQL setting that defines the syslog “facility” to be used when syslog enabled.
Note

Fact — official short description: “Sets the syslog “facility” to be used when syslog enabled.”

Identity

Type Valueenum
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 Valuelocal0, local1, local2, local3, local4, local5, local6, local7
— for non-enum types
Category ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valuelocal0
local0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 local0 — local0

How it works

syslog_facility sets the syslog “facility” to be used when syslog enabled. It selects the syslog routing facility only when syslog is listed in log_destination; the system logger maps that facility to storage or forwarding rules.

syslog_facility is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It is active only when syslog appears in log_destination, after which the facility, ident, sequence, splitting, host daemon, and remote receiver jointly define record delivery.

Tuning advice

Tip

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

Workload Guidance
OLTP Set syslog_facility to match the receiving syslog daemon’s routing, framing, deduplication, and message-size contract; validate failover and backpressure with the real collector.
OLAP Test syslog_facility under bursty analytical messages and multiline plans so splitting or receiver limits do not destroy record boundaries.
Small nodes Prefer the host’s established syslog convention for syslog_facility; avoid parallel local-file retention unless it has an explicit purpose and size limit.

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

  • Editing syslog_facility without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing PostgreSQL framing or identifiers without testing the host daemon and remote receiver as one pipeline.
  • Assuming syslog preserves unlimited message size, multiline boundaries, ordering, or repeated records by default.
  • Changing syslog_facility globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_destination · syslog_ident · syslog_sequence_numbers · syslog_split_messages · logging_collector

References

11.44 - syslog_ident

syslog_ident is the PostgreSQL setting that defines the program name used to identify PostgreSQL messages in syslog.
Note

Fact — official short description: “Sets the program name used to identify PostgreSQL messages in syslog.”

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 ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valuepostgres
postgres

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 postgres — postgres

How it works

syslog_ident sets the program name used to identify PostgreSQL messages in syslog. The ident labels PostgreSQL records in syslog and can distinguish clusters when combined with facility or host metadata.

syslog_ident is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It is active only when syslog appears in log_destination, after which the facility, ident, sequence, splitting, host daemon, and remote receiver jointly define record delivery.

Tuning advice

Tip

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

Workload Guidance
OLTP Set syslog_ident to match the receiving syslog daemon’s routing, framing, deduplication, and message-size contract; validate failover and backpressure with the real collector.
OLAP Test syslog_ident under bursty analytical messages and multiline plans so splitting or receiver limits do not destroy record boundaries.
Small nodes Prefer the host’s established syslog convention for syslog_ident; avoid parallel local-file retention unless it has an explicit purpose and size limit.

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

  • Editing syslog_ident without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing PostgreSQL framing or identifiers without testing the host daemon and remote receiver as one pipeline.
  • Assuming syslog preserves unlimited message size, multiline boundaries, ordering, or repeated records by default.
  • Changing syslog_ident globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_destination · syslog_facility · syslog_sequence_numbers · syslog_split_messages · logging_collector

References

11.45 - syslog_sequence_numbers

syslog_sequence_numbers is the PostgreSQL setting that adds sequence number to syslog messages to avoid duplicate suppression.
Note

Fact — official short description: “Add sequence number to syslog messages to avoid duplicate suppression.”

Identity

Type Valuebool
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 ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit f4c454e9ba52 — Add syslog_sequence_numbers parameter
Commit date 2016-02-26
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 on — on

How it works

syslog_sequence_numbers adds sequence number to syslog messages to avoid duplicate suppression. A monotonically increasing sequence prefix prevents some syslog implementations from collapsing repeated messages and helps detect gaps.

syslog_sequence_numbers is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It is active only when syslog appears in log_destination, after which the facility, ident, sequence, splitting, host daemon, and remote receiver jointly define record delivery.

Tuning advice

Tip

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

Workload Guidance
OLTP Set syslog_sequence_numbers to match the receiving syslog daemon’s routing, framing, deduplication, and message-size contract; validate failover and backpressure with the real collector.
OLAP Test syslog_sequence_numbers under bursty analytical messages and multiline plans so splitting or receiver limits do not destroy record boundaries.
Small nodes Prefer the host’s established syslog convention for syslog_sequence_numbers; avoid parallel local-file retention unless it has an explicit purpose and size limit.

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: PG9.6–19 Beta 3 unmodified; OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 unmodified; TINY: PG9.6–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing syslog_sequence_numbers without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing PostgreSQL framing or identifiers without testing the host daemon and remote receiver as one pipeline.
  • Assuming syslog preserves unlimited message size, multiline boundaries, ordering, or repeated records by default.
  • Changing syslog_sequence_numbers globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_destination · syslog_facility · syslog_ident · syslog_split_messages · logging_collector

References

11.46 - syslog_split_messages

syslog_split_messages is the PostgreSQL setting that splits messages sent to syslog by lines and to fit into 1024 bytes.
Note

Fact — official short description: “Split messages sent to syslog by lines and to fit into 1024 bytes.”

Identity

Type Valuebool
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 ValueReporting and Logging / Where to Log
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit fc201dfd9505 — Add syslog_split_messages parameter
Commit date 2016-03-15
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 on — on

How it works

syslog_split_messages splits messages sent to syslog by lines and to fit into 1024 bytes. When enabled, PostgreSQL splits at line boundaries and the traditional 1024-byte limit; disabling it relies on the receiver to handle multiline or long payloads.

syslog_split_messages is a SIGHUP-context setting: a configuration reload activates the new server value without a restart; subsequent operations that consult it use the refreshed value.

It is active only when syslog appears in log_destination, after which the facility, ident, sequence, splitting, host daemon, and remote receiver jointly define record delivery.

Tuning advice

Tip

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

Workload Guidance
OLTP Set syslog_split_messages to match the receiving syslog daemon’s routing, framing, deduplication, and message-size contract; validate failover and backpressure with the real collector.
OLAP Test syslog_split_messages under bursty analytical messages and multiline plans so splitting or receiver limits do not destroy record boundaries.
Small nodes Prefer the host’s established syslog convention for syslog_split_messages; avoid parallel local-file retention unless it has an explicit purpose and size limit.

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: PG9.6–19 Beta 3 unmodified; OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 unmodified; TINY: PG9.6–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Editing syslog_split_messages without reloading configuration and verifying the effective value and subsequent behavior.
  • Changing PostgreSQL framing or identifiers without testing the host daemon and remote receiver as one pipeline.
  • Assuming syslog preserves unlimited message size, multiline boundaries, ordering, or repeated records by default.
  • Changing syslog_split_messages globally without a rollback plan and a client or operational compatibility test.

Related parameters

log_destination · syslog_facility · syslog_ident · syslog_sequence_numbers · logging_collector

References

11.47 - update_process_title

update_process_title is the PostgreSQL setting that controls whether PostgreSQL updates the process title to show the active SQL command.
Note

Fact — official short description: “Updates the process title to show the active SQL command.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueReporting and Logging / Process Title
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

update_process_title updates the process title to show the active SQL command. Enables updating of the process title every time a new SQL command is received by the server. When supported by the operating system, PostgreSQL rewrites each backend’s process title as commands change, making current activity visible to tools such as ps.

update_process_title is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Process titles complement application_name, cluster_name, pg_stat_activity, and log_line_prefix, allowing operating-system observations to be joined with database activity.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep update_process_title enabled or populated for operator clarity unless profiling proves material overhead. Use stable, non-secret labels that match monitoring inventory.
OLAP Preserve update_process_title so long jobs can be attributed from operating-system and PostgreSQL views; use application_name for finer job identity.
Small nodes Do not tune update_process_title for capacity. Its observability value normally outweighs negligible overhead, but avoid high-cardinality or sensitive labels.

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

  • Changing update_process_title in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.
  • Putting secrets or unbounded high-cardinality data into operator-visible process labels.
  • Using inconsistent cluster, application, and process labels that cannot be joined across monitoring systems.
  • Changing update_process_title globally without a rollback plan and a client or operational compatibility test.

Related parameters

application_name · cluster_name · log_line_prefix · log_timezone · log_hostname

References

12 - Resource Usage

Complete dossiers for 51 core PostgreSQL settings in Resource Usage.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

12.1 - autovacuum_work_mem

The memory ceiling for each autovacuum worker, with -1 meaning that the worker inherits maintenance_work_mem.
Note

Fact — official short description: “Sets the maximum memory to be used by each autovacuum worker process.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit ValuekB
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value-1
-1 kB

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit 8693559cacf1 — New autovacuum_work_mem parameter
Commit date 2013-12-12
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–19 Beta 3 -1 kB -1 kB

How it works

autovacuum_work_mem applies separately to each autovacuum worker process. The default sentinel -1 means to use maintenance_work_mem rather than negative memory.

The setting affects autovacuum workers only; it does not change manually issued VACUUM. It is a SIGHUP-context parameter, so it is configured at server level rather than as a per-session tuning knob.

Because multiple workers can run concurrently, the aggregate potential allocation is the per-worker value multiplied by active autovacuum workers. Memory is only one part of vacuum behavior; I/O throttling, worker count, thresholds, and table activity also matter.

Tuning advice

Tip

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

Workload Guidance
OLTP When maintenance_work_mem is large, set an explicit lower autovacuum ceiling unless the concurrent-worker budget clearly fits. Watch vacuum duration, dead-tuple backlog, and latency before increasing it.
OLAP Large relations may justify more memory per worker, but schedule and worker concurrency can dominate. Coordinate the value with autovacuum_max_workers and the maintenance window.
Small nodes Keep -1 only when maintenance_work_mem is itself conservative; otherwise set a smaller explicit value to prevent several workers from exhausting the host.

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: PG9.4–19 Beta 3 unmodified; OLAP: PG9.4–19 Beta 3 unmodified; CRIT: PG9.4–19 Beta 3 unmodified; TINY: PG9.4–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Reading -1 as a literal negative kilobyte value instead of an inheritance sentinel.
  • Assuming the setting controls manual VACUUM.
  • Budgeting one worker while several autovacuum workers can run at once.
  • Increasing memory to address a vacuum problem actually caused by I/O throttling, thresholds, locks, or insufficient worker capacity.

Related parameters

maintenance_work_mem · autovacuum_max_workers · autovacuum_worker_slots · vacuum_buffer_usage_limit · autovacuum_vacuum_cost_delay

References

12.2 - backend_flush_after

backend_flush_after — Number of pages after which previously performed writes are flushed to disk. Observed in PG9.6–19 Beta 3; its last measured boot default is 0 B (0 × 8kB) in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Number of pages after which previously performed writes are flushed to disk.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value8kB
Raw unit
Range Value0 – 256
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value0
0 B (0 × 8kB)

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit 428b1d6b29ca — Allow to trigger kernel writeback after a configurable number of writes.
Commit date 2016-02-19
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 0 8kB 0 B (0 × 8kB)

How it works

After one backend has written more than backend_flush_after bytes, PostgreSQL asks the operating system to begin writing those dirty page-cache pages toward storage. Zero disables these writeback hints.

This is not fsync and does not make a transaction durable earlier. Its aim is to limit large dirty-page bursts and later stalls; support and effect depend on the operating system.

The threshold applies independently to each backend, so concurrent bulk writers can each generate writeback. It complements bgwriter_flush_after and checkpoint_flush_after, which cover different writer processes. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Change backend_flush_after only after identifying the corresponding resource bottleneck under concurrency. Budget total memory, I/O, disk, or kernel capacity rather than optimizing one process in isolation.
OLAP Benchmark backend_flush_after with representative bulk and scan phases. Include sustained throughput, spill/writeback, and interference with other sessions, not only one operation’s elapsed time.
Small nodes Keep backend_flush_after conservative on a small host and prefer the upstream default when evidence is weak. A setting copied from a large server can consume a disproportionate share of resources.

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: PG9.6–19 Beta 3 unmodified; OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 unmodified; TINY: PG9.6–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing backend_flush_after without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

bgwriter_flush_after · checkpoint_flush_after · bgwriter_delay · shared_buffers · track_io_timing

References

12.3 - bgwriter_delay

bgwriter_delay — Background writer sleep time between rounds. Observed in PG9.0–19 Beta 3; its last measured boot default is 200 ms in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Background writer sleep time between rounds.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value10 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Background Writer
Upstream classification
Latest boot value Value200
200 ms

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 200 ms 200 ms

How it works

The background writer performs a round, writes selected dirty shared buffers, then sleeps for bgwriter_delay. When no dirty buffers are found it can enter a longer sleep regardless of this value.

A shorter interval reacts sooner to buffer demand but wakes the process more often. Effective timer granularity can be about 10 ms on some systems, so smaller or non-multiple values may round up in practice.

The number of pages considered per round is derived from recent buffer allocation demand, bgwriter_lru_multiplier, and bgwriter_lru_maxpages; checkpoints are handled separately. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune bgwriter_delay only with bgwriter and checkpoint metrics. The goal is fewer backend writes and smoother latency without excessive repeated writes; change one dimension at a time.
OLAP Bulk writes can reach bgwriter_delay limits continuously. Measure total bytes written, checkpoints, and storage queueing, not just foreground query latency.
Small nodes A small host usually needs conservative write smoothing. Aggressive bgwriter_delay can consume I/O needed by foreground work, so retain the default unless backend writes are a measured problem.

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 10ms different 10ms
OLAP 10ms different 10ms
CRIT 10ms different 10ms
TINY 10ms different 10ms
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 10ms (dcs); OLAP: PG9.0–19 Beta 3 = 10ms (dcs); CRIT: PG9.0–19 Beta 3 = 10ms (dcs); TINY: PG9.0–19 Beta 3 = 10ms (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The 10ms interval is intended to make the background writer inspect dirty-buffer demand much more frequently than PostgreSQL’s boot default.

Common pitfalls

  • Changing bgwriter_delay without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

bgwriter_lru_maxpages · bgwriter_lru_multiplier · bgwriter_flush_after · shared_buffers · checkpoint_completion_target

References

12.4 - bgwriter_flush_after

bgwriter_flush_after — Number of pages after which previously performed writes are flushed to disk. Observed in PG9.6–19 Beta 3; its last measured boot default is 512 KiB (64 × 8kB) in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Number of pages after which previously performed writes are flushed to disk.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value8kB
Raw unit
Range Value0 – 256
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Background Writer
Upstream classification
Latest boot value Value64
512 KiB (64 × 8kB)

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit 428b1d6b29ca — Allow to trigger kernel writeback after a configurable number of writes.
Commit date 2016-02-19
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 64 8kB 512 KiB (64 × 8kB)

How it works

After the background writer has written more than bgwriter_flush_after bytes, PostgreSQL asks the operating system to begin writing those page-cache pages toward storage. Zero disables the request.

The request is writeback smoothing, not a durability fsync. It can reduce large kernel flush stalls, but can also hurt workloads that benefit from retaining dirty data in the OS cache, and it has no effect on unsupported platforms.

The measured Docker/Linux boot value represents Linux behavior; PostgreSQL documents a platform-dependent default of 512kB on Linux and zero elsewhere. Backend and checkpointer writeback have separate thresholds. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune bgwriter_flush_after only with bgwriter and checkpoint metrics. The goal is fewer backend writes and smoother latency without excessive repeated writes; change one dimension at a time.
OLAP Bulk writes can reach bgwriter_flush_after limits continuously. Measure total bytes written, checkpoints, and storage queueing, not just foreground query latency.
Small nodes A small host usually needs conservative write smoothing. Aggressive bgwriter_flush_after can consume I/O needed by foreground work, so retain the default unless backend writes are a measured problem.

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: PG9.6–19 Beta 3 unmodified; OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 unmodified; TINY: PG9.6–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing bgwriter_flush_after without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

backend_flush_after · checkpoint_flush_after · bgwriter_delay · bgwriter_lru_maxpages · shared_buffers

References

12.5 - bgwriter_lru_maxpages

bgwriter_lru_maxpages — Background writer maximum number of LRU pages to flush per round. Observed in PG9.0–19 Beta 3; its last measured boot default is 100 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Background writer maximum number of LRU pages to flush per round.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 1073741823
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Background Writer
Upstream classification
Latest boot value Value100
100

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 100 — 100

How it works

bgwriter_lru_maxpages caps how many LRU-selected dirty buffers the background writer writes in one round. Zero disables this background-writing activity but does not disable checkpoints.

The writer tries to create enough clean reusable buffers for predicted demand, but this cap bounds each round. If it is reached repeatedly, foreground backends may still have to write buffers themselves.

The prediction comes from recent allocations multiplied by bgwriter_lru_multiplier, and rounds are separated by bgwriter_delay. Raising the cap can smooth latency at the cost of extra write amplification. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune bgwriter_lru_maxpages only with bgwriter and checkpoint metrics. The goal is fewer backend writes and smoother latency without excessive repeated writes; change one dimension at a time.
OLAP Bulk writes can reach bgwriter_lru_maxpages limits continuously. Measure total bytes written, checkpoints, and storage queueing, not just foreground query latency.
Small nodes A small host usually needs conservative write smoothing. Aggressive bgwriter_lru_maxpages can consume I/O needed by foreground work, so retain the default unless backend writes are a measured problem.

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 800 different 800
OLAP 800 different 800
CRIT 800 different 800
TINY 800 different 800
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 800 (dcs); OLAP: PG9.0–19 Beta 3 = 800 (dcs); CRIT: PG9.0–19 Beta 3 = 800 (dcs); TINY: PG9.0–19 Beta 3 = 800 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The higher per-round cap is intended to give the frequently running background writer enough capacity to prepare clean buffers instead of forcing foreground backends to write them.

Common pitfalls

  • Changing bgwriter_lru_maxpages without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

bgwriter_lru_multiplier · bgwriter_delay · bgwriter_flush_after · shared_buffers · checkpoint_completion_target

References

12.6 - bgwriter_lru_multiplier

bgwriter_lru_multiplier — Multiple of the average buffer usage to free per round. Observed in PG9.0–19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Multiple of the average buffer usage to free per round.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Background Writer
Upstream classification
Latest boot value Value2
2

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 2 — 2

How it works

The background writer averages recent buffer allocations and multiplies that demand by bgwriter_lru_multiplier to choose a target number of clean reusable buffers. A value above 1 adds cushion for bursts.

This is a forecast multiplier, not a direct number of pages. Actual writes remain capped by bgwriter_lru_maxpages and occur once per bgwriter_delay round.

More cushion can reduce foreground backend writes and latency spikes, but pages dirtied repeatedly between checkpoints may be written more times, increasing total I/O. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune bgwriter_lru_multiplier only with bgwriter and checkpoint metrics. The goal is fewer backend writes and smoother latency without excessive repeated writes; change one dimension at a time.
OLAP Bulk writes can reach bgwriter_lru_multiplier limits continuously. Measure total bytes written, checkpoints, and storage queueing, not just foreground query latency.
Small nodes A small host usually needs conservative write smoothing. Aggressive bgwriter_lru_multiplier can consume I/O needed by foreground work, so retain the default unless backend writes are a measured problem.

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 5.0 different 5.0
OLAP 5.0 different 5.0
CRIT 5.0 different 5.0
TINY 5.0 different 5.0
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 5.0 (dcs); OLAP: PG9.0–19 Beta 3 = 5.0 (dcs); CRIT: PG9.0–19 Beta 3 = 5.0 (dcs); TINY: PG9.0–19 Beta 3 = 5.0 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The larger forecast cushion is intended to absorb bursts in buffer demand, accepting possible extra background writes.

Common pitfalls

  • Changing bgwriter_lru_multiplier without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

bgwriter_lru_maxpages · bgwriter_delay · bgwriter_flush_after · shared_buffers · checkpoint_completion_target

References

12.7 - commit_timestamp_buffers

commit_timestamp_buffers — Sets the size of the dedicated buffer pool used for the commit timestamp cache. Observed in PG17–19 Beta 3; its last measured boot default is 0 B (0 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size of the dedicated buffer pool used for the commit timestamp cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value0 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value0
0 B (0 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 53c2a97a9266 — Improve performance of subsystems on top of SLRU
Commit date 2024-02-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 0 8kB 0 B (0 × 8kB)

How it works

commit_timestamp_buffers allocates a dedicated startup-time shared buffer pool for pages in pg_commit_ts, the SLRU area used when commit timestamp tracking is enabled.

A configured zero is an automatic sizing request, not zero memory: PostgreSQL derives shared_buffers/512, clamps it to at least 16 and at most 1024 blocks, and allocates the result at server start.

The cache can reduce pg_commit_ts reads but does not enable commit timestamp collection; track_commit_timestamp is the separate functional switch. Increasing it consumes real shared memory. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave commit_timestamp_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.
OLAP Analytical workload labels alone do not justify changing commit_timestamp_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.
Small nodes Keep commit_timestamp_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing commit_timestamp_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

track_commit_timestamp · shared_buffers · transaction_buffers · subtransaction_buffers

References

12.8 - dynamic_shared_memory_type

dynamic_shared_memory_type — Selects the dynamic shared memory implementation used. Observed in PG9.4–19 Beta 3; its last measured boot default is posix in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Selects the dynamic shared memory implementation used.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueposix, sysv, mmap
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Valueposix
posix

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit 0ac5e5a7e152 — Allow dynamic allocation of shared memory segments.
Commit date 2013-10-09
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–19 Beta 3 posix — posix

How it works

dynamic_shared_memory_type selects how PostgreSQL creates dynamic shared memory segments used by parallel query and extensions: POSIX, System V, Windows, or file-backed mmap where supported.

The available enum values and selected boot default are platform dependent. The Docker/Linux catalog reports posix; that is not a portable promise for Windows or systems lacking POSIX shared memory.

The mmap implementation stores mapped files under pg_dynshmem and is generally discouraged because dirty pages may be written repeatedly. min_dynamic_shared_memory can preallocate part of parallel-query memory in the main shared region. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the platform’s first supported default, normally posix on the measured Linux images. Change only to solve an API availability or diagnostic requirement, and restart-test parallel query plus extension workers on the target OS.
OLAP Parallel queries use dynamic segments heavily, but choose the implementation by OS support and allocation behavior, not scan throughput alone. Avoid file-backed mmap on ordinary disk because repeated writeback can add I/O; a RAM disk is a special diagnostic case.
Small nodes Keep the platform default. sysv may need kernel tuning, and file-backed mmap can turn memory traffic into disk I/O; neither is a free way to reduce memory use.

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: PG9.4–19 Beta 3 unmodified; OLAP: PG9.4–19 Beta 3 unmodified; CRIT: PG9.4–19 Beta 3 unmodified; TINY: PG9.4–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the Linux-Docker posix boot value as portable to platforms without POSIX shared memory.
  • Using file-backed mmap on ordinary storage and creating repeated dirty-page writeback.
  • Selecting sysv without checking System V segment limits.
  • Confusing dynamic segments with the main region selected by shared_memory_type.
  • Changing the startup setting without testing parallel queries and extensions that allocate DSM.

Related parameters

shared_memory_type · min_dynamic_shared_memory · max_parallel_workers · max_worker_processes · huge_pages

References

12.9 - effective_io_concurrency

Tells PostgreSQL how many storage I/O operations one session should expect to issue concurrently. It shapes asynchronous reads and, on supported systems, prefetch distance; it is not a global I/O limit.
Note

Fact — official short description: “Number of simultaneous requests that can be handled efficiently by the disk subsystem.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value16
16

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–17 1 — 1
PG18–19 Beta 3 16 — 16

How it works

effective_io_concurrency tells one session how much storage concurrency it should try to exploit; it is not a cluster-wide queue cap. A tablespace option of the same name can override the session setting for data on that storage.

In PG10–17 it mainly controls prefetch distance for supported paths and platforms. The measured Linux-Docker boot value is 1, but unsupported platforms without effective posix_fadvise used 0 as the default; that platform condition must accompany any historical default claim.

PostgreSQL 18 integrates the setting with core asynchronous I/O, uses a boot default of 16, and allows 0 to disable asynchronous requests governed by this target. io_max_concurrency remains the separate per-process execution ceiling, and combine limits control bytes per request.

Tuning advice

Tip

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

Workload Guidance
OLTP Start conservatively and measure read latency under concurrency. Fast point queries often gain less than bitmap or scan-heavy workloads, while a very high per-session value can multiply queue depth at high connection counts.
OLAP Analytical scans and bitmap heap scans are stronger candidates for higher values. Benchmark sustained throughput and tail latency together, especially on network or high-IOPS storage.
Small nodes Use the PG18 default or a modest value unless measurements show I/O stalls. A value of 200 is rarely justified on a small host merely because the disk is labeled SSD.

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 200 different 200
OLAP 200 different 200
CRIT 200 different 200
TINY 200 different 200
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 200 (dcs); OLAP: PG9.0–19 Beta 3 = 200 (dcs); CRIT: PG9.0–19 Beta 3 = 200 (dcs); TINY: PG9.0–19 Beta 3 = 200 (dcs). Advice, pending human review — Editorial inference: Pigsty’s SSD branch assumes deep per-session read concurrency and prefetch are beneficial; that assumption requires device-level validation.

Common pitfalls

  • Treating this per-session target as a cluster-wide cap; many sessions can multiply outstanding I/O.
  • Calling 1 the unconditional PG10–17 upstream default even though unsupported platforms defaulted to 0.
  • Applying PG18 AIO behavior to older releases that used the setting chiefly for prefetch advice.
  • Using one global value for mixed-storage tablespaces instead of considering tablespace overrides.
  • Raising the target until device queueing increases latency for every session.

Related parameters

maintenance_io_concurrency · io_method · io_max_concurrency · io_combine_limit · random_page_cost · effective_cache_size

References

12.10 - file_copy_method

file_copy_method — Selects the file copy method. Observed in PG18–19 Beta 3; its last measured boot default is copy in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Selects the file copy method.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuecopy, clone
— for non-enum types
Category ValueResource Usage / Disk
Upstream classification
Latest boot value Valuecopy
copy

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit f78ca6f3ebbb — Introduce file_copy_method setting.
Commit date 2025-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 copy — copy

How it works

file_copy_method chooses COPY or CLONE for CREATE DATABASE … STRATEGY=FILE_COPY and ALTER DATABASE … SET TABLESPACE. It does not change SQL COPY or general file reads.

CLONE uses copy_file_range() on Linux/FreeBSD or copyfile on macOS, allowing supporting file systems to share blocks or offload the operation. Availability and the actual optimization depend on the operating system and file system; selecting CLONE does not prove that blocks were shared.

Copy-on-write can make the initial operation fast, but later writes allocate private blocks and snapshots still share failure domains. Backup, quota, and free-space accounting must understand the file system semantics. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Use COPY as the compatibility baseline. Select CLONE only after CREATE DATABASE … STRATEGY=FILE_COPY and ALTER DATABASE … SET TABLESPACE are tested on the exact kernel and file system, including backup, quota, and free-space monitoring.
OLAP Workload type does not determine the method; clone support and copy-on-write behavior do. CLONE can shorten large database copies, but benchmark the initial operation and subsequent write amplification before standardizing it.
Small nodes Prefer COPY unless the file system’s clone semantics are known and operational tooling understands shared extents. A fast initial clone can still create later space pressure on a small volume.

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 clone different clone
OLAP clone different clone
CRIT clone different clone
TINY clone different clone
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 = clone (dcs); OLAP: PG18–19 Beta 3 = clone (dcs); CRIT: PG18–19 Beta 3 = clone (dcs); TINY: PG18–19 Beta 3 = clone (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The template comment explicitly targets near-instant database cloning on copy-on-write file systems; support and free-space semantics still require deployment validation.

Common pitfalls

  • Assuming CLONE guarantees copy-on-write block sharing; the kernel and file system decide the actual optimization.
  • Expecting the parameter to affect SQL COPY or ordinary relation reads.
  • Ignoring later private-block allocation and free-space pressure after a fast clone.
  • Using CLONE before backup, quota, and filesystem tooling understand shared extents.

Related parameters

file_extend_method · data_directory · temp_tablespaces · shared_buffers

References

12.11 - file_extend_method

file_extend_method — Selects the method used for extending data files. Observed in PG16–19 Beta 3; its last measured boot default is posix_fallocate in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Selects the method used for extending data files.”

Identity

Type Valueenum
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 Valueposix_fallocate, write_zeros
— for non-enum types
Category ValueResource Usage / Disk
Upstream classification
Latest boot value Valueposix_fallocate
posix_fallocate

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit e37b59802846 — Add file_extend_method=posix_fallocate,write_zeros.
Commit date 2025-05-31
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16–19 Beta 3 posix_fallocate — posix_fallocate

How it works

file_extend_method chooses how PostgreSQL grows relation files during bulk extension: posix_fallocate when available or explicit zero writes. Extensions of eight blocks or fewer still use zero writes.

The first supported method is platform dependent. posix_fallocate reserves space without writing every block, but unsupported file systems silently fall back; on current BTRFS it can disable compression for the file.

This affects allocation behavior and bulk-write latency, not WAL durability. Storage reservations, sparse-file behavior, compression, and copy-on-write semantics vary by file system. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep file_extend_method at the detected/default value unless operating-system support and a controlled benchmark justify a change. Validate startup and recovery on the exact kernel and file system.
OLAP Large allocations or bulk I/O can make file_extend_method visible, but platform capability is the first gate. Benchmark on production-equivalent storage and include failure/fallback behavior.
Small nodes Avoid nondefault file_extend_method on a small or heterogeneous fleet unless it solves a verified platform issue. Portability and reliable startup usually outweigh a speculative gain.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing file_extend_method without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

file_copy_method · backend_flush_after · checkpoint_flush_after · wal_sync_method

References

12.12 - hash_mem_multiplier

The multiplier that lets hash-based executor operations use a larger memory budget than the work_mem base.
Note

Fact — official short description: “Multiple of “work_mem” to use for hash tables.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1 – 1000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value2
2

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit 78530c8e7a5a — Add hash_mem_multiplier GUC.
Commit date 2020-07-29
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–14 1 — 1
PG15–19 Beta 3 2 — 2

How it works

The memory ceiling for a hash table is work_mem multiplied by hash_mem_multiplier. It applies to hash joins, hash aggregation, memoize nodes, and other hash-based executor work, but does not enlarge the limit for sort operations.

The parameter first appears in the PG9.0–19 Beta 3 inventory in PostgreSQL 13. Its boot default is 1.0 in PostgreSQL 13–14 and 2.0 from PostgreSQL 15 onward.

A query can contain several hash operations, and parallel workers can execute their own operations, so the product is still an operation-level limit rather than a whole-query memory cap.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the upstream default or make modest increases only after proving recurring hash spills. Evaluate the product with work_mem and peak active plans; do not tune the multiplier in isolation.
OLAP Higher values can help large hash joins and aggregations when memory is genuinely available. Increase under a controlled concurrency ceiling and compare batches, spill volume, and end-to-end runtime.
Small nodes Stay near the default. A high multiplier can turn a seemingly modest work_mem into hundreds of megabytes per hash operation.

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 8.0 different 8.0
OLAP 8.0 different 8.0
CRIT 8.0 different 8.0
TINY 8.0 different 8.0
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG13–19 Beta 3 = 8.0 (dcs); OLAP: PG13–19 Beta 3 = 8.0 (dcs); CRIT: PG13–19 Beta 3 = 8.0 (dcs); TINY: PG13–19 Beta 3 = 8.0 (dcs). Advice, pending human review — Editorial inference: Pigsty bounds the base work_mem and then gives memory-sensitive hash operations a larger allowance; the resulting per-operation products and parallel concurrency require explicit human review.

Common pitfalls

  • Reading the value as an absolute memory size rather than a multiplier of work_mem.
  • Forgetting that it has no effect before PostgreSQL 13 and that the upstream default changed in PostgreSQL 15.
  • Expecting it to help sorts, which remain governed by work_mem.
  • Multiplying only once per query despite multiple hash nodes or parallel workers.

Related parameters

work_mem · temp_file_limit · enable_hashjoin · enable_hashagg · max_parallel_workers_per_gather

References

12.13 - huge_page_size

huge_page_size — The size of huge page that should be requested. Observed in PG14–19 Beta 3; its last measured boot default is 0 B in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “The size of huge page that should be requested.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit ValuekB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value0
0 B

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit d2bddc2500fb — Add huge_page_size setting for use on Linux.
Commit date 2020-07-17
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 0 kB 0 B

How it works

huge_page_size selects the explicit huge-page size requested for PostgreSQL’s main shared-memory area when huge_pages is used. Zero means the operating system’s default huge-page size.

This is a startup allocation choice, not an amount of memory. Supported nonzero sizes are architecture and kernel dependent, and PostgreSQL currently supports nondefault selection only on Linux.

The requested page size must match provisioned huge-page pools and the shared-memory allocation. It affects the main shared area, not ordinary backend allocations such as work_mem. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep 0 so PostgreSQL uses the system’s default explicit huge-page size. Choose a nonzero size only on Linux after provisioning the matching huge-page pool and verifying startup plus huge_pages_status with the intended shared-memory footprint.
OLAP A large main shared-memory region can make page-table savings material, but the useful size depends on architecture, kernel pools, fragmentation, and restart operations—not bulk-I/O throughput. Benchmark the exact host and preserve enough ordinary memory for backends and the OS.
Small nodes Keep 0. A nondefault explicit size adds kernel provisioning and startup-failure risk that rarely pays back on a small shared-memory allocation.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Reading 0 as zero-byte huge pages rather than ‘use the system default huge-page size’.
  • Selecting a nonzero size on a non-Linux platform, where nondefault sizes are not supported.
  • Requesting a page size whose kernel pool has not been provisioned and causing startup failure when huge_pages=on.
  • Confusing explicit huge pages for the main shared-memory area with Transparent Huge Pages or per-backend memory.

Related parameters

huge_pages · huge_pages_status · shared_buffers · shared_memory_type · min_dynamic_shared_memory

References

12.14 - huge_pages

Controls explicit huge-page use for PostgreSQL’s main shared-memory area on supported operating systems.
Note

Fact — official short description: “Use of huge pages on Linux or Windows.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueoff, on, try
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Valuetry
try

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit f8ce16d0d264 — Rename huge_tlb_pages to huge_pages, and improve docs.
Commit date 2014-03-03
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–19 Beta 3 try — try

How it works

huge_pages affects the main shared-memory area and is evaluated only at server start. try requests huge pages and falls back to normal pages, on makes failure fatal, and off skips the request.

Explicit huge pages can reduce page-table size and CPU time spent on memory management, especially with a large contiguous shared-memory allocation. On Linux, PostgreSQL requires shared_memory_type=mmap and enough pre-provisioned huge pages; huge_pages_status reports the actual outcome.

Explicit HugeTLB pages are not the same as Linux Transparent Huge Pages. PostgreSQL documentation currently discourages THP for some Linux versions even while describing explicit huge pages as potentially beneficial.

Tuning advice

Tip

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

Workload Guidance
OLTP Use try while validating operating-system provisioning and huge_pages_status. Switch to on only when failure to obtain huge pages should deliberately block startup and the reservation is managed reliably across reboots.
OLAP Large shared-memory footprints may benefit more, but calculate the required page count and leave memory for backends, query workspaces, and the OS. Benchmark rather than treating huge pages as an automatic throughput win.
Small nodes Leave try or use off when huge-page reservation would create more operational complexity than benefit. Do not reserve a large fraction of a small host without a complete memory budget.

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 try same as boot try
OLAP try same as boot try
CRIT try same as boot try
TINY try same as boot try
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.4–19 Beta 3 = try (dcs); OLAP: PG9.4–19 Beta 3 = try (dcs); CRIT: PG9.4–19 Beta 3 = try (dcs); TINY: PG9.4–19 Beta 3 = try (dcs). Advice, pending human review — Editorial inference: this preserves opportunistic use when the node is provisioned while keeping startup safe when huge pages are unavailable; OS-level reservation policy must be reviewed separately.

Common pitfalls

  • Confusing explicit huge pages with Transparent Huge Pages.
  • Setting on before provisioning enough pages, causing PostgreSQL startup to fail.
  • Assuming the setting covers work_mem or other ordinary per-process allocations; it targets the main shared-memory area.
  • Checking configuration but not the runtime huge_pages_status result.

Related parameters

huge_page_size · huge_pages_status · shared_buffers · shared_memory_type · min_dynamic_shared_memory

References

12.15 - io_combine_limit

io_combine_limit — Limit on the size of data reads and writes. Observed in PG17–19 Beta 3; its last measured boot default is 128 KiB (16 × 8kB) in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Limit on the size of data reads and writes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value8kB
Raw unit
Range Value1 – 128
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value16
128 KiB (16 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 210622c60e1a — Provide vectored variant of ReadBuffer().
Commit date 2024-04-03
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

How it works

io_combine_limit limits the byte size of one I/O request formed by combining adjacent eligible operations. It controls bytes per request, not the number of requests that may execute concurrently.

In PostgreSQL 17 it is a standalone user-settable combine-size limit with a measured Linux-Docker boot value of 128kB; io_max_combine_limit does not exist in that release. In PostgreSQL 18, the effective size is the lower of io_combine_limit and the new server-start io_max_combine_limit.

Actual requests can be smaller when adjacent work is unavailable, and operating-system plus BLCKSZ constraints bound the feasible maximum. Its user context permits session- or transaction-local changes; changing it does not alter io_max_concurrency or worker count.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the version-appropriate default until a benchmark shows that combined-request size, rather than queue depth, is a bottleneck. In PG18, verify both io_combine_limit and io_max_combine_limit, and measure tail latency under realistic concurrency.
OLAP Larger combined requests can reduce syscall overhead during eligible sequential work, but may increase service time and reduce fairness. Compare throughput, latency, and actual request sizes; do not infer a useful value from device queue depth alone.
Small nodes Retain 128kB unless measured adjacent I/O shows a benefit from another size. On PG18, raising only io_combine_limit above io_max_combine_limit is ineffective; on PG17 there is no separate clamp GUC.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Applying the PG18 io_max_combine_limit clamp to PostgreSQL 17, where that GUC does not exist.
  • Treating a byte-size limit as I/O concurrency or queue depth.
  • Raising io_combine_limit above the PG18 server clamp and expecting larger requests.
  • Assuming every eligible operation reaches the configured size even when adjacent I/O is unavailable.

Related parameters

io_max_combine_limit · io_max_concurrency · io_method · effective_io_concurrency · maintenance_io_concurrency

References

12.16 - io_max_combine_limit

io_max_combine_limit — Server-wide limit that clamps io_combine_limit. Observed in PG18–19 Beta 3; its last measured boot default is 128 KiB (16 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Server-wide limit that clamps io_combine_limit.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value1 – 128
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value16
128 KiB (16 × 8kB)

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 10f664684751 — Introduce io_max_combine_limit.
Commit date 2025-03-19
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

How it works

io_max_combine_limit is the server-start ceiling that silently clamps the user-settable io_combine_limit. It protects the I/O subsystem from request sizes beyond the configured server policy.

This controls bytes per combined operation, not queue depth. The feasible maximum depends on operating system and BLCKSZ, typically 1MB on Unix and 128kB on Windows.

Raising io_combine_limit above this value has no effect until this startup parameter is also raised. Combined requests can still be smaller when adjacent work is unavailable. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the PG18 server clamp at 128kB unless measurements show that larger combined requests improve eligible I/O without harming latency. Raising it alone changes nothing while io_combine_limit remains lower, and changing it requires a restart.
OLAP A larger clamp merely permits a larger user combine limit; it does not create adjacent I/O or add concurrency. Benchmark actual request sizes, sequential throughput, and mixed-workload fairness with both parameters set intentionally.
Small nodes Retain 128kB on small or mixed-use storage. Do not increase a restart-only global ceiling to fix queue-depth problems, which belong to the concurrency controls.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the server byte-size clamp as an I/O concurrency limit.
  • Raising io_max_combine_limit while io_combine_limit remains lower and expecting a change.
  • Expecting larger combined requests when adjacent eligible operations do not exist.
  • Ignoring operating-system and BLCKSZ limits, especially the smaller typical Windows maximum.
  • Forgetting that a change requires a server restart.

Related parameters

io_combine_limit · io_max_concurrency · io_method · shared_buffers

References

12.17 - io_max_concurrency

io_max_concurrency — Max number of IOs that one process can execute simultaneously. Observed in PG18–19 Beta 3; its last measured boot default is -1 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Max number of IOs that one process can execute simultaneously.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value-1 – 1024
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value-1
-1

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 02844012b304 — aio: Basic subsystem initialization
Commit date 2025-03-17
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 -1 — -1

How it works

io_max_concurrency is a PostgreSQL 18 server-start ceiling on the number of I/O operations that one process may execute simultaneously. It is per process, not a reservation and not a cluster-wide cap.

The default -1 asks PostgreSQL to derive a value from shared_buffers and configured process maxima, capped at 64. Because many backends and workers can each reach their own ceiling, possible cluster-wide outstanding I/O can be much larger.

effective_io_concurrency and maintenance_io_concurrency are workload targets below this ceiling; io_method chooses the execution mechanism, and combine limits control bytes per request. Changing io_max_concurrency requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave -1 until measurements show the automatic per-process ceiling constrains eligible AIO. If setting it explicitly, multiply the value across concurrently active processes and test device queueing plus tail latency after the required restart.
OLAP Raise the per-process ceiling only when one scan or maintenance process cannot keep high-IOPS storage busy and the target-concurrency settings are already appropriate. Compare outstanding-operation counts, throughput, and latency; this parameter does not change request size.
Small nodes Prefer -1. An explicit high ceiling is multiplied by concurrent processes and can overwhelm a small device even though no single process exceeds its configured limit.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the per-process ceiling as a cluster-wide I/O limit.
  • Reading -1 as unlimited rather than automatic sizing capped at 64.
  • Calling the ceiling reserved capacity; it permits concurrency but does not preallocate I/O slots.
  • Confusing operation count with io_combine_limit’s bytes per request.
  • Changing the value without a restart or without multiplying exposure across processes.

Related parameters

io_method · io_workers · effective_io_concurrency · maintenance_io_concurrency · io_combine_limit · max_connections

References

12.18 - io_max_workers

io_max_workers — Maximum number of I/O worker processes, for io_method=worker. Observed in PG19 Beta 3; its last measured boot default is 8 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Maximum number of I/O worker processes, for io_method=worker.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value1 – 32
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value8
8

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
Commit date 2026-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 8 — 8

How it works

PostgreSQL describes io_max_workers as follows: “Maximum number of I/O worker processes, for io_method=worker.” A configuration reload applies the value to the server without a full 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.

These controls govern the elastic background-worker pool used only when io_method is worker. io_min_workers keeps warm capacity, io_max_workers caps the pool, io_worker_launch_interval damps short bursts, and io_worker_idle_timeout lets unused workers retire; they do not raise a backend’s separate io_max_concurrency ceiling.

Read it together with io_min_workers, io_worker_idle_timeout, io_worker_launch_interval, io_method. 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

Tip

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

Workload Guidance
OLTP Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.
OLAP Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.
Small nodes Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism.

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: 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 io_max_workers as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

io_min_workers · io_worker_idle_timeout · io_worker_launch_interval · io_method · io_max_concurrency · io_combine_limit

References

12.19 - io_method

io_method — Selects the method for executing asynchronous I/O. Observed in PG18–19 Beta 3; its last measured boot default is worker in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Selects the method for executing asynchronous I/O.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuesync, worker, io_uring
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Valueworker
worker

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 02844012b304 — aio: Basic subsystem initialization
Commit date 2025-03-17
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 worker — worker

How it works

worker sends eligible I/O through dedicated I/O worker processes; io_uring uses Linux io_uring and requires a build with liburing support; sync performs asynchronous-eligible operations synchronously. The upstream default is worker.

The PG18 AIO subsystem allows backends to queue multiple reads and can improve sequential scans, bitmap heap scans, vacuum, and other supported operations. It does not make every PostgreSQL I/O path asynchronous.

io_workers matters only when worker is selected. io_max_concurrency and the I/O combine limits control different dimensions of queue depth and request size, so method selection should be evaluated with them and with the storage stack.

Tuning advice

Tip

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

Workload Guidance
OLTP Use worker as the compatibility baseline. Test io_uring only on a verified build and kernel, and keep it only if representative concurrent latency improves without destabilizing the storage queue.
OLAP Sequential and bitmap-heavy analytical workloads are promising AIO candidates. Benchmark worker and io_uring with realistic scan concurrency, not just a single cold scan.
Small nodes Worker is a safe default; sync can be a diagnostic fallback when worker overhead or platform constraints matter. Avoid spending scarce processes on excessive io_workers.

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 worker same as boot {{ pg_effective_io_method }}
OLAP worker same as boot {{ pg_effective_io_method }}
CRIT worker same as boot {{ pg_effective_io_method }}
TINY worker same as boot {{ pg_effective_io_method }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 = worker (dcs); OLAP: PG18–19 Beta 3 = worker (dcs); CRIT: PG18–19 Beta 3 = worker (dcs); TINY: PG18–19 Beta 3 = worker (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: Pigsty selects the portable PG18 AIO baseline while leaving io_uring as an explicit operator choice.

Common pitfalls

  • The parameter does not exist before PostgreSQL 18.
  • Changing it requires a server restart.
  • io_uring requires operating-system and build support; the enum value alone does not provide that support.
  • io_workers has no effect unless io_method=worker.
  • AIO benefits only eligible paths and cannot compensate for an overloaded or poorly configured storage layer.

Related parameters

io_workers · io_max_concurrency · io_combine_limit · io_max_combine_limit · effective_io_concurrency · maintenance_io_concurrency

References

12.20 - io_min_workers

io_min_workers — Minimum number of I/O worker processes, for io_method=worker. Observed in PG19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Minimum number of I/O worker processes, for io_method=worker.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value1 – 32
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value2
2

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
Commit date 2026-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 2 — 2

How it works

PostgreSQL describes io_min_workers as follows: “Minimum number of I/O worker processes, for io_method=worker.” A configuration reload applies the value to the server without a full 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.

These controls govern the elastic background-worker pool used only when io_method is worker. io_min_workers keeps warm capacity, io_max_workers caps the pool, io_worker_launch_interval damps short bursts, and io_worker_idle_timeout lets unused workers retire; they do not raise a backend’s separate io_max_concurrency ceiling.

Read it together with io_max_workers, io_worker_idle_timeout, io_worker_launch_interval, io_method. 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

Tip

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

Workload Guidance
OLTP Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.
OLAP Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.
Small nodes Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism.

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: 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 io_min_workers as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

io_max_workers · io_worker_idle_timeout · io_worker_launch_interval · io_method · io_max_concurrency · io_combine_limit

References

12.21 - io_worker_idle_timeout

io_worker_idle_timeout — Maximum time before idle I/O worker processes time out, for io_method=worker. Observed in PG19 Beta 3; its last measured boot default is 1 min in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Maximum time before idle I/O worker processes time out, for io_method=worker.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value60000
1 min

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
Commit date 2026-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 60000 ms 1 min

How it works

PostgreSQL describes io_worker_idle_timeout as follows: “Maximum time before idle I/O worker processes time out, for io_method=worker.” A configuration reload applies the value to the server without a full 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.

These controls govern the elastic background-worker pool used only when io_method is worker. io_min_workers keeps warm capacity, io_max_workers caps the pool, io_worker_launch_interval damps short bursts, and io_worker_idle_timeout lets unused workers retire; they do not raise a backend’s separate io_max_concurrency ceiling.

Read it together with io_min_workers, io_max_workers, io_worker_launch_interval, io_method. 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

Tip

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

Workload Guidance
OLTP Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.
OLAP Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.
Small nodes Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism.

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: 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 io_worker_idle_timeout as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

io_min_workers · io_max_workers · io_worker_launch_interval · io_method · io_max_concurrency · io_combine_limit

References

12.22 - io_worker_launch_interval

io_worker_launch_interval — Minimum time before launching a new I/O worker process, for io_method=worker. Observed in PG19 Beta 3; its last measured boot default is 100 ms in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Minimum time before launching a new I/O worker process, for io_method=worker.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value100
100 ms

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
Commit date 2026-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 100 ms 100 ms

How it works

PostgreSQL describes io_worker_launch_interval as follows: “Minimum time before launching a new I/O worker process, for io_method=worker.” A configuration reload applies the value to the server without a full 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.

These controls govern the elastic background-worker pool used only when io_method is worker. io_min_workers keeps warm capacity, io_max_workers caps the pool, io_worker_launch_interval damps short bursts, and io_worker_idle_timeout lets unused workers retire; they do not raise a backend’s separate io_max_concurrency ceiling.

Read it together with io_min_workers, io_max_workers, io_worker_idle_timeout, io_method. 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

Tip

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

Workload Guidance
OLTP Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.
OLAP Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.
Small nodes Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism.

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: 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 io_worker_launch_interval as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

io_min_workers · io_max_workers · io_worker_idle_timeout · io_method · io_max_concurrency · io_combine_limit

References

12.23 - io_workers

io_workers — Number of IO worker processes, for io_method=worker. Observed in PG18; its last measured boot default is 3 in PG18, with sighup context. It was removed in PG19 Beta 3.
Note

Fact — official short description: “Number of IO worker processes, for io_method=worker.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value1 – 32
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value3
3

Lifecycle

Fact Value
First observed PG18
Present in PG18
Removed in PG19 Beta 3
Introduction commit 55b454d0e140 — aio: Infrastructure for io_method=worker
Commit date 2025-03-18
Discussion thread 1 · thread 2 · thread 3

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18 3 — 3

How it works

io_workers sets the number of dedicated I/O worker processes used by PostgreSQL 18 when io_method=worker. It has no effect for io_uring or sync.

I/O workers execute asynchronous requests on behalf of database processes; this is an execution pool, distinct from parallel query workers and background worker slots.

Changing the count is reloadable, but useful capacity still depends on io_max_concurrency, workload queue depth, storage latency, and CPU. More workers do not guarantee more device throughput. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune io_workers only when io_method=worker. Start from the PG18 default 3, measure worker saturation, CPU use, and tail latency, and increase the pool only when queued eligible I/O waits for worker execution rather than for the device.
OLAP Sustained eligible scans can benefit from enough I/O workers to feed storage, but extra processes add scheduling overhead and cannot exceed the per-process or device concurrency bottleneck. Compare throughput and worker utilization; request size is controlled elsewhere.
Small nodes Keep 3 or a measured smaller value when process and CPU budgets are tight. io_workers has no effect under io_uring or sync, so never spend tuning effort on it until io_method is confirmed as worker.

Pigsty

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

Template Effective value Versus upstream boot Source expression
OLTP 4 different {{ pg_io_workers }}
OLAP 4 different {{ pg_io_workers }}
CRIT 4 different {{ pg_io_workers }}
TINY 3 same as boot {{ pg_io_workers }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18 = 4 (dcs); OLAP: PG18 = 4 (dcs); CRIT: PG18 = 4 (dcs); TINY: PG18 = 3 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The resolved worker pool gives PG18’s worker AIO method more executors on non-tiny profiles while keeping the tiny profile at the upstream boot count.

Common pitfalls

  • Changing io_workers while io_method is io_uring or sync, where it has no effect.
  • Treating worker-process count as bytes per request or as the per-process I/O ceiling.
  • Adding workers when the storage device, not the worker pool, is already saturated.
  • Forgetting that the reloadable pool still consumes process slots, CPU, and scheduling capacity.

Related parameters

io_method · io_max_concurrency · effective_io_concurrency · maintenance_io_concurrency · max_worker_processes

References

12.24 - logical_decoding_work_mem

logical_decoding_work_mem — Sets the maximum memory to be used for logical decoding. Observed in PG13–19 Beta 3; its last measured boot default is 64 MiB in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum memory to be used for logical decoding.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValuekB
Raw unit
Range Value64 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value65536
64 MiB

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit cec2edfa7859 — Add logical_decoding_work_mem to limit ReorderBuffer memory usage.
Commit date 2019-11-16
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 65536 kB 64 MiB

How it works

logical_decoding_work_mem is the real memory threshold for one logical decoding stream before decoded changes are written to local temporary files. It is independent of ordinary query work_mem.

Each replication connection uses one such buffer, and concurrency is bounded by replication sender capacity rather than client sessions. Large in-progress transactions can spill and later be reread.

Raising the threshold can reduce serialization I/O for logical replication, but the cluster memory budget must multiply it by concurrent decoding streams and include output-plugin memory outside this accounting. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Change logical_decoding_work_mem only after identifying the corresponding resource bottleneck under concurrency. Budget total memory, I/O, disk, or kernel capacity rather than optimizing one process in isolation.
OLAP Benchmark logical_decoding_work_mem with representative bulk and scan phases. Include sustained throughput, spill/writeback, and interference with other sessions, not only one operation’s elapsed time.
Small nodes Keep logical_decoding_work_mem conservative on a small host and prefer the upstream default when evidence is weak. A setting copied from a large server can consume a disproportionate share of resources.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing logical_decoding_work_mem without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

work_mem · max_wal_senders · max_replication_slots · debug_logical_replication_streaming · temp_file_limit

References

12.25 - maintenance_io_concurrency

maintenance_io_concurrency — A variant of “effective_io_concurrency” that is used for maintenance work. Observed in PG13–19 Beta 3; its last measured boot default is 16 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “A variant of “effective_io_concurrency” that is used for maintenance work.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / I/O
Upstream classification
Latest boot value Value16
16

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit fc34b0d9de27 — Introduce a maintenance_io_concurrency setting.
Commit date 2020-03-16
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–17 10 — 10
PG18–19 Beta 3 16 — 16

How it works

maintenance_io_concurrency is the per-maintenance-operation target for storage concurrency used by work performed on behalf of many clients. A tablespace option of the same name can override it for that storage; it is neither a cluster-wide device cap nor a memory allocation.

In PG13–17 it chiefly controls maintenance prefetch on supported systems. The measured Linux-Docker boot value is 10, while unsupported platforms without effective prefetch-advice support defaulted to 0; those releases do not have the PG18 core-AIO execution model.

PostgreSQL 18 integrates the target with core AIO and uses a boot default of 16. io_max_concurrency separately clamps simultaneous execution by one process, io_method chooses the execution mechanism, and combine limits control bytes per request. Its user context permits scoped runtime changes.

Tuning advice

Tip

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

Workload Guidance
OLTP For PG13–17, tune this as a maintenance-prefetch target only on supported storage; for PG18, tune it as an AIO concurrency target. Measure foreground tail latency while VACUUM or other eligible maintenance runs, and use a tablespace override for heterogeneous storage.
OLAP Higher maintenance concurrency can shorten eligible scans or vacuum work on high-latency, high-IOPS storage, but it can also deepen the queue seen by analytical queries. Benchmark maintenance completion time and mixed-workload latency together; it does not change request size.
Small nodes Use the version- and platform-appropriate default unless maintenance is demonstrably I/O-stalled. A small host can saturate storage with a low target, so do not copy Pigsty’s SSD value 100 without measurement.

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 100 different 100
OLAP 100 different 100
CRIT 100 different 100
TINY 100 different 100
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG13–19 Beta 3 = 100 (dcs); OLAP: PG13–19 Beta 3 = 100 (dcs); CRIT: PG13–19 Beta 3 = 100 (dcs); TINY: PG13–19 Beta 3 = 100 (dcs). Advice, pending human review — Editorial inference: the template asks SSD maintenance to exploit more prefetch/AIO concurrency, but the value is a target per maintenance operation and must be validated against foreground latency.

Common pitfalls

  • Calling 10 the unconditional PG13–17 default when unsupported platforms used 0.
  • Back-projecting PG18 core-AIO semantics into PG13–17 prefetch behavior.
  • Treating the per-operation target as a cluster or device-wide cap.
  • Confusing concurrency with io_combine_limit’s bytes-per-request dimension.
  • Using one value across tablespaces with materially different storage.

Related parameters

effective_io_concurrency · io_method · io_max_concurrency · io_combine_limit · vacuum_buffer_usage_limit

References

12.26 - maintenance_work_mem

The memory ceiling for maintenance commands such as VACUUM, CREATE INDEX, and adding foreign-key constraints.
Note

Fact — official short description: “Sets the maximum memory to be used for maintenance operations.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValuekB
Raw unit
Range Value64 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value65536
64 MiB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.3 16384 kB 16 MiB
PG9.4–19 Beta 3 65536 kB 64 MiB

How it works

maintenance_work_mem applies to maintenance operations including VACUUM, CREATE INDEX, and ALTER TABLE ADD FOREIGN KEY. Because a session normally runs only one such operation at a time, it can usually be set higher than work_mem.

For parallel utility commands, PostgreSQL treats maintenance_work_mem as a limit for the entire utility command rather than granting the full amount to every parallel maintenance worker. CPU and I/O consumption can still rise with parallelism.

Autovacuum is a separate concurrency concern: when autovacuum_work_mem is -1, each autovacuum worker inherits maintenance_work_mem, so several workers can make the aggregate budget much larger than the single-operation value.

Tuning advice

Tip

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

Workload Guidance
OLTP Use enough memory to keep routine vacuum and index work efficient, but budget explicitly for simultaneous autovacuum workers. If interactive latency matters and maintenance_work_mem is large, give autovacuum_work_mem its own lower ceiling.
OLAP Larger values are often useful for index builds, vacuuming large relations, and restores. Schedule heavy maintenance and verify that concurrent maintenance, query memory, and the OS still fit together.
Small nodes Keep the global value modest and temporarily raise it only for controlled maintenance sessions. Check autovacuum inheritance before increasing it.

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 2048MB different {{ pg_maintenance_mem }}MB
OLAP 4096MB different {{ pg_maintenance_mem }}MB
CRIT 2048MB different {{ pg_maintenance_mem }}MB
TINY 2048MB different {{ pg_maintenance_mem }}MB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 2048MB (dcs); OLAP: PG9.0–19 Beta 3 = 4096MB (dcs); CRIT: PG9.0–19 Beta 3 = 2048MB (dcs); TINY: PG9.0–19 Beta 3 = 2048MB (dcs). Advice, pending human review — Editorial inference: the larger OLAP fraction is intended to favor bulk maintenance, while inherited autovacuum exposure needs separate review.

Common pitfalls

  • Assuming the value is harmless because maintenance is infrequent while leaving autovacuum_work_mem at -1.
  • Multiplying the limit by parallel maintenance workers; PostgreSQL applies it to the utility command as a whole.
  • Using a permanently large cluster-wide value for a one-off restore instead of a scoped SET.
  • Expecting more memory alone to solve maintenance dominated by locks or storage I/O.

Related parameters

autovacuum_work_mem · autovacuum_max_workers · max_parallel_maintenance_workers · vacuum_buffer_usage_limit · work_mem

References

12.27 - max_files_per_process

max_files_per_process — Sets the maximum number of files each server process is allowed to open simultaneously. Observed in PG9.0–19 Beta 3; its last measured boot default is 1000 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of files each server process is allowed to open simultaneously.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value64 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Kernel Resources
Upstream classification
Latest boot value Value1000
1000

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 1000 — 1000

How it works

max_files_per_process is PostgreSQL’s startup-time expectation for how many files one server subprocess may keep open, excluding files inherited already open from the postmaster.

It does not raise the kernel’s file-descriptor limit. PostgreSQL uses it in resource management, and on kernels that overcommit descriptors across processes a lower value can prevent system-wide exhaustion.

The relevant capacity is per process multiplied across backends and workers. ‘Too many open files’ can also require fixing OS service limits, connection counts, partition fan-out, or extension behavior. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP First compare the PostgreSQL value with the service’s real per-process nofile limit and observed descriptor use. Raising this GUC cannot raise the kernel limit; on systems that overcommit descriptors across many processes, a lower PostgreSQL value can be safer.
OLAP Large partition or index fan-out can increase descriptors in one backend, but size from measured peak opens and the aggregate backend/worker count. Resolve leaks and OS service limits before changing the PostgreSQL ceiling.
Small nodes Keep the default unless descriptor evidence says otherwise. A small host can exhaust the system-wide file table even when every process remains below its individual limit.

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

  • Expecting the GUC to raise ulimit or the service manager’s nofile limit.
  • Sizing only per process and ignoring the aggregate across connections and workers.
  • Raising the value to hide a descriptor leak or excessive partition/index fan-out.
  • Forgetting that files inherited already open from the postmaster are excluded from this count.

Related parameters

max_connections · max_worker_processes · max_wal_senders · shared_preload_libraries

References

12.28 - max_notify_queue_pages

max_notify_queue_pages — Sets the maximum number of allocated pages for NOTIFY / LISTEN queue. Observed in PG17–19 Beta 3; its last measured boot default is 1048576 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of allocated pages for NOTIFY / LISTEN queue.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value64 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Disk
Upstream classification
Latest boot value Value1048576
1048576

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 2cdf131c46e6 — Use larger segment file names for pg_notify
Commit date 2023-11-29
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 1048576 — 1048576

How it works

max_notify_queue_pages caps the number of database pages that the disk-backed LISTEN/NOTIFY queue may allocate. At the usual 8kB BLCKSZ, the PG18 default permits up to 8GB.

Notifications remain queued until all listening sessions have consumed or no longer need them. A listener that stays inside a long transaction can prevent cleanup and let queue usage grow.

This is disk capacity, not notify_buffers memory and not a limit on one payload. When the queue is full, transactions attempting NOTIFY can fail at commit. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Monitor pg_notification_queue_usage() and identify listeners that remain in long transactions before increasing capacity. Size the disk-backed queue from the maximum tolerated notification backlog and available database volume, not query scan throughput.
OLAP An OLAP label does not justify a larger queue. Long analytical transactions in listening sessions can delay cleanup, so separate listeners from long transactions and measure notification production versus consumption.
Small nodes Keep the default unless the application has a verified LISTEN/NOTIFY backlog requirement. More pages permit more disk consumption and postpone failure; they do not fix a stalled listener.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Increasing queue capacity instead of fixing a listener that stays inside a long transaction.
  • Confusing max_notify_queue_pages disk capacity with notify_buffers shared-memory cache.
  • Forgetting that, with 8kB pages, the default 1048576 pages permits up to about 8GB.
  • Assuming a larger queue changes an individual NOTIFY payload limit or delivery semantics.

Related parameters

notify_buffers · track_activities · max_connections · shared_buffers

References

12.29 - max_parallel_maintenance_workers

max_parallel_maintenance_workers — Sets the maximum number of parallel processes per maintenance operation. Observed in PG11–19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of parallel processes per maintenance operation.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1024
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Worker Processes
Upstream classification
Latest boot value Value2
2

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit 9da0cc35284b — Support parallel btree index builds.
Commit date 2018-02-02
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 2 — 2

How it works

max_parallel_maintenance_workers caps workers requested by one supported maintenance command, such as parallel CREATE INDEX or VACUUM. The leader is additional and may also perform work.

The cap does not reserve workers or guarantee they will be available. Requests compete within max_parallel_workers and max_worker_processes, and operation-specific rules can choose fewer.

Parallel maintenance can multiply CPU and I/O pressure; CREATE INDEX memory follows maintenance-specific accounting rather than simply granting maintenance_work_mem independently to every worker. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Set max_parallel_maintenance_workers from a concurrency budget, not core count alone. Protect latency-sensitive OLTP from report and maintenance bursts, and verify actual Workers Planned versus Workers Launched.
OLAP Analytical work can use a larger max_parallel_maintenance_workers, but multiply per-node memory and I/O by concurrent statements. Benchmark throughput under realistic worker contention rather than one isolated query.
Small nodes Keep max_parallel_maintenance_workers conservative on a small host. More possible workers can reduce throughput through context switching and memory pressure even when a single query becomes faster.

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 3 different {{ pg_max_parallel_mt_workers }}
OLAP 3 different {{ pg_max_parallel_mt_workers }}
CRIT 3 different {{ pg_max_parallel_mt_workers }}
TINY 2 same as boot {{ pg_max_parallel_mt_workers }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG11–19 Beta 3 = 3 (dcs); OLAP: PG11–19 Beta 3 = 3 (dcs); CRIT: PG11–19 Beta 3 = 3 (dcs); TINY: PG11–19 Beta 3 = 2 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The profile variables allocate modest parallel maintenance capacity, with one fewer worker in the tiny fixture to reduce resource pressure.

Common pitfalls

  • Treating max_parallel_maintenance_workers as reserved capacity rather than an upper bound shared with other work.
  • Ignoring that parallel plans multiply CPU, I/O, and work_mem-limited nodes.
  • Benchmarking one query without concurrent worker contention.
  • Assuming planned workers will always be launched at execution time.

Related parameters

max_parallel_workers · max_worker_processes · maintenance_work_mem · maintenance_io_concurrency · max_parallel_workers_per_gather

References

12.30 - max_parallel_workers

max_parallel_workers — Sets the maximum number of parallel workers that can be active at one time. Observed in PG10–19 Beta 3; its last measured boot default is 8 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of parallel workers that can be active at one time.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1024
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Worker Processes
Upstream classification
Latest boot value Value8
8

Lifecycle

Fact Value
First observed PG10
Present in PG10–19 Beta 3
Removed in No
Introduction commit b460f5d66931 — Add max_parallel_workers GUC.
Commit date 2016-12-02
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG10–19 Beta 3 8 — 8

How it works

max_parallel_workers caps the cluster-wide number of workers simultaneously active for parallel query and maintenance. It is a pool ceiling beneath max_worker_processes.

Per-operation parameters request workers from this pool, but no slots are reserved. A plan can start with fewer workers than planned, and concurrent jobs can starve each other.

Increasing it expands potential CPU, memory, and I/O concurrency; it does not itself make plans parallel. Planner thresholds, safety checks, and max_parallel_workers_per_gather still govern query choices. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Set max_parallel_workers from a concurrency budget, not core count alone. Protect latency-sensitive OLTP from report and maintenance bursts, and verify actual Workers Planned versus Workers Launched.
OLAP Analytical work can use a larger max_parallel_workers, but multiply per-node memory and I/O by concurrent statements. Benchmark throughput under realistic worker contention rather than one isolated query.
Small nodes Keep max_parallel_workers conservative on a small host. More possible workers can reduce throughput through context switching and memory pressure even when a single query becomes faster.

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 4 different {{ pg_max_parallel_workers }}
OLAP 7 different {{ pg_max_parallel_workers }}
CRIT 4 different {{ pg_max_parallel_workers }}
TINY 4 different {{ pg_max_parallel_workers }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG10–19 Beta 3 = 4 (dcs); OLAP: PG10–19 Beta 3 = 7 (dcs); CRIT: PG10–19 Beta 3 = 4 (dcs); TINY: PG10–19 Beta 3 = 4 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The resolved pool gives OLAP more cluster-wide parallel capacity than OLTP/crit/tiny, consistent with a throughput-oriented profile.

Common pitfalls

  • Treating max_parallel_workers as reserved capacity rather than an upper bound shared with other work.
  • Ignoring that parallel plans multiply CPU, I/O, and work_mem-limited nodes.
  • Benchmarking one query without concurrent worker contention.
  • Assuming planned workers will always be launched at execution time.

Related parameters

max_worker_processes · max_parallel_workers_per_gather · max_parallel_maintenance_workers · parallel_setup_cost · parallel_leader_participation

References

12.31 - max_parallel_workers_per_gather

max_parallel_workers_per_gather — Sets the maximum number of parallel processes per executor node. Observed in PG9.6–19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of parallel processes per executor node.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1024
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Worker Processes
Upstream classification
Latest boot value Value2
2

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit c9ce4a1c61eb — Eliminate “parallel degree” terminology.
Commit date 2016-06-09
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6 0 — 0
PG10–19 Beta 3 2 — 2

How it works

max_parallel_workers_per_gather limits how many workers one Gather or Gather Merge node may request. Zero prevents parallel query execution through these nodes without disabling other background workers.

Workers are not reserved and can be unavailable at execution time because max_parallel_workers and max_worker_processes are shared pools. The leader process is not included in this numeric limit.

Each parallel plan can multiply work_mem-limited nodes, CPU demand, and I/O. The planner weighs parallel_setup_cost and parallel_tuple_cost before deciding whether to request workers. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Set max_parallel_workers_per_gather from a concurrency budget, not core count alone. Protect latency-sensitive OLTP from report and maintenance bursts, and verify actual Workers Planned versus Workers Launched.
OLAP Analytical work can use a larger max_parallel_workers_per_gather, but multiply per-node memory and I/O by concurrent statements. Benchmark throughput under realistic worker contention rather than one isolated query.
Small nodes Keep max_parallel_workers_per_gather conservative on a small host. More possible workers can reduce throughput through context switching and memory pressure even when a single query becomes faster.

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 2 same as boot {{ pg_max_parallel_workers_per_gather|int }}
OLAP 4 different {{ pg_max_parallel_workers_per_gather|int }}
CRIT 0 different {{ pg_max_parallel_workers_per_gather|int }}
TINY 0 different {{ pg_max_parallel_workers_per_gather|int }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.6–19 Beta 3 = 2 (dcs); OLAP: PG9.6–19 Beta 3 = 4 (dcs); CRIT: PG9.6–19 Beta 3 = 0 (dcs); TINY: PG9.6–19 Beta 3 = 0 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The values allow modest OLTP and stronger OLAP query parallelism while explicitly suppressing Gather workers in crit and tiny profiles.

Common pitfalls

  • Treating max_parallel_workers_per_gather as reserved capacity rather than an upper bound shared with other work.
  • Ignoring that parallel plans multiply CPU, I/O, and work_mem-limited nodes.
  • Benchmarking one query without concurrent worker contention.
  • Assuming planned workers will always be launched at execution time.

Related parameters

max_parallel_workers · max_worker_processes · parallel_setup_cost · parallel_tuple_cost · parallel_leader_participation · work_mem

References

12.32 - max_prepared_transactions

max_prepared_transactions — Sets the maximum number of simultaneously prepared transactions. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum number of simultaneously prepared transactions.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value0
0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 — 0

How it works

max_prepared_transactions reserves capacity for two-phase transactions left in the prepared state by PREPARE TRANSACTION. Zero disables creating prepared transactions.

Prepared transactions retain locks and transaction state across client disconnects and crashes until COMMIT PREPARED or ROLLBACK PREPARED. Capacity requires shared memory and durable state.

A standby must configure at least the primary’s value or read queries can be refused. This is unrelated to SQL prepared statements and should remain zero unless a two-phase commit coordinator is operationally managed. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep max_prepared_transactions=0 unless a real two-phase-commit coordinator monitors and resolves every prepared transaction. If enabled, size primary and standbys consistently and alert on transaction age.
OLAP Analytical workload does not justify max_prepared_transactions. Enable only for an application protocol that requires durable prepared transactions, not for SQL prepared statements.
Small nodes Leave max_prepared_transactions=0 on a small deployment unless two-phase commit is mandatory and operational recovery is documented; stranded prepared transactions can block the cluster.

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 0 same as boot {{ pg_max_prepared_transactions }}
OLAP 0 same as boot {{ pg_max_prepared_transactions }}
CRIT 0 same as boot {{ pg_max_prepared_transactions }}
TINY 0 same as boot {{ pg_max_prepared_transactions }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 0 (dcs); OLAP: PG9.0–19 Beta 3 = 0 (dcs); CRIT: PG9.0–19 Beta 3 = 0 (dcs); TINY: PG9.0–19 Beta 3 = 0 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The explicit zero keeps two-phase prepared transactions disabled unless the user deliberately changes the profile variable and deploys a coordinator.

Common pitfalls

  • Changing max_prepared_transactions without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

max_connections · max_locks_per_transaction · wal_level · max_wal_senders

References

12.33 - max_stack_depth

max_stack_depth — Sets the maximum stack depth, in kilobytes. Observed in PG9.0–19 Beta 3; its last measured boot default is 100 KiB in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum stack depth, in kilobytes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit ValuekB
Raw unit
Range Value100 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value100
100 KiB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 100 kB 100 KiB

How it works

max_stack_depth is a guard used by selected recursive execution paths. It neither allocates a process stack nor changes the operating-system stack limit; the kernel limit remains authoritative.

The catalog’s raw boot_val is 100kB in every measured PG9.0–19 Beta 3 image, but the same fresh containers report setting=2048kB, matching the documented 2MB default after configuration/initdb. The 100kB boot fallback must not be presented as the ordinary effective setting.

A safe explicit value is the kernel stack limit, such as ulimit -s, minus roughly 1MB because not every C call site checks depth. Setting it above the real limit can let runaway recursion crash a backend. Its superuser context allows an authorized runtime change without a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the effective 2MB default unless a reproducible recursive function or expression reaches the PostgreSQL guard. Before raising it, record the service’s real kernel stack limit and preserve about 1MB of safety margin.
OLAP Query duration, table size, and bulk I/O do not justify a larger stack ceiling. Change it only for verified deep expression or function recursion, and test backend stability with the same OS service limits used in production.
Small nodes Do not lower or raise it merely to save memory: the value is a safety check, not reserved memory. Keep the configured default unless the kernel stack and a specific recursive workload prove another value safe and necessary.

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

  • Confusing boot_val=100kB with the measured and documented effective setting of 2048kB.
  • Treating max_stack_depth as allocated memory or a way to reduce resident memory.
  • Setting it above the kernel stack limit and allowing recursive code to crash a backend.
  • Copying a value across hosts without checking the service manager and ulimit stack settings.

Related parameters

max_worker_processes · shared_buffers · work_mem · max_connections

References

12.34 - max_worker_processes

max_worker_processes — Maximum number of concurrent worker processes. Observed in PG9.4–19 Beta 3; its last measured boot default is 8 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Maximum number of concurrent worker processes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value0 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Worker Processes
Upstream classification
Latest boot value Value8
8

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit 6bc8ef0b7f1f — Add new GUC, max_worker_processes, limiting number of bgworkers.
Commit date 2013-07-04
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–19 Beta 3 8 — 8

How it works

max_worker_processes is the startup-time ceiling for concurrent background worker processes, including parallel workers and extension-managed workers. It is broader than max_parallel_workers.

The setting allocates shared control capacity but does not launch workers. Replication, extensions, logical apply, and parallel execution can all depend on slots beneath this ceiling.

A standby should normally configure the same or a higher value than its primary because worker requirements can be replayed or promoted. Increasing it without a CPU and memory budget only creates possible concurrency. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Set max_worker_processes from a concurrency budget, not core count alone. Protect latency-sensitive OLTP from report and maintenance bursts, and verify actual Workers Planned versus Workers Launched.
OLAP Analytical work can use a larger max_worker_processes, but multiply per-node memory and I/O by concurrent statements. Benchmark throughput under realistic worker contention rather than one isolated query.
Small nodes Keep max_worker_processes conservative on a small host. More possible workers can reduce throughput through context switching and memory pressure even when a single query becomes faster.

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 24 different {{ pg_max_worker_processes + 8 }}
OLAP 28 different {{ pg_max_worker_processes + 8 }}
CRIT 24 different {{ pg_max_worker_processes + 8 }}
TINY 20 different {{ pg_max_worker_processes + 8 }}
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.4–19 Beta 3 = 24 (dcs); OLAP: PG9.4–19 Beta 3 = 28 (dcs); CRIT: PG9.4–19 Beta 3 = 24 (dcs); TINY: PG9.4–19 Beta 3 = 20 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The template expression adds worker headroom above its profile variable, likely reserving slots for extensions, replication, and parallel work; the exact capacity model needs maintainer confirmation.

Common pitfalls

  • Treating max_worker_processes as reserved capacity rather than an upper bound shared with other work.
  • Ignoring that parallel plans multiply CPU, I/O, and work_mem-limited nodes.
  • Benchmarking one query without concurrent worker contention.
  • Assuming planned workers will always be launched at execution time.

Related parameters

max_parallel_workers · max_parallel_workers_per_gather · max_parallel_maintenance_workers · max_logical_replication_workers · max_wal_senders

References

12.35 - min_dynamic_shared_memory

min_dynamic_shared_memory — Amount of dynamic shared memory reserved at startup. Observed in PG14–19 Beta 3; its last measured boot default is 0 B in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Amount of dynamic shared memory reserved at startup.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit ValueMB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value0
0 B

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 84b1c63ad418 — Preallocate some DSM space at startup.
Commit date 2020-07-31
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 0 MB 0 B

How it works

min_dynamic_shared_memory preallocates real memory at server start for parallel-query dynamic shared memory. It is a reserved pool, not a maximum and not an estimate of cache size.

When the pool is insufficient, parallel queries can still allocate temporary dynamic shared memory through dynamic_shared_memory_type, with additional operating-system allocation overhead.

Startup allocation joins the main shared-memory region and can benefit from huge pages where supported. Reserving too much consumes memory even when parallel work is absent. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave 0 unless repeated parallel-query startup shows measurable dynamic-shared-memory allocation overhead. Any nonzero value is real resident startup memory, so include it in the cluster memory budget even when no parallel query runs.
OLAP Preallocation can reduce temporary DSM setup overhead for frequent concurrent parallel queries. Measure DSM allocation latency and pool use, then reserve only a justified floor; exhaustion still falls back to dynamic allocation.
Small nodes Keep 0 or a small measured reservation. Do not convert speculative future parallel demand into permanently allocated memory on a constrained host.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating min_dynamic_shared_memory as a maximum instead of a real preallocated floor.
  • Assuming parallel queries fail when the reserved pool is exhausted; PostgreSQL can allocate additional dynamic segments.
  • Reserving memory that remains committed even when parallel work is absent.
  • Ignoring dynamic_shared_memory_type, huge-page behavior, and the required restart.

Related parameters

dynamic_shared_memory_type · huge_pages · max_parallel_workers · max_parallel_workers_per_gather · shared_buffers

References

12.36 - multixact_member_buffers

multixact_member_buffers — Sets the size of the dedicated buffer pool used for the MultiXact member cache. Observed in PG17–19 Beta 3; its last measured boot default is 256 KiB (32 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size of the dedicated buffer pool used for the MultiXact member cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value16 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value32
256 KiB (32 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 53c2a97a9266 — Improve performance of subsystems on top of SLRU
Commit date 2024-02-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 32 8kB 256 KiB (32 × 8kB)

How it works

multixact_member_buffers allocates a dedicated shared buffer pool for pg_multixact/members, which caches MultiXact member entries. This is real startup shared memory, not a planner estimate.

The configured block count is allocated at server start. The unit is BLCKSZ blocks, normally 8kB.

A larger cache can reduce SLRU read/write churn for unusually heavy use of the underlying feature, but it permanently consumes shared memory and does not increase the feature’s logical capacity. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave multixact_member_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.
OLAP Analytical workload labels alone do not justify changing multixact_member_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.
Small nodes Keep multixact_member_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing multixact_member_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

multixact_offset_buffers · shared_buffers · max_locks_per_transaction

References

12.37 - multixact_offset_buffers

multixact_offset_buffers — Sets the size of the dedicated buffer pool used for the MultiXact offset cache. Observed in PG17–19 Beta 3; its last measured boot default is 128 KiB (16 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size of the dedicated buffer pool used for the MultiXact offset cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value16 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value16
128 KiB (16 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 53c2a97a9266 — Improve performance of subsystems on top of SLRU
Commit date 2024-02-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

How it works

multixact_offset_buffers allocates a dedicated shared buffer pool for pg_multixact/offsets, which caches MultiXact offsets. This is real startup shared memory, not a planner estimate.

The configured block count is allocated at server start. The unit is BLCKSZ blocks, normally 8kB.

A larger cache can reduce SLRU read/write churn for unusually heavy use of the underlying feature, but it permanently consumes shared memory and does not increase the feature’s logical capacity. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave multixact_offset_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.
OLAP Analytical workload labels alone do not justify changing multixact_offset_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.
Small nodes Keep multixact_offset_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing multixact_offset_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

multixact_member_buffers · shared_buffers · max_locks_per_transaction

References

12.38 - notify_buffers

notify_buffers — Sets the size of the dedicated buffer pool used for the LISTEN/NOTIFY message cache. Observed in PG17–19 Beta 3; its last measured boot default is 128 KiB (16 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size of the dedicated buffer pool used for the LISTEN/NOTIFY message cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value16 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value16
128 KiB (16 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 53c2a97a9266 — Improve performance of subsystems on top of SLRU
Commit date 2024-02-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

How it works

notify_buffers allocates a dedicated shared buffer pool for pg_notify, which caches LISTEN/NOTIFY queue pages. This is real startup shared memory, not a planner estimate.

The configured block count is allocated at server start. The unit is BLCKSZ blocks, normally 8kB.

A larger cache can reduce SLRU read/write churn for unusually heavy use of the underlying feature, but it permanently consumes shared memory and does not increase the feature’s logical capacity. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave notify_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.
OLAP Analytical workload labels alone do not justify changing notify_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.
Small nodes Keep notify_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing notify_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

max_notify_queue_pages · shared_buffers · track_activities

References

12.39 - old_snapshot_threshold

old_snapshot_threshold — Time before a snapshot is too old to read pages changed after the snapshot was taken. Observed in PG9.6–16; its last measured boot default is -1 min in PG16, with postmaster context. It was removed in PG17.
Note

Fact — official short description: “Time before a snapshot is too old to read pages changed after the snapshot was taken.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Valuemin
Raw unit
Range Value-1 – 86400
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Asynchronous Behavior
Upstream classification
Latest boot value Value-1
-1 min

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–16
Removed in PG17
Introduction commit 848ef42bb8c7 — Add the “snapshot too old” feature
Commit date 2016-04-08
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–16 -1 min -1 min

How it works

old_snapshot_threshold, available through PG16 and removed in PG17, marked snapshots as too old after a configured time so page pruning could proceed more aggressively. A later read could fail with snapshot-too-old rather than return a historical page image.

It was not a transaction timeout: the transaction could continue until it touched data whose old versions had been removed. The feature required startup-time tracking overhead even before a failure appeared.

It did not replace vacuum discipline or prevent all bloat. Because the feature was removed, migration must not carry the parameter into PG17+ and applications must not depend on its error behavior. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune old_snapshot_threshold on current PostgreSQL: remove it from upgrade targets and use the current replacement behavior described above. Retain it only when reproducing the historical version.
OLAP Do not carry old_snapshot_threshold into a modern analytical cluster. Benchmark the supported current mechanisms instead of trying to emulate a removed implementation detail.
Small nodes Delete old_snapshot_threshold during version migration; an unknown-parameter startup failure is more likely than a benefit. Historical test instances should keep the old upstream default.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG16; 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: PG9.6–16 unmodified; OLAP: PG9.6–16 unmodified; CRIT: PG9.6–16 unmodified; TINY: PG9.6–16 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing old_snapshot_threshold without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

vacuum_defer_cleanup_age · autovacuum · hot_standby_feedback · idle_in_transaction_session_timeout

References

12.40 - parallel_leader_participation

parallel_leader_participation — Controls whether Gather and Gather Merge also run subplans. Observed in PG11–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Controls whether Gather and Gather Merge also run subplans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Worker Processes
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG11
Present in PG11–19 Beta 3
Removed in No
Introduction commit e5253fdc4f5f — Add parallel_leader_participation GUC.
Commit date 2017-11-15
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG11–19 Beta 3 on — on

How it works

parallel_leader_participation controls whether the process above Gather or Gather Merge also runs the parallel subplan while coordinating workers. With it off, the leader focuses on reading worker output.

Leader participation can add useful CPU when result production is expensive, but a leader busy executing the subplan may be slower to consume a large worker result stream.

The value is a planning/execution policy for eligible parallel plans, not an extra worker slot. Its effect depends on tuple volume, Gather versus Gather Merge, worker availability, and where the bottleneck lies. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the default on unless a representative Gather plan shows that the leader is too busy executing the subplan to consume worker tuples promptly. Test off only at session scope and compare first-row latency, total latency, and worker blocking.
OLAP For CPU-heavy subplans, leader participation often adds useful execution capacity; for very large result streams, disabling it can let the leader drain workers sooner. Compare both boolean states on the same plan and concurrency level.
Small nodes This boolean does not add or remove worker slots. Leave it on unless measurements show a result-consumption bottleneck; size worker counts separately with max_parallel_workers_per_gather and the shared pools.

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

  • Treating the boolean as a degree-of-parallelism or worker-count setting.
  • Speaking of a ’larger’ value when the only choices are on and off.
  • Disabling participation without measuring the extra wait before workers produce the first tuples.
  • Enabling participation without checking whether the leader then drains a large worker result stream too slowly.

Related parameters

max_parallel_workers_per_gather · max_parallel_workers · enable_gathermerge · parallel_tuple_cost · parallel_setup_cost

References

12.41 - replacement_sort_tuples

replacement_sort_tuples — Sets the maximum number of tuples to be sorted using replacement selection. Observed in PG9.6–10; its last measured boot default is 150000 in PG10, with user context. It was removed in PG11.
Note

Fact — official short description: “Sets the maximum number of tuples to be sorted using replacement selection.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value150000
150000

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–10
Removed in PG11
Introduction commit 0711803775a3 — Use quicksort, not replacement selection, for external sorting.
Commit date 2016-04-08
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–10 150000 — 150000

How it works

In PG10, replacement_sort_tuples selected when an in-memory sort used replacement selection to produce a long initial run for external merge sorting. It was removed in PG11 with the old replacement-selection path.

The value counted tuples, not bytes, so its memory implications depended on row width and work_mem. It was an algorithm threshold rather than a general sort-memory ceiling.

Modern PostgreSQL does not recognize the parameter. Migration should delete it and tune current sort behavior through work_mem, plan shape, and measured temporary-file use instead. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune replacement_sort_tuples on current PostgreSQL: remove it from upgrade targets and use the current replacement behavior described above. Retain it only when reproducing the historical version.
OLAP Do not carry replacement_sort_tuples into a modern analytical cluster. Benchmark the supported current mechanisms instead of trying to emulate a removed implementation detail.
Small nodes Delete replacement_sort_tuples during version migration; an unknown-parameter startup failure is more likely than a benefit. Historical test instances should keep the old upstream default.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG10; 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: PG9.6–10 unmodified; OLAP: PG9.6–10 unmodified; CRIT: PG9.6–10 unmodified; TINY: PG9.6–10 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing replacement_sort_tuples without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

work_mem · temp_file_limit · enable_sort · trace_sort · log_temp_files

References

12.42 - serializable_buffers

serializable_buffers — Sets the size of the dedicated buffer pool used for the serializable transaction cache. Observed in PG17–19 Beta 3; its last measured boot default is 256 KiB (32 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size of the dedicated buffer pool used for the serializable transaction cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value16 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value32
256 KiB (32 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 53c2a97a9266 — Improve performance of subsystems on top of SLRU
Commit date 2024-02-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 32 8kB 256 KiB (32 × 8kB)

How it works

serializable_buffers allocates a dedicated shared buffer pool for pg_serial, which caches serializable-transaction state. This is real startup shared memory, not a planner estimate.

The configured block count is allocated at server start. The unit is BLCKSZ blocks, normally 8kB.

A larger cache can reduce SLRU read/write churn for unusually heavy use of the underlying feature, but it permanently consumes shared memory and does not increase the feature’s logical capacity. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave serializable_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.
OLAP Analytical workload labels alone do not justify changing serializable_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.
Small nodes Keep serializable_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing serializable_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

shared_buffers · max_connections · max_pred_locks_per_transaction

References

12.43 - shared_buffers

shared_buffers — Sets the number of shared memory buffers used by the server. Observed in PG9.0–19 Beta 3; its last measured boot default is 128 MiB (16384 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the number of shared memory buffers used by the server.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value16 – 1073741823
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value16384
128 MiB (16384 × 8kB)

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–14 1024 8kB 8 MiB (1024 × 8kB)
PG15–19 Beta 3 16384 8kB 128 MiB (16384 × 8kB)

How it works

shared_buffers allocates PostgreSQL’s real shared buffer cache at server start. Pages cached here are PostgreSQL-managed and coexist with the operating system page cache; the setting is not merely a planner estimate.

The PG10-14 Docker boot value in this catalog is 8MB while PG15-18 report 128MB, reflecting historical initdb/container defaults rather than a universal hardware recommendation. The official guidance treats about 25% of RAM as a starting point for a dedicated server and rarely expects more than 40% to help.

A larger cache changes checkpoint and WAL pressure, often requiring a larger max_wal_size, and leaves less memory for backend processes, work_mem, maintenance, extensions, and the OS. Buffer allocation uses BLCKSZ units, normally 8kB. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Change shared_buffers only after identifying the corresponding resource bottleneck under concurrency. Budget total memory, I/O, disk, or kernel capacity rather than optimizing one process in isolation.
OLAP Benchmark shared_buffers with representative bulk and scan phases. Include sustained throughput, spill/writeback, and interference with other sessions, not only one operation’s elapsed time.
Small nodes Keep shared_buffers conservative on a small host and prefer the upstream default when evidence is weak. A setting copied from a large server can consume a disproportionate share of resources.

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 8192MB different {{ pg_shared_buffers }}MB
OLAP 8192MB different {{ pg_shared_buffers }}MB
CRIT 8192MB different {{ pg_shared_buffers }}MB
TINY 8192MB different {{ pg_shared_buffers }}MB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 8192MB (dcs); OLAP: PG9.0–19 Beta 3 = 8192MB (dcs); CRIT: PG9.0–19 Beta 3 = 8192MB (dcs); TINY: PG9.0–19 Beta 3 = 8192MB (dcs). Advice, pending human review — Editorial inference, pending maintainer review: Pigsty deliberately parameterizes real shared-buffer allocation instead of hard-coding the fixture’s 8192MB; the published rationale must reference the host-memory sizing formula, not present 8192MB as a universal default.

Common pitfalls

  • Changing shared_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

effective_cache_size · work_mem · max_wal_size · huge_pages · checkpoint_completion_target · wal_buffers

References

12.44 - shared_memory_type

shared_memory_type — Selects the shared memory implementation used for the main shared memory region. Observed in PG12–19 Beta 3; its last measured boot default is mmap in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Selects the shared memory implementation used for the main shared memory region.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuesysv, mmap
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Valuemmap
mmap

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit f1bebef60ec8 — Add shared_memory_type GUC.
Commit date 2019-02-03
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 mmap — mmap

How it works

shared_memory_type selects the operating-system mechanism for PostgreSQL’s main shared-memory region, including shared_buffers and other fixed shared state. It does not set the region’s size.

Supported enum values and the first-supported boot default are platform dependent. The Docker/Linux catalog reports mmap; Windows has its own implementation, and sysv can require nondefault kernel limits for large allocations.

On Linux, explicit huge_pages support requires mmap. This parameter is distinct from dynamic_shared_memory_type, which governs temporary dynamic segments used by parallel query and extensions. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the first supported platform default; on Linux that is normally mmap and is required for PostgreSQL’s explicit huge-page support. Use sysv only for a verified compatibility need and provision its kernel limits before restart.
OLAP Large shared_buffers increases the importance of reliable main-region allocation, but workload label does not select the API. Validate startup, huge pages, failover, and service limits on the target operating system rather than benchmarking storage throughput.
Small nodes Keep the platform default. Changing the implementation does not reduce the configured shared-memory size and can add kernel-limit or portability failures.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the Linux-Docker mmap boot value as a portable default for every operating system.
  • Selecting sysv without raising the System V shared-memory kernel limits needed for the main region.
  • Forgetting that explicit huge pages on Linux require shared_memory_type=mmap.
  • Expecting the parameter to resize shared_buffers or other shared allocations.

Related parameters

dynamic_shared_memory_type · shared_buffers · huge_pages · huge_page_size · min_dynamic_shared_memory

References

12.45 - subtransaction_buffers

subtransaction_buffers — Sets the size of the dedicated buffer pool used for the subtransaction cache. Observed in PG17–19 Beta 3; its last measured boot default is 0 B (0 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size of the dedicated buffer pool used for the subtransaction cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value0 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value0
0 B (0 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 53c2a97a9266 — Improve performance of subsystems on top of SLRU
Commit date 2024-02-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 0 8kB 0 B (0 × 8kB)

How it works

subtransaction_buffers allocates a dedicated shared buffer pool for pg_subtrans, which caches subtransaction parent mappings. This is real startup shared memory, not a planner estimate.

Zero is an automatic-sizing request: PostgreSQL derives shared_buffers/512 and clamps it between 16 and 1024 blocks. The unit is BLCKSZ blocks, normally 8kB.

A larger cache can reduce SLRU read/write churn for unusually heavy use of the underlying feature, but it permanently consumes shared memory and does not increase the feature’s logical capacity. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave subtransaction_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.
OLAP Analytical workload labels alone do not justify changing subtransaction_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.
Small nodes Keep subtransaction_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing subtransaction_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

transaction_buffers · shared_buffers · max_locks_per_transaction

References

12.46 - temp_buffers

A per-session, lazily allocated buffer ceiling used only when accessing temporary tables.
Note

Fact — official short description: “Sets the maximum number of temporary buffers used by each session.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value8kB
Raw unit
Range Value100 – 1073741823
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value1024
8 MiB (1024 × 8kB)

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 1024 8kB 8 MiB (1024 × 8kB)

How it works

temp_buffers controls session-local buffers for temporary-table access. It does not govern sort or hash spill files created by ordinary query execution.

A session can change the value only before its first use of a temporary table; later SET commands have no effect for that session. Buffers are allocated on demand up to the ceiling.

An unused increase still creates buffer-descriptor overhead, while each buffer actually used consumes one database block, normally 8kB. Aggregate usage therefore depends on the number of sessions actively using temporary tables.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave the default unless the application demonstrably uses sizable temporary tables. Prefer scoped changes in the sessions that create them and set the value before first access.
OLAP Raise it only for workflows that use PostgreSQL temporary tables; work_mem, not temp_buffers, is the primary control for sort and hash operations. Include session concurrency in the budget.
Small nodes Keep the default and avoid globally increasing per-session ceilings. Temporary-table-heavy jobs should be isolated or adjusted locally.

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

  • Confusing temporary-table buffers with sort and hash temporary files.
  • Issuing SET after the session has already accessed a temporary table.
  • Ignoring multiplication across many sessions actively using temporary tables.
  • Assuming a large value is fully allocated immediately; PostgreSQL grows usage on demand, though descriptor overhead remains.

Related parameters

work_mem · temp_file_limit · temp_tablespaces · max_connections · log_temp_files

References

12.47 - temp_file_limit

A per-process safety limit on disk space consumed at one time by executor temporary files.
Note

Fact — official short description: “Limits the total size of all temporary files used by each process.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit ValuekB
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Disk
Upstream classification
Latest boot value Value-1
-1 kB

Lifecycle

Fact Value
First observed PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit 23e5b16c71f2 — Add temp_file_limit GUC parameter to constrain temporary file space usage.
Commit date 2011-07-17
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.2–19 Beta 3 -1 kB -1 kB

How it works

temp_file_limit limits the total instantaneous size of temporary files owned by one PostgreSQL process, including sort and hash spill files and storage for held cursors. Exceeding it cancels the transaction.

The limit is per process, not cluster-wide, so concurrent backends and parallel workers can collectively consume multiples of it. The default -1 means no limit.

Explicit temporary-table storage is excluded from this limit. log_temp_files and pg_stat_database.temp_bytes observe related temporary-file activity but do not change the enforcement boundary.

Tuning advice

Tip

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

Workload Guidance
OLTP Use a finite guardrail sized from filesystem headroom and worst-case concurrent spillers. Monitor temp_bytes and log_temp_files so the cap blocks pathological queries rather than routine bursts.
OLAP Allow a larger but still finite budget for known large joins and sorts, and coordinate it with query concurrency and parallelism. Test cancellation behavior before relying on the limit in production.
Small nodes Choose a modest fraction of the data filesystem and preserve emergency free space. Pair a lower limit with conservative work_mem and query timeouts.

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 5GB different {{ ([pg_size_twentieth, 200])|min }}GB
OLAP 20GB different {{ ([pg_size_twentieth * 4, 2000])|min }}GB
CRIT 5GB different {{ ([pg_size_twentieth, 200])|min }}GB
TINY 5GB different {{ ([pg_size_twentieth, 200])|min }}GB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.2–19 Beta 3 = 5GB (dcs); OLAP: PG9.2–19 Beta 3 = 20GB (dcs); CRIT: PG9.2–19 Beta 3 = 5GB (dcs); TINY: PG9.2–19 Beta 3 = 5GB (dcs). Advice, pending human review — Editorial inference: these values act as process-level circuit breakers while giving analytical spills more room; aggregate multi-process exposure still needs capacity review.

Common pitfalls

  • Treating a per-process limit as a cluster-wide disk cap.
  • Expecting it to constrain explicit temporary tables, which are excluded.
  • Leaving -1 on a filesystem where one runaway query can exhaust shared storage.
  • Setting the cap below normal spill sizes and discovering through transaction cancellations.

Related parameters

work_mem · hash_mem_multiplier · log_temp_files · temp_tablespaces · max_parallel_workers_per_gather

References

12.48 - timing_clock_source

timing_clock_source — Controls the clock source used for collecting timing measurements. Observed in PG19 Beta 3; its last measured boot default is auto in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Controls the clock source used for collecting timing measurements.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueauto, system, tsc
— for non-enum types
Category ValueResource Usage / Time
Upstream classification
Latest boot value Valueauto
auto

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit 294520c44487 — instrumentation: Use Time-Stamp Counter on x86-64 to lower overhead
Commit date 2026-04-07
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 auto — auto

How it works

PostgreSQL describes timing_clock_source as follows: “Controls the clock source used for collecting timing measurements.” It can be changed at run time only by a superuser or a role with an appropriate SET grant. 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.

auto selects a supported x86-64 Time-Stamp Counter when appropriate and otherwise uses the operating-system monotonic clock; system forces the OS clock and tsc requests CPU instructions such as RDTSC/RDTSCP. The faster source lowers EXPLAIN ANALYZE measurement overhead, but emulated or unstable TSC behavior can be slower or invalid.

Read it together with track_io_timing, track_wal_io_timing, log_executor_stats, compute_query_id. 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

Tip

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

Workload Guidance
OLTP Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.
OLAP Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.
Small nodes Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism.

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: 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 timing_clock_source as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports superuser 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

track_io_timing · track_wal_io_timing · log_executor_stats · compute_query_id

References

12.49 - transaction_buffers

transaction_buffers — Sets the size of the dedicated buffer pool used for the transaction status cache. Observed in PG17–19 Beta 3; its last measured boot default is 0 B (0 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size of the dedicated buffer pool used for the transaction status cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value0 – 131072
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value0
0 B (0 × 8kB)

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 53c2a97a9266 — Improve performance of subsystems on top of SLRU
Commit date 2024-02-28
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 0 8kB 0 B (0 × 8kB)

How it works

transaction_buffers allocates a dedicated shared buffer pool for pg_xact, which caches transaction commit-status pages. This is real startup shared memory, not a planner estimate.

Zero is an automatic-sizing request: PostgreSQL derives shared_buffers/512 and clamps it between 16 and 1024 blocks. The unit is BLCKSZ blocks, normally 8kB.

A larger cache can reduce SLRU read/write churn for unusually heavy use of the underlying feature, but it permanently consumes shared memory and does not increase the feature’s logical capacity. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Leave transaction_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.
OLAP Analytical workload labels alone do not justify changing transaction_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.
Small nodes Keep transaction_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing transaction_buffers without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

subtransaction_buffers · shared_buffers · commit_timestamp_buffers

References

12.50 - vacuum_buffer_usage_limit

vacuum_buffer_usage_limit — Sets the buffer pool size for VACUUM, ANALYZE, and autovacuum. Observed in PG16–19 Beta 3; its last measured boot default is 2 MiB in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the buffer pool size for VACUUM, ANALYZE, and autovacuum.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValuekB
Raw unit
Range Value0 – 16777216
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value2048
2 MiB

Lifecycle

Fact Value
First observed PG16
Present in PG16–19 Beta 3
Removed in No
Introduction commit 1cbbee033857 — Add VACUUM/ANALYZE BUFFER_USAGE_LIMIT option
Commit date 2023-04-07
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG16 256 kB 256 KiB
PG17–19 Beta 3 2048 kB 2 MiB

How it works

vacuum_buffer_usage_limit sizes the shared-buffer access-strategy ring used by VACUUM, ANALYZE, and autovacuum. It is not a private memory allocation and does not cap all buffers those operations can ever touch.

A nonzero value is silently capped at one eighth of shared_buffers; zero allows unrestricted shared-buffer use. The ring reduces eviction of unrelated hot pages while permitting repeated reuse during scans.

Larger rings can improve maintenance throughput but can displace more useful cache. VACUUM and ANALYZE can override it per command with BUFFER_USAGE_LIMIT, and the boot default rose from 256kB in PG16 to 2MB in PG17. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Change vacuum_buffer_usage_limit only after identifying the corresponding resource bottleneck under concurrency. Budget total memory, I/O, disk, or kernel capacity rather than optimizing one process in isolation.
OLAP Benchmark vacuum_buffer_usage_limit with representative bulk and scan phases. Include sustained throughput, spill/writeback, and interference with other sessions, not only one operation’s elapsed time.
Small nodes Keep vacuum_buffer_usage_limit conservative on a small host and prefer the upstream default when evidence is weak. A setting copied from a large server can consume a disproportionate share of resources.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing vacuum_buffer_usage_limit without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

shared_buffers · maintenance_work_mem · autovacuum_work_mem · maintenance_io_concurrency · track_io_timing

References

12.51 - work_mem

The per-operation memory budget that determines when sorts and other query workspaces begin spilling to temporary files.
Note

Fact — official short description: “Sets the maximum memory to be used for query workspaces.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValuekB
Raw unit
Range Value64 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueResource Usage / Memory
Upstream classification
Latest boot value Value4096
4 MiB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.3 1024 kB 1 MiB
PG9.4–19 Beta 3 4096 kB 4 MiB

How it works

work_mem is a base limit for each execution operation, not a reservation for an entire query or session. A complex plan can run several sorts or hash operations concurrently, and many sessions can do the same, so aggregate memory can be many times the configured value.

Sorts used by ORDER BY, DISTINCT, and merge joins generally use work_mem before spilling. Hash joins, hash aggregation, memoize nodes, and hash-based IN processing derive their limit from work_mem multiplied by hash_mem_multiplier.

Parallel query further multiplies exposure because resource limits such as work_mem apply to individual worker processes. The setting is therefore best understood together with plan shape, parallelism, and active-query concurrency.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the cluster-wide value conservative and size it against peak active backends, not the connection limit alone. Use transaction-, role-, or database-scoped overrides for known reporting jobs after checking actual spill behavior.
OLAP Larger values can remove expensive sort and hash spills, but raise them with an explicit concurrency budget. Compare EXPLAIN (ANALYZE, BUFFERS) results and temporary-file statistics before and after each change.
Small nodes Prefer the default or a low tens-of-megabytes setting and leave headroom for shared buffers, autovacuum, the operating system, and other processes. A single globally generous value is risky on a small host.

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 64MB different {{ pg_workmem }}MB
OLAP 64MB different {{ pg_workmem }}MB
CRIT 64MB different {{ pg_workmem }}MB
TINY 32MB different {{ pg_workmem }}MB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 64MB (dcs); OLAP: PG9.0–19 Beta 3 = 64MB (dcs); CRIT: PG9.0–19 Beta 3 = 64MB (dcs); TINY: PG9.0–19 Beta 3 = 32MB (dcs). Advice, pending human review — Editorial inference: the formula is intended to trade spill frequency against worst-case concurrent memory.

Common pitfalls

  • Treating work_mem as a per-connection or per-query cap; it is normally available to each eligible plan operation.
  • Ignoring parallel workers, which can each receive their own work_mem budget.
  • Raising work_mem to fix hash spills without accounting for hash_mem_multiplier.
  • Assuming temporary-table buffers are controlled here; those are governed by temp_buffers.

Related parameters

hash_mem_multiplier · temp_file_limit · log_temp_files · max_connections · max_parallel_workers_per_gather

References

13 - Statistics

Complete dossiers for 14 core PostgreSQL settings in Statistics.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

13.1 - compute_query_id

compute_query_id — Enables in-core computation of query identifiers. Observed in PG14–19 Beta 3; its last measured boot default is auto in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables in-core computation of query identifiers.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueauto, regress, on, off
— for non-enum types
Category ValueStatistics / Monitoring
Upstream classification
Latest boot value Valueauto
auto

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 5fd9dfa5f50e — Move pg_stat_statements query jumbling to core.
Commit date 2021-04-07
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 auto — auto

How it works

compute_query_id controls PostgreSQL’s in-core normalized query identifier. The identifier can appear in pg_stat_activity, EXPLAIN, and logs, and is required by pg_stat_statements unless another module computes one.

auto lets a module request in-core computation, on always computes, off prevents it, and regress behaves like auto while suppressing the ID in EXPLAIN for stable regression output.

Only one provider should compute the identifier. An extension with an alternative algorithm must disable the in-core implementation and detect conflicts rather than silently publishing two incompatible IDs. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Use auto when pg_stat_statements or another module should request the in-core identifier, and use on only when logs, EXPLAIN, or monitoring require IDs without such a module. Measure query-normalization overhead at peak parse/plan rates.
OLAP auto or on can make long analytical statements easier to correlate across pg_stat_activity, EXPLAIN, and logs. The cost is query-tree normalization and hashing, not clock reads; compare planning CPU on workloads with very large statements.
Small nodes Keep auto unless an external query-ID provider requires off. regress is for stable regression output, not a smaller production setting, and off can remove IDs required by pg_stat_statements.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Enabling the in-core provider while an extension also attempts to compute a different query identifier.
  • Setting off and silently losing IDs required by pg_stat_statements, logs, or correlation tooling.
  • Treating regress as a production optimization rather than a test-output mode.
  • Using query IDs as stable cross-major-version or cryptographic identifiers.

Related parameters

track_activities · shared_preload_libraries · log_line_prefix · track_activity_query_size

References

13.2 - log_executor_stats

log_executor_stats — Writes executor performance statistics to the server log. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Writes executor performance statistics to the server log.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Monitoring
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_executor_stats emits executor-stage resource usage for every query using a crude getrusage-style profiler. Output goes to the server log and is intended for short diagnostic sessions.

log_statement_stats reports the total statement, while parser, planner, and executor switches report individual phases. The total switch cannot be enabled together with any per-phase switch.

This is synchronous diagnostic logging rather than the cumulative statistics system. Volume and formatting make it unsuitable as routine production telemetry. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not enable log_executor_stats as normal OLTP tuning. Use it briefly on an isolated reproduction or one controlled session, collect the needed log, then disable it.
OLAP For a specific analytical statement, EXPLAIN (ANALYZE, BUFFERS) and cumulative views are usually more actionable than cluster-wide log_executor_stats. Scope any use and budget log volume.
Small nodes Leave log_executor_stats=off. A small host is especially vulnerable to diagnostic log I/O and storage exhaustion.

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

  • Enabling or enlarging log_executor_stats without measuring collection and observation overhead.
  • Confusing collection semantics with a performance-control or I/O-control setting.
  • Assuming all statistics are immediately current inside a long transaction.
  • Collecting sensitive query text or identifiers without matching access and retention policy.

Related parameters

log_statement_stats · log_parser_stats · log_planner_stats · log_min_duration_statement · track_io_timing

References

13.3 - log_parser_stats

log_parser_stats — Writes parser performance statistics to the server log. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Writes parser performance statistics to the server log.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Monitoring
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_parser_stats emits parser-stage resource usage for every query using a crude getrusage-style profiler. Output goes to the server log and is intended for short diagnostic sessions.

log_statement_stats reports the total statement, while parser, planner, and executor switches report individual phases. The total switch cannot be enabled together with any per-phase switch.

This is synchronous diagnostic logging rather than the cumulative statistics system. Volume and formatting make it unsuitable as routine production telemetry. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not enable log_parser_stats as normal OLTP tuning. Use it briefly on an isolated reproduction or one controlled session, collect the needed log, then disable it.
OLAP For a specific analytical statement, EXPLAIN (ANALYZE, BUFFERS) and cumulative views are usually more actionable than cluster-wide log_parser_stats. Scope any use and budget log volume.
Small nodes Leave log_parser_stats=off. A small host is especially vulnerable to diagnostic log I/O and storage exhaustion.

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

  • Enabling or enlarging log_parser_stats without measuring collection and observation overhead.
  • Confusing collection semantics with a performance-control or I/O-control setting.
  • Assuming all statistics are immediately current inside a long transaction.
  • Collecting sensitive query text or identifiers without matching access and retention policy.

Related parameters

log_statement_stats · log_planner_stats · log_executor_stats · log_min_duration_statement

References

13.4 - log_planner_stats

log_planner_stats — Writes planner performance statistics to the server log. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Writes planner performance statistics to the server log.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Monitoring
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_planner_stats emits planner-stage resource usage for every query using a crude getrusage-style profiler. Output goes to the server log and is intended for short diagnostic sessions.

log_statement_stats reports the total statement, while parser, planner, and executor switches report individual phases. The total switch cannot be enabled together with any per-phase switch.

This is synchronous diagnostic logging rather than the cumulative statistics system. Volume and formatting make it unsuitable as routine production telemetry. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not enable log_planner_stats as normal OLTP tuning. Use it briefly on an isolated reproduction or one controlled session, collect the needed log, then disable it.
OLAP For a specific analytical statement, EXPLAIN (ANALYZE, BUFFERS) and cumulative views are usually more actionable than cluster-wide log_planner_stats. Scope any use and budget log volume.
Small nodes Leave log_planner_stats=off. A small host is especially vulnerable to diagnostic log I/O and storage exhaustion.

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

  • Enabling or enlarging log_planner_stats without measuring collection and observation overhead.
  • Confusing collection semantics with a performance-control or I/O-control setting.
  • Assuming all statistics are immediately current inside a long transaction.
  • Collecting sensitive query text or identifiers without matching access and retention policy.

Related parameters

log_statement_stats · log_parser_stats · log_executor_stats · log_min_duration_statement · join_collapse_limit

References

13.5 - log_statement_stats

log_statement_stats — Writes cumulative performance statistics to the server log. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Writes cumulative performance statistics to the server log.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Monitoring
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

log_statement_stats emits whole-statement resource usage for every query using a crude getrusage-style profiler. Output goes to the server log and is intended for short diagnostic sessions.

log_statement_stats reports the total statement, while parser, planner, and executor switches report individual phases. The total switch cannot be enabled together with any per-phase switch.

This is synchronous diagnostic logging rather than the cumulative statistics system. Volume and formatting make it unsuitable as routine production telemetry. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not enable log_statement_stats as normal OLTP tuning. Use it briefly on an isolated reproduction or one controlled session, collect the needed log, then disable it.
OLAP For a specific analytical statement, EXPLAIN (ANALYZE, BUFFERS) and cumulative views are usually more actionable than cluster-wide log_statement_stats. Scope any use and budget log volume.
Small nodes Leave log_statement_stats=off. A small host is especially vulnerable to diagnostic log I/O and storage exhaustion.

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

  • Enabling or enlarging log_statement_stats without measuring collection and observation overhead.
  • Confusing collection semantics with a performance-control or I/O-control setting.
  • Assuming all statistics are immediately current inside a long transaction.
  • Collecting sensitive query text or identifiers without matching access and retention policy.

Related parameters

log_parser_stats · log_planner_stats · log_executor_stats · log_min_duration_statement · track_functions

References

13.6 - stats_fetch_consistency

stats_fetch_consistency — Sets the consistency of accesses to statistics data. Observed in PG15–19 Beta 3; its last measured boot default is cache in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the consistency of accesses to statistics data.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuenone, cache, snapshot
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Valuecache
cache

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit 5891c7a8ed8f — pgstat: store statistics in shared memory.
Commit date 2022-04-06
Discussion thread 1 · thread 2 · thread 3

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG15–19 Beta 3 cache — cache

How it works

stats_fetch_consistency defines repeat-read behavior for cumulative statistics within one transaction. none refetches each object, cache retains each object after first access, and snapshot materializes all accessible database statistics on first access.

The cache or snapshot lasts until transaction end or pg_stat_clear_snapshot(). Changing the setting inside a transaction discards the current statistics snapshot.

none is efficient for monitoring queries that read each counter once; cache gives stable repeated object reads; snapshot gives a coherent interactive view at higher cost, especially with many objects. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload Guidance
OLTP Use cache for ordinary SQL, none for scrape queries that read each statistic once, and snapshot only for a deliberate coherent inspection. Do not hold a monitoring transaction open indefinitely.
OLAP Large catalogs make snapshot expensive; choose stats_fetch_consistency from the monitoring query’s access pattern rather than workload label.
Small nodes Keep cache unless a simple one-pass collector benefits from none. The setting changes read semantics, not collection accuracy.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Enabling or enlarging stats_fetch_consistency without measuring collection and observation overhead.
  • Confusing collection semantics with a performance-control or I/O-control setting.
  • Assuming all statistics are immediately current inside a long transaction.
  • Collecting sensitive query text or identifiers without matching access and retention policy.

Related parameters

track_counts · track_activities · track_io_timing · track_functions

References

13.7 - stats_temp_directory

stats_temp_directory — Writes temporary statistics files to the specified directory. Observed in PG9.0–14; its last measured boot default is pg_stat_tmp in PG14, with sighup context. It was removed in PG15.
Note

Fact — official short description: “Writes temporary statistics files to the specified directory.”

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 ValueStatistics / Query and Index Statistics Collector
Upstream classification
Latest boot value Valuepg_stat_tmp
pg_stat_tmp

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–14
Removed in PG15
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–14 pg_stat_tmp — pg_stat_tmp

How it works

Through PG14, stats_temp_directory selected where the old statistics collector wrote temporary statistics files. It did not store durable table statistics created by ANALYZE.

A fast local memory-backed directory could reduce collector file I/O, but loss of its temporary contents was expected. Permissions and directory availability still had to permit the server to operate.

PostgreSQL 15 replaced the collector’s file-based architecture with shared-memory cumulative statistics and removed this GUC. PG15+ migrations must delete the setting rather than map it to another directory. Its SIGHUP context allows configuration reload without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune stats_temp_directory on current PostgreSQL: remove it from upgrade targets and use the current replacement behavior described above. Retain it only when reproducing the historical version.
OLAP Do not carry stats_temp_directory into a modern analytical cluster. Benchmark the supported current mechanisms instead of trying to emulate a removed implementation detail.
Small nodes Delete stats_temp_directory during version migration; an unknown-parameter startup failure is more likely than a benefit. Historical test instances should keep the old upstream default.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG14; 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: PG9.0–14 unmodified; OLAP: PG9.0–14 unmodified; CRIT: PG9.0–14 unmodified; TINY: PG9.0–14 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing stats_temp_directory without applying its documented unit and configuration context.
  • Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.
  • Assuming a configured value guarantees operating-system or storage behavior.
  • Failing to retest startup, failover, and workload latency after the change.

Related parameters

stats_fetch_consistency · track_counts · track_activities · data_directory

References

13.8 - track_activities

track_activities — Collects information about executing commands. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Collects information about executing commands.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

track_activities records each session’s current command, query identifier, and timing metadata for pg_stat_activity. Access remains privilege-filtered even when collection is enabled.

Turning it off removes essential live observability but does not terminate or speed up the command itself. The text stored per session is bounded by track_activity_query_size.

The switch can be changed by authorized users, so monitoring should detect sessions reporting disabled activity. It is separate from cumulative counters controlled by track_counts. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep on in production so pg_stat_activity can show the current command, query ID, and timing needed for incident response. Restrict view privileges and size track_activity_query_size separately rather than disabling activity collection to hide text.
OLAP Keep on for long analytical sessions; live phase and wait context is especially valuable during resource contention. If overhead is suspected, measure it explicitly before accepting the observability loss from off.
Small nodes Keep on. The setting is a boolean collection gate, not a buffer size; reduce query-text memory with track_activity_query_size only after preserving enough text for diagnosis.

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

  • Turning it off and losing the current-command evidence needed to diagnose blocking or runaway sessions.
  • Confusing live activity collection with cumulative counters controlled by track_counts.
  • Assuming on makes every session’s query text visible to every role; visibility remains privilege filtered.
  • Ignoring that an authorized session can disable its own activity reporting in the permitted context.

Related parameters

track_activity_query_size · track_counts · compute_query_id · log_line_prefix · log_min_duration_statement

References

13.9 - track_activity_query_size

track_activity_query_size — Sets the size reserved for pg_stat_activity.query, in bytes. Observed in PG9.0–19 Beta 3; its last measured boot default is 1 KiB in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the size reserved for pg_stat_activity.query, in bytes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit ValueB
Raw unit
Range Value100 – 1048576
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Value1024
1 KiB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–10 1024 — 1024
PG11–19 Beta 3 1024 B 1 KiB

How it works

track_activity_query_size reserves real shared memory for the current-query text of every active session shown in pg_stat_activity.query. It is a byte count fixed at server start.

Long statements are truncated to this storage size; increasing it improves incident context but multiplies memory by the number of backend slots, including configured connection capacity.

It does not change log statement length, pg_stat_statements query-text storage, or application payload limits. Query identifiers can correlate truncated text with other telemetry when compute_query_id is available. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose enough bytes to retain diagnostically useful SQL, then budget approximately that storage across all backend slots rather than active queries alone. Increasing it is a startup shared-memory decision and requires a restart.
OLAP Long generated SQL often needs more than 1kB to remain identifiable. Compare truncation frequency and incident needs against the value multiplied by MaxBackends; this setting incurs memory, not repeated clock-read overhead.
Small nodes Keep the smallest value that preserves useful statement identity. Do not copy a 32kB critical-profile value without multiplying it across connection and worker slots on the small host.

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 8192 different 8192
OLAP 8192 different 8192
CRIT 32768 different 32768
TINY 8192 different 8192
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 8192 (dcs); OLAP: PG9.0–19 Beta 3 = 8192 (dcs); CRIT: PG9.0–19 Beta 3 = 32768 (dcs); TINY: PG9.0–19 Beta 3 = 8192 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The templates retain more query text than upstream for operations, with a larger critical-profile value intended to preserve full diagnostic context.

Common pitfalls

  • Treating the value as memory only for currently active queries instead of storage reserved across backend slots.
  • Forgetting that the unit is bytes and multibyte query text can contain fewer characters than the byte count suggests.
  • Expecting it to change log statement length or pg_stat_statements query-text storage.
  • Changing it without the required server restart.

Related parameters

track_activities · max_connections · compute_query_id · log_line_prefix · shared_buffers

References

13.10 - track_cost_delay_timing

track_cost_delay_timing — Collects timing statistics for cost-based vacuum delay. Observed in PG18–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Collects timing statistics for cost-based vacuum delay.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit bb8dff9995f2 — Add cost-based vacuum delay time to progress views.
Commit date 2025-02-11
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 off — off

How it works

track_cost_delay_timing measures time actually spent in cost-based VACUUM and ANALYZE delay. The result appears in progress views, verbose command output, and eligible autovacuum logs.

Collection repeatedly reads the operating-system clock and can have platform-dependent overhead. It does not enable vacuum delay or alter vacuum_cost_* policy.

The metric helps distinguish useful work from intentional throttling. pg_test_timing can measure clock-read overhead before enabling it widely. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable it when operators need to distinguish VACUUM or ANALYZE work from intentional cost-delay sleep. Measure clock-read overhead with pg_test_timing and under autovacuum load; it is a boolean and does not size or enable cost-based delay itself.
OLAP It is useful when long maintenance overlaps analytical work and throttle time must be quantified. Compare reported delay time with maintenance duration and foreground latency, then keep it on only if the evidence is used operationally.
Small nodes Leave off unless vacuum-delay diagnostics are needed and clock reads are cheap on the platform. Enabling it does not make maintenance faster or slower by policy; vacuum_cost_* settings remain separate.

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 on different 'on'
CRIT on different 'on'
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 = on (dcs); CRIT: PG18–19 Beta 3 = on (dcs); TINY: PG18–19 Beta 3 unmodified. Advice, pending human review — Editorial inference, pending maintainer review: The OLAP/crit-only switch is intended to expose time spent in vacuum/analyze cost delays where long maintenance or critical observability justifies clock overhead.

Common pitfalls

  • Assuming the switch enables cost-based vacuum delay rather than only timing existing delay.
  • Ignoring platform-dependent clock-read overhead instead of measuring with pg_test_timing.
  • Looking for the metric without enabling the relevant progress, verbose, or autovacuum-log output.
  • Treating the boolean as a duration or buffer-size parameter.

Related parameters

vacuum_cost_delay · autovacuum_vacuum_cost_delay · log_autovacuum_min_duration · track_io_timing · vacuum_buffer_usage_limit

References

13.11 - track_counts

track_counts — Collects statistics on database activity. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Collects statistics on database activity.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

track_counts feeds PostgreSQL’s cumulative database, table, and index activity counters. Autovacuum depends on these counts to decide when tables need vacuum and analyze.

Turning it off removes planner and maintenance telemetry and can prevent normal autovacuum triggering. It does not reset already stored counters by itself.

The statistics are exposed through pg_stat views under snapshot rules controlled by stats_fetch_consistency. Collection is server-wide, while visibility remains privilege controlled. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep track_counts=on; normal autovacuum and capacity monitoring rely on it. Disable only in a controlled experiment that does not represent a production configuration.
OLAP Keep track_counts=on for maintenance decisions even if queries are batch oriented. Counter collection is more valuable than the small saving from losing autovacuum inputs.
Small nodes Keep track_counts=on. Small systems still need autovacuum and table-activity visibility.

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

  • Enabling or enlarging track_counts without measuring collection and observation overhead.
  • Confusing collection semantics with a performance-control or I/O-control setting.
  • Assuming all statistics are immediately current inside a long transaction.
  • Collecting sensitive query text or identifiers without matching access and retention policy.

Related parameters

autovacuum · stats_fetch_consistency · track_activities · default_statistics_target · log_autovacuum_min_duration

References

13.12 - track_functions

track_functions — Collects function-level statistics on database activity. Observed in PG9.0–19 Beta 3; its last measured boot default is none in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Collects function-level statistics on database activity.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuenone, pl, all
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Valuenone
none

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 none — none

How it works

track_functions counts calls and execution time for procedural functions with pl, and also SQL/C functions with all. none disables function-level cumulative statistics.

Simple SQL-language functions that the planner inlines disappear into the caller and are not tracked regardless of this setting. Nested function time is reported through the statistics system’s own total/self accounting.

all broadens instrumentation and can add overhead on function-heavy workloads. The counters are cumulative and observed through pg_stat_user_functions or related views. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep none unless function-level call counts and timing answer a concrete production question. Use pl to limit instrumentation to procedural languages, or all only after measuring overhead on function-heavy traffic.
OLAP Enable pl or all for a bounded analysis when time inside functions must be separated from caller time. Remember that simple SQL functions may be inlined and remain invisible, so absence from the view is not proof of no execution.
Small nodes Prefer none or a short scoped diagnostic interval. The enum controls instrumentation breadth; it is not a numeric sampling rate, and all can add disproportionate overhead on a CPU-limited host.

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 all different all
OLAP all different all
CRIT all different all
TINY all different all
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = all (dcs); OLAP: PG9.0–19 Beta 3 = all (dcs); CRIT: PG9.0–19 Beta 3 = all (dcs); TINY: PG9.0–19 Beta 3 = all (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The explicit all setting maximizes function-level observability across every profile, accepting instrumentation overhead and the SQL-inlining blind spot.

Common pitfalls

  • Expecting inlined SQL-language functions to appear in function statistics.
  • Enabling all cluster-wide without measuring instrumentation overhead on function-heavy workloads.
  • Reading cumulative total and self time without accounting for nested calls and snapshot behavior.
  • Treating none, pl, and all as levels of sampling rather than different instrumentation scopes.

Related parameters

track_counts · stats_fetch_consistency · compute_query_id · jit_expressions · log_statement_stats

References

13.13 - track_io_timing

track_io_timing — Collects timing statistics for database I/O activity. Observed in PG9.2–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Collects timing statistics for database I/O activity.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.2
Present in PG9.2–19 Beta 3
Removed in No
Introduction commit 309c64745ea1 — Rename track_iotiming GUC to track_io_timing.
Commit date 2012-04-29
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.2–19 Beta 3 off — off

How it works

track_io_timing measures database I/O wait time outside the WAL object. It populates pg_stat_database, pg_stat_io, pg_stat_get_backend_io(), EXPLAIN with BUFFERS, maintenance output, and supporting extensions.

The setting repeatedly reads the operating-system clock; overhead is platform dependent and measurable with pg_test_timing. It records elapsed wait, not device service time in isolation.

WAL I/O timing is controlled separately by track_wal_io_timing. Enabling timing adds observability but does not make I/O asynchronous or change planner costs. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable it when database I/O wait time is needed for pg_stat_io, EXPLAIN with BUFFERS, or incident analysis. Measure clock-read overhead with pg_test_timing and at peak statement rates; Pigsty’s on value is an observability choice, not a throughput tuning value.
OLAP Long scans and spills make relation and temporary-file timing valuable. Keep it on when those counters drive diagnosis, but compare execution overhead and distinguish elapsed waits from device-only service time.
Small nodes Use on only when the platform’s clock-read cost is acceptable and the measurements are consumed. The boolean has no conservative numeric size; off removes timing but does not remove I/O itself.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.2–19 Beta 3 = on (dcs); OLAP: PG9.2–19 Beta 3 = on (dcs); CRIT: PG9.2–19 Beta 3 = on (dcs); TINY: PG9.2–19 Beta 3 = on (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The explicit on setting follows the source comment’s goal of collecting I/O statistics across all profiles, accepting platform-dependent clock overhead.

Common pitfalls

  • Treating measured wait time as isolated device service time without queueing or scheduling effects.
  • Expecting the switch to make I/O asynchronous or change planner cost estimates.
  • Assuming it includes WAL timing, which is controlled by track_wal_io_timing.
  • Enabling it without measuring clock-read overhead on the actual platform.

Related parameters

track_wal_io_timing · track_counts · stats_fetch_consistency · effective_io_concurrency · compute_query_id

References

13.14 - track_wal_io_timing

track_wal_io_timing — Collects timing statistics for WAL I/O activity. Observed in PG14–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Collects timing statistics for WAL I/O activity.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueStatistics / Cumulative Query and Index Statistics
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit ff99918c625a — Track total amounts of times spent writing and syncing WAL data to disk.
Commit date 2021-03-09
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 off — off

How it works

track_wal_io_timing measures wait time for WAL I/O and exposes it under the wal object in pg_stat_io and pg_stat_get_backend_io(). It is independent of ordinary database I/O timing.

Collection repeatedly reads the operating-system clock and can add platform-dependent overhead. pg_test_timing measures clock-read cost, while workload tests reveal aggregate impact.

It does not change wal_sync_method, durability, or WAL throughput. Pairing it with track_io_timing separates WAL waits from relation and temporary-file I/O. Its superuser context permits an authorized session change without a server restart.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable it when WAL write and sync waits must be separated from relation I/O during commit-latency analysis. Measure platform clock overhead and correlate the counters with synchronous_commit, wal_sync_method, and storage behavior.
OLAP Read-heavy analytics may gain little from WAL timing, while bulk loads and refresh jobs can benefit substantially. Enable it for the write phases that use the evidence rather than because the workload is labeled OLAP.
Small nodes Keep off unless WAL latency is an active diagnostic need and clock reads are inexpensive. Pair it with track_io_timing only when both WAL and non-WAL wait separation is useful.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Expecting WAL timing to include relation and temporary-file I/O measured by track_io_timing.
  • Treating elapsed WAL waits as pure device service time.
  • Assuming the switch changes durability, wal_sync_method, or WAL throughput.
  • Enabling it without measuring clock-read overhead on the production platform.

Related parameters

track_io_timing · wal_sync_method · synchronous_commit · track_counts · stats_fetch_consistency

References

14 - Vacuuming

Complete dossiers for 34 core PostgreSQL settings in Vacuuming.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

14.1 - autovacuum

Autovacuum keeps MVCC tables usable by scheduling background VACUUM and ANALYZE work. It is both a performance mechanism and a wraparound safety net, not optional cosmetic housekeeping.
Note

Fact — official short description: “Starts the autovacuum subprocess.”

Identity

Type Valuebool
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 ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

When enabled, one launcher coordinates worker processes across databases. Workers use cumulative table-change statistics, so track_counts must also be enabled, and they run VACUUM or ANALYZE when a table crosses the relevant thresholds.

Ordinary vacuum triggers react to inserted, updated, and deleted tuples. Separately, PostgreSQL can launch anti-wraparound autovacuums even when this switch is off, because allowing old transaction IDs or multixact IDs to wrap would threaten correctness.

Most trigger and cost settings can be overridden per table through storage parameters. Temporary tables are outside autovacuum’s reach, and partitioned parent tables can still need manual ANALYZE even though their partitions are processed normally.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep it on. Tune busy tables individually, then watch dead tuples, autovacuum duration, canceled workers, and XID age before changing global aggressiveness.
OLAP Keep it on for safety, but coordinate it with bulk-load windows. Run explicit ANALYZE after large loads and on partitioned parents when planner statistics must be immediately current.
Small nodes Leave the default on. Reducing worker count or per-table aggressiveness is safer than disabling the launcher merely to save a small amount of background activity.

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

  • Turning it off does not disable emergency anti-wraparound vacuuming.
  • track_counts must be on for ordinary autovacuum decisions to work.
  • Long transactions and stale replication slots can prevent cleanup even when workers run successfully.
  • Autovacuum does not analyze partitioned parent tables solely because their partitions changed.
  • Temporary tables require maintenance from the owning session.

Related parameters

autovacuum_max_workers · autovacuum_naptime · autovacuum_vacuum_scale_factor · autovacuum_analyze_scale_factor · autovacuum_freeze_max_age · track_counts

References

14.2 - autovacuum_analyze_scale_factor

autovacuum_analyze_scale_factor — Number of tuple inserts, updates, or deletes prior to analyze as a fraction of reltuples. Observed in PG9.0–19 Beta 3; its last measured boot default is 0.1 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Number of tuple inserts, updates, or deletes prior to analyze as a fraction of reltuples.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 100
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value0.1
0.1

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0.1 — 0.1

How it works

Number of tuple inserts, updates, or deletes prior to analyze as a fraction of reltuples. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The automatic-ANALYZE trigger is autovacuum_analyze_threshold plus autovacuum_analyze_scale_factor times pg_class.reltuples; inserts, updates, and deletes feed the cumulative counter. Per-table storage parameters can override the global values, and the statistics are eventually consistent estimates.

Monitor and change autovacuum_analyze_scale_factor together with autovacuum_analyze_threshold, default_statistics_target, track_counts. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_analyze_scale_factor from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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 0.04 different 0.04
OLAP 0.04 different 0.04
CRIT 0.04 different 0.04
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 0.04 (dcs); OLAP: PG9.0–19 Beta 3 = 0.04 (dcs); CRIT: PG9.0–19 Beta 3 = 0.04 (dcs); TINY: PG9.0–19 Beta 3 unmodified. Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to refresh planner statistics earlier on growing production tables; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum_analyze_threshold · default_statistics_target · track_counts · autovacuum · autovacuum_freeze_max_age · autovacuum_max_workers

References

14.3 - autovacuum_analyze_score_weight

autovacuum_analyze_score_weight — Scaling factor of analyze score for autovacuum prioritization. Observed in PG19 Beta 3; its last measured boot default is 1 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Scaling factor of analyze score for autovacuum prioritization.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value1
1

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
Commit date 2026-03-27
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 1 — 1

How it works

PostgreSQL describes autovacuum_analyze_score_weight as follows: “Scaling factor of analyze score for autovacuum prioritization.” A configuration reload applies the value to the server without a full 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.

PostgreSQL 19 scores every eligible table and sorts work by the maximum weighted component. This parameter multiplies the ANALYZE change pressure component: values above 1 raise its scheduling influence, values between 0 and 1 reduce it, and setting every score weight to 0 restores the pre-19 catalog-order strategy. pg_stat_autovacuum_scores exposes the components for inspection.

Read it together with autovacuum_freeze_score_weight, autovacuum_multixact_freeze_score_weight, autovacuum_vacuum_score_weight, autovacuum_vacuum_insert_score_weight. 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

Tip

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

Workload Guidance
OLTP Start at the upstream default and use pg_stat_autovacuum_scores, table churn, freeze age, queueing, and foreground latency to justify a change. Protect wraparound work and avoid letting a busy-table preference starve quieter tables.
OLAP Batch-heavy systems can benefit from prioritizing the largest maintenance debt or parallelizing index cleanup, but benchmark I/O saturation, maintenance memory, worker contention, and completion time across the whole maintenance window.
Small nodes Keep weights and parallelism conservative. One extra worker can be a large share of CPU, RAM, and storage queue depth; first fix thresholds and ensure autovacuum has enough time to finish.

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: 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 autovacuum_analyze_score_weight as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

autovacuum_freeze_score_weight · autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_max_workers · autovacuum_naptime

References

14.4 - autovacuum_analyze_threshold

autovacuum_analyze_threshold — Minimum number of tuple inserts, updates, or deletes prior to analyze. Observed in PG9.0–19 Beta 3; its last measured boot default is 50 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Minimum number of tuple inserts, updates, or deletes prior to analyze.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value50
50

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 50 — 50

How it works

Minimum number of tuple inserts, updates, or deletes prior to analyze. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The automatic-ANALYZE trigger is autovacuum_analyze_threshold plus autovacuum_analyze_scale_factor times pg_class.reltuples; inserts, updates, and deletes feed the cumulative counter. Per-table storage parameters can override the global values, and the statistics are eventually consistent estimates.

Monitor and change autovacuum_analyze_threshold together with autovacuum_analyze_scale_factor, default_statistics_target, track_counts. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_analyze_threshold from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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 250 different 250
OLAP 500 different 500
CRIT 250 different 250
TINY 250 different 250
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 250 (dcs); OLAP: PG9.0–19 Beta 3 = 500 (dcs); CRIT: PG9.0–19 Beta 3 = 250 (dcs); TINY: PG9.0–19 Beta 3 = 250 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to avoid analyzing very small change bursts while giving OLAP a larger base threshold; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum_analyze_scale_factor · default_statistics_target · track_counts · autovacuum · autovacuum_freeze_max_age · autovacuum_max_workers

References

14.5 - autovacuum_freeze_max_age

autovacuum_freeze_max_age — Age at which to autovacuum a table to prevent transaction ID wraparound. Observed in PG9.0–19 Beta 3; its last measured boot default is 200000000 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Age at which to autovacuum a table to prevent transaction ID wraparound.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value100000 – 2000000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value200000000
200000000

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 200000000 — 200000000

How it works

Age at which to autovacuum a table to prevent transaction ID wraparound. The value is fixed when the server starts, so changing it requires a restart.

Reaching the max age forces an aggressive autovacuum even if ordinary autovacuum is disabled; a per-table override can only lower the global ceiling. Safety must be assessed across every database/table age together with long transactions and replication slots.

Monitor and change autovacuum_freeze_max_age together with vacuum_freeze_min_age, vacuum_freeze_table_age, vacuum_failsafe_age. 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

Tip

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

Workload Guidance
OLTP Calibrate autovacuum_freeze_max_age against the oldest XID/MXID age in every database and measured vacuum completion rate. Remove long transactions, stale slots, and blocked workers; never raise ages merely to hide a backlog.
OLAP Proactively VACUUM (FREEZE) newly loaded or static partitions in batch windows and reserve I/O time for full scans. Convert age budgets using peak transaction rate, not a wall-clock guess.
Small nodes Upstream defaults are usually safest. A small system still needs anti-wraparound maintenance; monitor every database, not only the application database.

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 1000000000 different 1000000000
OLAP 1000000000 different 1000000000
CRIT 1000000000 different 1000000000
TINY 1000000000 different 1000000000
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 1000000000 (dcs); OLAP: PG9.0–19 Beta 3 = 1000000000 (dcs); CRIT: PG9.0–19 Beta 3 = 1000000000 (dcs); TINY: PG9.0–19 Beta 3 = 1000000000 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to reduce forced anti-wraparound vacuum frequency by accepting a larger XID-age operating window; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Converting transaction age to days without using the actual transaction rate.
  • Raising the ceiling to hide blocked or underprovisioned vacuum.
  • Monitoring only the current database instead of every database and table.
  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.

Related parameters

vacuum_freeze_min_age · vacuum_freeze_table_age · vacuum_failsafe_age · autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age · vacuum_multixact_freeze_table_age

References

14.6 - autovacuum_freeze_score_weight

autovacuum_freeze_score_weight — Scaling factor of freeze score for autovacuum prioritization. Observed in PG19 Beta 3; its last measured boot default is 1 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Scaling factor of freeze score for autovacuum prioritization.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value1
1

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
Commit date 2026-03-27
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 1 — 1

How it works

PostgreSQL describes autovacuum_freeze_score_weight as follows: “Scaling factor of freeze score for autovacuum prioritization.” A configuration reload applies the value to the server without a full 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.

PostgreSQL 19 scores every eligible table and sorts work by the maximum weighted component. This parameter multiplies the transaction-ID freeze age component: values above 1 raise its scheduling influence, values between 0 and 1 reduce it, and setting every score weight to 0 restores the pre-19 catalog-order strategy. pg_stat_autovacuum_scores exposes the components for inspection.

Read it together with autovacuum_multixact_freeze_score_weight, autovacuum_vacuum_score_weight, autovacuum_vacuum_insert_score_weight, autovacuum_analyze_score_weight. 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

Tip

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

Workload Guidance
OLTP Start at the upstream default and use pg_stat_autovacuum_scores, table churn, freeze age, queueing, and foreground latency to justify a change. Protect wraparound work and avoid letting a busy-table preference starve quieter tables.
OLAP Batch-heavy systems can benefit from prioritizing the largest maintenance debt or parallelizing index cleanup, but benchmark I/O saturation, maintenance memory, worker contention, and completion time across the whole maintenance window.
Small nodes Keep weights and parallelism conservative. One extra worker can be a large share of CPU, RAM, and storage queue depth; first fix thresholds and ensure autovacuum has enough time to finish.

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: 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 autovacuum_freeze_score_weight as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

References

14.7 - autovacuum_max_parallel_workers

autovacuum_max_parallel_workers — Maximum number of parallel workers that can be used by a single autovacuum worker. Observed in PG19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Maximum number of parallel workers that can be used by a single autovacuum worker.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 1024
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value0
0

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit 1ff3180ca016 — Allow autovacuum to use parallel vacuum workers.
Commit date 2026-04-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 0 — 0

How it works

PostgreSQL describes autovacuum_max_parallel_workers as follows: “Maximum number of parallel workers that can be used by a single autovacuum worker.” A configuration reload applies the value to the server without a full 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 limit applies per autovacuum worker and only to index vacuuming and index-cleanup phases. Zero disables parallel autovacuum; the actual count is also capped by max_parallel_workers, while each participating worker consumes CPU and maintenance memory.

Read it together with autovacuum_max_workers, autovacuum_worker_slots, max_parallel_workers, maintenance_work_mem. 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

Tip

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

Workload Guidance
OLTP Start at the upstream default and use pg_stat_autovacuum_scores, table churn, freeze age, queueing, and foreground latency to justify a change. Protect wraparound work and avoid letting a busy-table preference starve quieter tables.
OLAP Batch-heavy systems can benefit from prioritizing the largest maintenance debt or parallelizing index cleanup, but benchmark I/O saturation, maintenance memory, worker contention, and completion time across the whole maintenance window.
Small nodes Keep weights and parallelism conservative. One extra worker can be a large share of CPU, RAM, and storage queue depth; first fix thresholds and ensure autovacuum has enough time to finish.

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: 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 autovacuum_max_parallel_workers as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

autovacuum_max_workers · autovacuum_worker_slots · max_parallel_workers · maintenance_work_mem · autovacuum_work_mem

References

14.8 - autovacuum_max_workers

Sets the cluster-wide ceiling for concurrently running autovacuum workers, excluding the launcher. More workers improve scheduling capacity, but they also increase concurrent maintenance demand.
Note

Fact — official short description: “Sets the maximum number of simultaneously running autovacuum worker processes.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value1 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value3
3

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 3 — 3

How it works

The launcher starts workers across databases up to this limit. A worker can process one table at a time, several workers may operate in the same database, and these processes do not consume max_connections slots.

In PostgreSQL 18, autovacuum workers are drawn from autovacuum_worker_slots, so setting this value above the slot count has no effect. The local fact matrix also records a context change: PG10-17 required server start, while PG18 makes the setting reloadable.

Autovacuum cost limits are normally balanced among active workers. Raising only the worker count therefore improves concurrency and queueing, but does not necessarily multiply the total permitted maintenance I/O rate.

Tuning advice

Tip

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

Workload Guidance
OLTP Increase gradually only when eligible tables wait too long and storage has headroom. Check worker saturation, vacuum duration, I/O latency, and autovacuum_worker_slots together.
OLAP Large relations can occupy workers for long periods, so extra workers may reduce backlog across databases. Pair any increase with explicit maintenance windows and cost-limit review.
Small nodes Two or three workers are usually a sensible starting range. Prefer fewer concurrent workers over disabling autovacuum on a constrained host.

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 3 same as boot 3
OLAP 3 same as boot 3
CRIT 3 same as boot 3
TINY 2 different 2
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 3 (dcs); OLAP: PG9.0–19 Beta 3 = 3 (dcs); CRIT: PG9.0–19 Beta 3 = 3 (dcs); TINY: PG9.0–19 Beta 3 = 2 (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: TINY reduces maintenance concurrency to limit CPU and I/O contention, while the other profiles retain conservative upstream concurrency.

Common pitfalls

  • A value above autovacuum_worker_slots is ineffective on PostgreSQL 18.
  • More workers can amplify I/O latency even when backlog improves.
  • Raising workers alone may not raise aggregate cost-based vacuum throughput.
  • A few very large tables can occupy all workers and delay unrelated databases.
  • Changing it on PG10-17 requires restart; PG18 behavior is reloadable.

Related parameters

autovacuum · autovacuum_worker_slots · autovacuum_naptime · autovacuum_vacuum_cost_limit · autovacuum_vacuum_cost_delay · max_worker_processes

References

14.9 - autovacuum_multixact_freeze_max_age

autovacuum_multixact_freeze_max_age — Multixact age at which to autovacuum a table to prevent multixact wraparound. Observed in PG9.3–19 Beta 3; its last measured boot default is 400000000 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Multixact age at which to autovacuum a table to prevent multixact wraparound.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value10000 – 2000000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value400000000
400000000

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit fb47de2be6e4 — Separate multixact freezing parameters from xid’s
Commit date 2014-02-13
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 400000000 — 400000000

How it works

Multixact age at which to autovacuum a table to prevent multixact wraparound. The value is fixed when the server starts, so changing it requires a restart.

Reaching the max age forces an aggressive autovacuum even if ordinary autovacuum is disabled; a per-table override can only lower the global ceiling. Safety must be assessed across every database/table age together with long transactions and replication slots.

Monitor and change autovacuum_multixact_freeze_max_age together with autovacuum_freeze_max_age, vacuum_freeze_min_age, vacuum_freeze_table_age. 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

Tip

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

Workload Guidance
OLTP Calibrate autovacuum_multixact_freeze_max_age against the oldest XID/MXID age in every database and measured vacuum completion rate. Remove long transactions, stale slots, and blocked workers; never raise ages merely to hide a backlog.
OLAP Proactively VACUUM (FREEZE) newly loaded or static partitions in batch windows and reserve I/O time for full scans. Convert age budgets using peak transaction rate, not a wall-clock guess.
Small nodes Upstream defaults are usually safest. A small system still needs anti-wraparound maintenance; monitor every database, not only the application database.

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: PG9.3–19 Beta 3 unmodified; OLAP: PG9.3–19 Beta 3 unmodified; CRIT: PG9.3–19 Beta 3 unmodified; TINY: PG9.3–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Ignoring MultiXact member storage pressure, which can force work earlier.
  • Assuming XID-age monitoring also covers MXID age.
  • Raising the ceiling while long-lived row locks keep generating old multixacts.
  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.

Related parameters

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_freeze_table_age · vacuum_failsafe_age · vacuum_multixact_freeze_min_age · vacuum_multixact_freeze_table_age

References

14.10 - autovacuum_multixact_freeze_score_weight

autovacuum_multixact_freeze_score_weight — Scaling factor of multixact freeze score for autovacuum prioritization. Observed in PG19 Beta 3; its last measured boot default is 1 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Scaling factor of multixact freeze score for autovacuum prioritization.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value1
1

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
Commit date 2026-03-27
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 1 — 1

How it works

PostgreSQL describes autovacuum_multixact_freeze_score_weight as follows: “Scaling factor of multixact freeze score for autovacuum prioritization.” A configuration reload applies the value to the server without a full 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.

PostgreSQL 19 scores every eligible table and sorts work by the maximum weighted component. This parameter multiplies the MultiXact freeze age component: values above 1 raise its scheduling influence, values between 0 and 1 reduce it, and setting every score weight to 0 restores the pre-19 catalog-order strategy. pg_stat_autovacuum_scores exposes the components for inspection.

Read it together with autovacuum_freeze_score_weight, autovacuum_vacuum_score_weight, autovacuum_vacuum_insert_score_weight, autovacuum_analyze_score_weight. 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

Tip

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

Workload Guidance
OLTP Start at the upstream default and use pg_stat_autovacuum_scores, table churn, freeze age, queueing, and foreground latency to justify a change. Protect wraparound work and avoid letting a busy-table preference starve quieter tables.
OLAP Batch-heavy systems can benefit from prioritizing the largest maintenance debt or parallelizing index cleanup, but benchmark I/O saturation, maintenance memory, worker contention, and completion time across the whole maintenance window.
Small nodes Keep weights and parallelism conservative. One extra worker can be a large share of CPU, RAM, and storage queue depth; first fix thresholds and ensure autovacuum has enough time to finish.

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: 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 autovacuum_multixact_freeze_score_weight as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

autovacuum_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

References

14.11 - autovacuum_naptime

autovacuum_naptime — Time to sleep between autovacuum runs. Observed in PG9.0–19 Beta 3; its last measured boot default is 1 min in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Time to sleep between autovacuum runs.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value1 – 2147483
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value60
1 min

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 60 s 1 min

How it works

Time to sleep between autovacuum runs. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The launcher aims to start work in each database once per interval; with N databases, launch attempts are spread at roughly naptime/N. It is not a fixed per-table polling period, and worker availability plus long-running jobs can add delay.

Monitor and change autovacuum_naptime together with autovacuum, autovacuum_max_workers, autovacuum_worker_slots. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_naptime from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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 1min same as boot 1min
OLAP 1min same as boot 1min
CRIT 1min same as boot 1min
TINY 1min same as boot 1min
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 1min (dcs); OLAP: PG9.0–19 Beta 3 = 1min (dcs); CRIT: PG9.0–19 Beta 3 = 1min (dcs); TINY: PG9.0–19 Beta 3 = 1min (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to retain PostgreSQL’s one-minute database scheduling cadence explicitly; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum · autovacuum_max_workers · autovacuum_worker_slots · autovacuum_work_mem · track_counts · autovacuum_analyze_scale_factor

References

14.12 - autovacuum_vacuum_cost_delay

autovacuum_vacuum_cost_delay — Vacuum cost delay in milliseconds, for autovacuum. Observed in PG9.0–19 Beta 3; its last measured boot default is 2 ms in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Vacuum cost delay in milliseconds, for autovacuum.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value-1 – 100
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value2
2 ms

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–11 20 ms 20 ms
PG12–19 Beta 3 2 ms 2 ms

How it works

Vacuum cost delay in milliseconds, for autovacuum. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

These values govern cost throttling for autovacuum workers; -1 inherits vacuum_cost_delay or vacuum_cost_limit respectively. With multiple active workers, the autovacuum cost budget is balanced among them, so a per-worker reading is not simply multiplied by concurrency.

Monitor and change autovacuum_vacuum_cost_delay together with vacuum_cost_delay, vacuum_cost_limit, vacuum_cost_page_hit. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_vacuum_cost_delay from autovacuum duration, dead-tuple growth, and foreground I/O latency together. Prefer per-table overrides for hotspots; global throttling must not let cleanup fall permanently behind.
OLAP During post-load windows, a larger budget or shorter delay can improve maintenance throughput, but verify that scans do not starve queries/imports. Failsafe activation means normal pacing already failed.
Small nodes Keep conservative defaults. On slow disks, lowering concurrency or overriding one table is usually more controllable than making the delay arbitrarily large.

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 -1 different -1
OLAP -1 different -1
CRIT -1 different -1
TINY -1 different -1
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = -1 (dcs); OLAP: PG9.0–19 Beta 3 = -1 (dcs); CRIT: PG9.0–19 Beta 3 = -1 (dcs); TINY: PG9.0–19 Beta 3 = -1 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to delegate autovacuum delay to the ordinary vacuum cost setting via the -1 inheritance value; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_limit

References

14.13 - autovacuum_vacuum_cost_limit

autovacuum_vacuum_cost_limit — Vacuum cost amount available before napping, for autovacuum. Observed in PG9.0–19 Beta 3; its last measured boot default is -1 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Vacuum cost amount available before napping, for autovacuum.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value-1 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value-1
-1

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 -1 — -1

How it works

Vacuum cost amount available before napping, for autovacuum. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

These values govern cost throttling for autovacuum workers; -1 inherits vacuum_cost_delay or vacuum_cost_limit respectively. With multiple active workers, the autovacuum cost budget is balanced among them, so a per-worker reading is not simply multiplied by concurrency.

Monitor and change autovacuum_vacuum_cost_limit together with vacuum_cost_delay, vacuum_cost_limit, vacuum_cost_page_hit. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_vacuum_cost_limit from autovacuum duration, dead-tuple growth, and foreground I/O latency together. Prefer per-table overrides for hotspots; global throttling must not let cleanup fall permanently behind.
OLAP During post-load windows, a larger budget or shorter delay can improve maintenance throughput, but verify that scans do not starve queries/imports. Failsafe activation means normal pacing already failed.
Small nodes Keep conservative defaults. On slow disks, lowering concurrency or overriding one table is usually more controllable than making the delay arbitrarily large.

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 -1 same as boot -1
OLAP -1 same as boot -1
CRIT -1 same as boot -1
TINY -1 same as boot -1
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = -1 (dcs); OLAP: PG9.0–19 Beta 3 = -1 (dcs); CRIT: PG9.0–19 Beta 3 = -1 (dcs); TINY: PG9.0–19 Beta 3 = -1 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to delegate autovacuum’s cost budget to vacuum_cost_limit via the -1 inheritance value; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay

References

14.14 - autovacuum_vacuum_insert_scale_factor

autovacuum_vacuum_insert_scale_factor sets the number of tuple inserts prior to vacuum as a fraction of reltuples. It is a sighup setting present in PG13–18; the latest recorded boot default is 0.2.
Note

Fact — official short description: “Number of tuple inserts prior to vacuum as a fraction of reltuples.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 100
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value0.2
0.2

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit b07642dbcd8d — Trigger autovacuum based on number of INSERTs
Commit date 2020-03-28
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 0.2 — 0.2

How it works

Number of tuple inserts prior to vacuum as a fraction of reltuples. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

For insert-heavy tables the trigger is the insert threshold plus insert scale factor times reltuples times the fraction not all-frozen. Such vacuuming can advance visibility/freeze state even without dead tuples and reduce later aggressive-vacuum work.

Monitor and change autovacuum_vacuum_insert_scale_factor together with autovacuum_vacuum_threshold, autovacuum_vacuum_scale_factor, autovacuum_vacuum_max_threshold. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_vacuum_insert_scale_factor from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum_vacuum_threshold · autovacuum_vacuum_scale_factor · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_threshold · autovacuum · autovacuum_analyze_scale_factor

References

14.15 - autovacuum_vacuum_insert_score_weight

autovacuum_vacuum_insert_score_weight — Scaling factor of vacuum insert score for autovacuum prioritization. Observed in PG19 Beta 3; its last measured boot default is 1 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Scaling factor of vacuum insert score for autovacuum prioritization.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value1
1

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
Commit date 2026-03-27
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 1 — 1

How it works

PostgreSQL describes autovacuum_vacuum_insert_score_weight as follows: “Scaling factor of vacuum insert score for autovacuum prioritization.” A configuration reload applies the value to the server without a full 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.

PostgreSQL 19 scores every eligible table and sorts work by the maximum weighted component. This parameter multiplies the insert-driven vacuum pressure component: values above 1 raise its scheduling influence, values between 0 and 1 reduce it, and setting every score weight to 0 restores the pre-19 catalog-order strategy. pg_stat_autovacuum_scores exposes the components for inspection.

Read it together with autovacuum_freeze_score_weight, autovacuum_multixact_freeze_score_weight, autovacuum_vacuum_score_weight, autovacuum_analyze_score_weight. 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

Tip

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

Workload Guidance
OLTP Start at the upstream default and use pg_stat_autovacuum_scores, table churn, freeze age, queueing, and foreground latency to justify a change. Protect wraparound work and avoid letting a busy-table preference starve quieter tables.
OLAP Batch-heavy systems can benefit from prioritizing the largest maintenance debt or parallelizing index cleanup, but benchmark I/O saturation, maintenance memory, worker contention, and completion time across the whole maintenance window.
Small nodes Keep weights and parallelism conservative. One extra worker can be a large share of CPU, RAM, and storage queue depth; first fix thresholds and ensure autovacuum has enough time to finish.

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: 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 autovacuum_vacuum_insert_score_weight as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

autovacuum_freeze_score_weight · autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

References

14.16 - autovacuum_vacuum_insert_threshold

autovacuum_vacuum_insert_threshold sets the minimum number of tuple inserts prior to vacuum. It is a sighup setting present in PG13–18; the latest recorded boot default is 1000.
Note

Fact — official short description: “Minimum number of tuple inserts prior to vacuum.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value1000
1000

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit b07642dbcd8d — Trigger autovacuum based on number of INSERTs
Commit date 2020-03-28
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 1000 — 1000

How it works

Minimum number of tuple inserts prior to vacuum. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

For insert-heavy tables the trigger is the insert threshold plus insert scale factor times reltuples times the fraction not all-frozen. Such vacuuming can advance visibility/freeze state even without dead tuples and reduce later aggressive-vacuum work.

Monitor and change autovacuum_vacuum_insert_threshold together with autovacuum_vacuum_threshold, autovacuum_vacuum_scale_factor, autovacuum_vacuum_max_threshold. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_vacuum_insert_threshold from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum_vacuum_threshold · autovacuum_vacuum_scale_factor · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum · autovacuum_analyze_scale_factor

References

14.17 - autovacuum_vacuum_max_threshold

autovacuum_vacuum_max_threshold — Maximum number of tuple updates or deletes prior to vacuum. Observed in PG18–19 Beta 3; its last measured boot default is 100000000 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Maximum number of tuple updates or deletes prior to vacuum.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value-1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value100000000
100000000

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 306dc520b9df — Introduce autovacuum_vacuum_max_threshold.
Commit date 2025-02-05
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 100000000 — 100000000

How it works

Maximum number of tuple updates or deletes prior to vacuum. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The ordinary automatic-vacuum threshold is the base term plus scale factor times reltuples, capped by autovacuum_vacuum_max_threshold from PG18. It reacts to dead tuples from updates/deletes, permits per-table overrides, and is separate from mandatory anti-wraparound vacuuming.

Monitor and change autovacuum_vacuum_max_threshold together with autovacuum_vacuum_threshold, autovacuum_vacuum_scale_factor, autovacuum_vacuum_insert_threshold. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_vacuum_max_threshold from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum_vacuum_threshold · autovacuum_vacuum_scale_factor · autovacuum_vacuum_insert_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum · autovacuum_analyze_scale_factor

References

14.18 - autovacuum_vacuum_scale_factor

Controls the table-size-proportional part of the normal autovacuum VACUUM trigger. Lower values make large tables eligible after a smaller fraction of rows becomes obsolete.
Note

Fact — official short description: “Number of tuple updates or deletes prior to vacuum as a fraction of reltuples.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 100
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value0.2
0.2

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0.2 — 0.2

How it works

The core trigger is the base threshold plus this factor multiplied by pg_class.reltuples, an approximate row count. In PostgreSQL 18 the result is also capped by autovacuum_vacuum_max_threshold.

This trigger counts tuples made obsolete by UPDATE or DELETE; insert-driven vacuuming has its own threshold and scale factor. Anti-wraparound vacuuming is governed by transaction-age rules and can run independently of this setting.

A table-level autovacuum_vacuum_scale_factor storage parameter overrides the global value, which is often preferable when table sizes and update rates vary widely.

Tuning advice

Tip

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

Workload Guidance
OLTP Use lower per-table values on large, update-heavy tables so dead tuples do not accumulate into a large absolute backlog. Validate with table churn and vacuum duration rather than selecting a percentage in isolation.
OLAP For append-and-batch workloads, coordinate the threshold with load cycles and explicit VACUUM/ANALYZE. A low global factor can create unwanted maintenance during bulk jobs.
Small nodes The upstream default is often adequate for genuinely small tables. Tune exceptions per table; a low cluster-wide value can create frequent tiny vacuums.

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 0.08 different 0.08
OLAP 0.08 different 0.08
CRIT 0.08 different 0.08
TINY Unmodified — —
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 0.08 (dcs); OLAP: PG9.0–19 Beta 3 = 0.08 (dcs); CRIT: PG9.0–19 Beta 3 = 0.08 (dcs); TINY: PG9.0–19 Beta 3 unmodified. Advice, pending human review — Editorial hypothesis, pending maintainer review: the larger profiles favor earlier cleanup to bound absolute dead-tuple accumulation on sizable tables; TINY avoids extra vacuum frequency on constrained systems.

Common pitfalls

  • A percentage that looks small can still represent millions of dead tuples on a large table.
  • Lowering the factor globally can create continuous I/O pressure across many tables.
  • It does not control insert-triggered vacuuming or anti-wraparound vacuuming.
  • reltuples is an estimate, so the trigger is not an exact dead-row percentage.
  • Table storage parameters can silently make the global value irrelevant for that table.

Related parameters

autovacuum_vacuum_threshold · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum_analyze_scale_factor · autovacuum_naptime · autovacuum_freeze_max_age

References

14.19 - autovacuum_vacuum_score_weight

autovacuum_vacuum_score_weight — Scaling factor of vacuum score for autovacuum prioritization. Observed in PG19 Beta 3; its last measured boot default is 1 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Scaling factor of vacuum score for autovacuum prioritization.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 10
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value1
1

Lifecycle

Fact Value
First observed PG19 Beta 3
Present in PG19 Beta 3
Removed in No
Introduction commit d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
Commit date 2026-03-27
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG19 Beta 3 1 — 1

How it works

PostgreSQL describes autovacuum_vacuum_score_weight as follows: “Scaling factor of vacuum score for autovacuum prioritization.” A configuration reload applies the value to the server without a full 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.

PostgreSQL 19 scores every eligible table and sorts work by the maximum weighted component. This parameter multiplies the updated/deleted-tuple vacuum pressure component: values above 1 raise its scheduling influence, values between 0 and 1 reduce it, and setting every score weight to 0 restores the pre-19 catalog-order strategy. pg_stat_autovacuum_scores exposes the components for inspection.

Read it together with autovacuum_freeze_score_weight, autovacuum_multixact_freeze_score_weight, autovacuum_vacuum_insert_score_weight, autovacuum_analyze_score_weight. 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

Tip

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

Workload Guidance
OLTP Start at the upstream default and use pg_stat_autovacuum_scores, table churn, freeze age, queueing, and foreground latency to justify a change. Protect wraparound work and avoid letting a busy-table preference starve quieter tables.
OLAP Batch-heavy systems can benefit from prioritizing the largest maintenance debt or parallelizing index cleanup, but benchmark I/O saturation, maintenance memory, worker contention, and completion time across the whole maintenance window.
Small nodes Keep weights and parallelism conservative. One extra worker can be a large share of CPU, RAM, and storage queue depth; first fix thresholds and ensure autovacuum has enough time to finish.

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: 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 autovacuum_vacuum_score_weight as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup 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

autovacuum_freeze_score_weight · autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

References

14.20 - autovacuum_vacuum_threshold

autovacuum_vacuum_threshold — Minimum number of tuple updates or deletes prior to vacuum. Observed in PG9.0–19 Beta 3; its last measured boot default is 50 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Minimum number of tuple updates or deletes prior to vacuum.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value50
50

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 50 — 50

How it works

Minimum number of tuple updates or deletes prior to vacuum. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The ordinary automatic-vacuum threshold is the base term plus scale factor times reltuples, capped by autovacuum_vacuum_max_threshold from PG18. It reacts to dead tuples from updates/deletes, permits per-table overrides, and is separate from mandatory anti-wraparound vacuuming.

Monitor and change autovacuum_vacuum_threshold together with autovacuum_vacuum_scale_factor, autovacuum_vacuum_max_threshold, autovacuum_vacuum_insert_threshold. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune autovacuum_vacuum_threshold from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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 500 different 500
OLAP 1000 different 1000
CRIT 500 different 500
TINY 500 different 500
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 500 (dcs); OLAP: PG9.0–19 Beta 3 = 1000 (dcs); CRIT: PG9.0–19 Beta 3 = 500 (dcs); TINY: PG9.0–19 Beta 3 = 500 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to raise the fixed trigger term so small tables are not vacuumed after only a handful of dead tuples; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum_vacuum_scale_factor · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum · autovacuum_analyze_scale_factor

References

14.21 - autovacuum_worker_slots

autovacuum_worker_slots — Sets the number of backend slots to allocate for autovacuum workers. Observed in PG18–19 Beta 3; its last measured boot default is 16 in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the number of backend slots to allocate for autovacuum workers.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value1 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Automatic Vacuuming
Upstream classification
Latest boot value Value16
16

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit c758119e5bfb — Allow changing autovacuum_max_workers without restarting.
Commit date 2025-01-06
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 16 — 16

How it works

Sets the number of backend slots to allocate for autovacuum workers. The value is fixed when the server starts, so changing it requires a restart.

PG18 separates the startup allocation of backend slots for autovacuum workers from the active concurrency limit autovacuum_max_workers. The slots are reserved at startup so the worker limit can be reloaded within that allocation.

Monitor and change autovacuum_worker_slots together with autovacuum, autovacuum_naptime, autovacuum_max_workers. 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

Tip

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

Workload Guidance
OLTP Tune autovacuum_worker_slots from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

autovacuum · autovacuum_naptime · autovacuum_max_workers · autovacuum_work_mem · track_counts · autovacuum_analyze_scale_factor

References

14.22 - vacuum_cost_delay

vacuum_cost_delay — Vacuum cost delay in milliseconds. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 ms in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Vacuum cost delay in milliseconds.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Valuems
Raw unit
Range Value0 – 100
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Cost-Based Vacuum Delay
Upstream classification
Latest boot value Value0
0 ms

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 ms 0 ms

How it works

Vacuum cost delay in milliseconds. It can be changed at session scope, so different sessions may observe different behavior.

VACUUM accumulates virtual cost for page hits, misses, and dirties; after the balance reaches vacuum_cost_limit it sleeps for vacuum_cost_delay and resets. This is coarse I/O pacing rather than an exact bandwidth cap, and the wraparound failsafe bypasses throttling.

Monitor and change vacuum_cost_delay together with vacuum_cost_limit, vacuum_cost_page_hit, vacuum_cost_page_miss. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune vacuum_cost_delay from autovacuum duration, dead-tuple growth, and foreground I/O latency together. Prefer per-table overrides for hotspots; global throttling must not let cleanup fall permanently behind.
OLAP During post-load windows, a larger budget or shorter delay can improve maintenance throughput, but verify that scans do not starve queries/imports. Failsafe activation means normal pacing already failed.
Small nodes Keep conservative defaults. On slow disks, lowering concurrency or overriding one table is usually more controllable than making the delay arbitrarily large.

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 20ms different 20ms
OLAP 10ms different 10ms
CRIT 20ms different 20ms
TINY 20ms different 20ms
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 20ms (dcs); OLAP: PG9.0–19 Beta 3 = 10ms (dcs); CRIT: PG9.0–19 Beta 3 = 20ms (dcs); TINY: PG9.0–19 Beta 3 = 20ms (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to throttle manual and inherited autovacuum I/O, with a shorter delay for the higher-throughput OLAP profile; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

References

14.23 - vacuum_cost_limit

vacuum_cost_limit — Vacuum cost amount available before napping. Observed in PG9.0–19 Beta 3; its last measured boot default is 200 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Vacuum cost amount available before napping.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value1 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Cost-Based Vacuum Delay
Upstream classification
Latest boot value Value200
200

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 200 — 200

How it works

Vacuum cost amount available before napping. It can be changed at session scope, so different sessions may observe different behavior.

VACUUM accumulates virtual cost for page hits, misses, and dirties; after the balance reaches vacuum_cost_limit it sleeps for vacuum_cost_delay and resets. This is coarse I/O pacing rather than an exact bandwidth cap, and the wraparound failsafe bypasses throttling.

Monitor and change vacuum_cost_limit together with vacuum_cost_delay, vacuum_cost_page_hit, vacuum_cost_page_miss. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune vacuum_cost_limit from autovacuum duration, dead-tuple growth, and foreground I/O latency together. Prefer per-table overrides for hotspots; global throttling must not let cleanup fall permanently behind.
OLAP During post-load windows, a larger budget or shorter delay can improve maintenance throughput, but verify that scans do not starve queries/imports. Failsafe activation means normal pacing already failed.
Small nodes Keep conservative defaults. On slow disks, lowering concurrency or overriding one table is usually more controllable than making the delay arbitrarily large.

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 2000 different 2000
OLAP 10000 different 10000
CRIT 2000 different 2000
TINY 2000 different 2000
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 2000 (dcs); OLAP: PG9.0–19 Beta 3 = 10000 (dcs); CRIT: PG9.0–19 Beta 3 = 2000 (dcs); TINY: PG9.0–19 Beta 3 = 2000 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to pair the delay with a much larger work budget, especially for OLAP maintenance; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

vacuum_cost_delay · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

References

14.24 - vacuum_cost_page_dirty

vacuum_cost_page_dirty — Vacuum cost for a page dirtied by vacuum. Observed in PG9.0–19 Beta 3; its last measured boot default is 20 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Vacuum cost for a page dirtied by vacuum.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Cost-Based Vacuum Delay
Upstream classification
Latest boot value Value20
20

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 20 — 20

How it works

Vacuum cost for a page dirtied by vacuum. It can be changed at session scope, so different sessions may observe different behavior.

VACUUM accumulates virtual cost for page hits, misses, and dirties; after the balance reaches vacuum_cost_limit it sleeps for vacuum_cost_delay and resets. This is coarse I/O pacing rather than an exact bandwidth cap, and the wraparound failsafe bypasses throttling.

Monitor and change vacuum_cost_page_dirty together with vacuum_cost_delay, vacuum_cost_limit, vacuum_cost_page_hit. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune vacuum_cost_page_dirty from autovacuum duration, dead-tuple growth, and foreground I/O latency together. Prefer per-table overrides for hotspots; global throttling must not let cleanup fall permanently behind.
OLAP During post-load windows, a larger budget or shorter delay can improve maintenance throughput, but verify that scans do not starve queries/imports. Failsafe activation means normal pacing already failed.
Small nodes Keep conservative defaults. On slow disks, lowering concurrency or overriding one table is usually more controllable than making the delay arbitrarily large.

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

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

References

14.25 - vacuum_cost_page_hit

vacuum_cost_page_hit — Vacuum cost for a page found in the buffer cache. Observed in PG9.0–19 Beta 3; its last measured boot default is 1 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Vacuum cost for a page found in the buffer cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Cost-Based Vacuum Delay
Upstream classification
Latest boot value Value1
1

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 1 — 1

How it works

Vacuum cost for a page found in the buffer cache. It can be changed at session scope, so different sessions may observe different behavior.

VACUUM accumulates virtual cost for page hits, misses, and dirties; after the balance reaches vacuum_cost_limit it sleeps for vacuum_cost_delay and resets. This is coarse I/O pacing rather than an exact bandwidth cap, and the wraparound failsafe bypasses throttling.

Monitor and change vacuum_cost_page_hit together with vacuum_cost_delay, vacuum_cost_limit, vacuum_cost_page_miss. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune vacuum_cost_page_hit from autovacuum duration, dead-tuple growth, and foreground I/O latency together. Prefer per-table overrides for hotspots; global throttling must not let cleanup fall permanently behind.
OLAP During post-load windows, a larger budget or shorter delay can improve maintenance throughput, but verify that scans do not starve queries/imports. Failsafe activation means normal pacing already failed.
Small nodes Keep conservative defaults. On slow disks, lowering concurrency or overriding one table is usually more controllable than making the delay arbitrarily large.

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

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

References

14.26 - vacuum_cost_page_miss

vacuum_cost_page_miss — Vacuum cost for a page not found in the buffer cache. Observed in PG9.0–19 Beta 3; its last measured boot default is 2 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Vacuum cost for a page not found in the buffer cache.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Cost-Based Vacuum Delay
Upstream classification
Latest boot value Value2
2

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–13 10 — 10
PG14–19 Beta 3 2 — 2

How it works

Vacuum cost for a page not found in the buffer cache. It can be changed at session scope, so different sessions may observe different behavior.

VACUUM accumulates virtual cost for page hits, misses, and dirties; after the balance reaches vacuum_cost_limit it sleeps for vacuum_cost_delay and resets. This is coarse I/O pacing rather than an exact bandwidth cap, and the wraparound failsafe bypasses throttling.

Monitor and change vacuum_cost_page_miss together with vacuum_cost_delay, vacuum_cost_limit, vacuum_cost_page_hit. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune vacuum_cost_page_miss from autovacuum duration, dead-tuple growth, and foreground I/O latency together. Prefer per-table overrides for hotspots; global throttling must not let cleanup fall permanently behind.
OLAP During post-load windows, a larger budget or shorter delay can improve maintenance throughput, but verify that scans do not starve queries/imports. Failsafe activation means normal pacing already failed.
Small nodes Keep conservative defaults. On slow disks, lowering concurrency or overriding one table is usually more controllable than making the delay arbitrarily large.

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

  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.
  • Blaming a threshold without checking long transactions, replication slots, and worker saturation.
  • Buying short-term quiet by deferring maintenance until wraparound failsafe activates.

Related parameters

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

References

14.27 - vacuum_failsafe_age

vacuum_failsafe_age sets the age at which VACUUM should trigger failsafe to avoid a wraparound outage. It is a user setting present in PG14–18; the latest recorded boot default is 1600000000.
Note

Fact — official short description: “Age at which VACUUM should trigger failsafe to avoid a wraparound outage.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2100000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Freezing
Upstream classification
Latest boot value Value1600000000
1600000000

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 1e55e7d1755c — Add wraparound failsafe to VACUUM.
Commit date 2021-04-07
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 1600000000 — 1600000000

How it works

Age at which VACUUM should trigger failsafe to avoid a wraparound outage. It can be changed at session scope, so different sessions may observe different behavior.

At the failsafe age, a running VACUUM prioritizes advancing the freeze horizon quickly: cost delays stop and optional work such as index cleanup and tail truncation is skipped. This is a last defense against wraparound outage, not a routine performance mode.

Monitor and change vacuum_failsafe_age together with autovacuum_freeze_max_age, vacuum_freeze_min_age, vacuum_freeze_table_age. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate vacuum_failsafe_age against the oldest XID/MXID age in every database and measured vacuum completion rate. Remove long transactions, stale slots, and blocked workers; never raise ages merely to hide a backlog.
OLAP Proactively VACUUM (FREEZE) newly loaded or static partitions in batch windows and reserve I/O time for full scans. Convert age budgets using peak transaction rate, not a wall-clock guess.
Small nodes Upstream defaults are usually safest. A small system still needs anti-wraparound maintenance; monitor every database, not only the application database.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating failsafe as a normal high-throughput VACUUM mode.
  • Ignoring skipped index cleanup after the emergency has passed.
  • Raising the age to suppress evidence of a maintenance failure.
  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.

Related parameters

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_freeze_table_age · autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age · vacuum_multixact_freeze_table_age

References

14.28 - vacuum_freeze_min_age

vacuum_freeze_min_age — Minimum age at which VACUUM should freeze a table row. Observed in PG9.0–19 Beta 3; its last measured boot default is 50000000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Minimum age at which VACUUM should freeze a table row.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1000000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Freezing
Upstream classification
Latest boot value Value50000000
50000000

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 50000000 — 50000000

How it works

Sets the minimum XID age at which VACUUM freezes tuple xmin values. It is a user-context setting, so a session can override it for manual VACUUM.

VACUUM computes an XID freeze cutoff from this age. Lower values freeze XIDs earlier and can repeat work on rows soon updated; higher values defer work. The effective value is capped at half of autovacuum_freeze_max_age.

Track age(relfrozenxid) for tables and age(datfrozenxid) for every database. Interpret this lower cutoff with vacuum_freeze_table_age, autovacuum_freeze_max_age, and vacuum_failsafe_age; the separate vacuum_multixact_freeze_min_age controls MXIDs.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep enough distance below autovacuum_freeze_max_age for routine vacuums to advance relfrozenxid. Tune from peak XID consumption and measured vacuum completion, not days on a calendar.
OLAP For append-mostly or static partitions, a lower value during planned VACUUM can freeze XIDs earlier and reduce later aggressive work; verify the extra WAL and scan cost.
Small nodes Keep the upstream default unless XID-age evidence justifies a change. Small databases still share the cluster transaction counter and need every database monitored.

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

  • Describing the cutoff as an MXID control; MultiXacts use vacuum_multixact_freeze_min_age.
  • Converting XID age to time without the measured transaction rate.
  • Raising the value so far that routine vacuum loses useful headroom before anti-wraparound work.
  • Ignoring per-table autovacuum_freeze_min_age overrides.

Related parameters

autovacuum_freeze_max_age · vacuum_freeze_table_age · vacuum_failsafe_age · vacuum_multixact_freeze_min_age · autovacuum · log_autovacuum_min_duration

References

14.29 - vacuum_freeze_table_age

vacuum_freeze_table_age — Age at which VACUUM should scan whole table to freeze tuples. Observed in PG9.0–19 Beta 3; its last measured boot default is 150000000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Age at which VACUUM should scan whole table to freeze tuples.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2000000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Freezing
Upstream classification
Latest boot value Value150000000
150000000

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 150000000 — 150000000

How it works

Sets the XID age at which VACUUM switches to an aggressive scan so it can advance a table’s relfrozenxid. It is a user-context setting.

An aggressive XID scan visits every page not already all-frozen and freezes eligible XIDs. PostgreSQL caps the effective value at 95% of autovacuum_freeze_max_age, leaving room for manual maintenance before forced anti-wraparound autovacuum.

Monitor age(relfrozenxid) and age(datfrozenxid), not relminmxid. The separate vacuum_multixact_freeze_table_age controls MXID-driven aggressive scans.

Tuning advice

Tip

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

Workload Guidance
OLTP Set an XID aggressive-scan threshold that routine maintenance can reach and complete before autovacuum_freeze_max_age. Confirm full-table scan time on the largest relations.
OLAP Schedule aggressive XID freezing for static or newly loaded partitions while I/O headroom is available; lowering the threshold can spread work across maintenance windows.
Small nodes Keep the default and watch the oldest relfrozenxid in every database. Setting zero forces aggressive behavior for every VACUUM and is rarely appropriate globally.

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

  • Monitoring relminmxid instead of the XID horizon relfrozenxid.
  • Setting a value above 95% of autovacuum_freeze_max_age and assuming PostgreSQL will use it unchanged.
  • Forcing aggressive scans too frequently on large mutable tables.
  • Waiting for forced anti-wraparound autovacuum instead of measuring routine full-scan completion time.

Related parameters

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_failsafe_age · vacuum_multixact_freeze_table_age · autovacuum · log_autovacuum_min_duration

References

14.30 - vacuum_max_eager_freeze_failure_rate

vacuum_max_eager_freeze_failure_rate — Fraction of pages in a relation vacuum can scan and fail to freeze before disabling eager scanning. Observed in PG18–19 Beta 3; its last measured boot default is 0.03 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Fraction of pages in a relation vacuum can scan and fail to freeze before disabling eager scanning.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Freezing
Upstream classification
Latest boot value Value0.03
0.03

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 052026c9b903 — Eagerly scan all-visible pages to amortize aggressive vacuum
Commit date 2025-02-11
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 0.03 — 0.03

How it works

Fraction of pages in a relation vacuum can scan and fail to freeze before disabling eager scanning. It can be changed at session scope, so different sessions may observe different behavior.

PG18 ordinary VACUUM may eagerly scan all-visible pages that are not all-frozen; it stops that extra work when the fraction scanned without successful freezing grows too high. Raising the rate can shrink later aggressive scans at the cost of more current I/O.

Monitor and change vacuum_max_eager_freeze_failure_rate together with vacuum_truncate, vacuum_freeze_table_age, autovacuum_freeze_max_age. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate vacuum_max_eager_freeze_failure_rate against the oldest XID/MXID age in every database and measured vacuum completion rate. Remove long transactions, stale slots, and blocked workers; never raise ages merely to hide a backlog.
OLAP Proactively VACUUM (FREEZE) newly loaded or static partitions in batch windows and reserve I/O time for full scans. Convert age budgets using peak transaction rate, not a wall-clock guess.
Small nodes Upstream defaults are usually safest. A small system still needs anti-wraparound maintenance; monitor every database, not only the application database.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the value as a percentage integer instead of a fraction between zero and one.
  • Raising it and increasing scans of all-visible pages without measuring added I/O and WAL.
  • Assuming eager freezing eliminates the need for periodic aggressive VACUUM.
  • Ignoring a table-level storage-parameter override.
  • Judging success only by pages scanned instead of pages actually frozen and future aggressive-scan work.

Related parameters

vacuum_truncate · vacuum_freeze_table_age · autovacuum_freeze_max_age · maintenance_work_mem · vacuum_failsafe_age · vacuum_freeze_min_age

References

14.31 - vacuum_multixact_failsafe_age

vacuum_multixact_failsafe_age sets the multixact age at which VACUUM should trigger failsafe to avoid a wraparound outage. It is a user setting present in PG14–18; the latest recorded boot default is 1600000000.
Note

Fact — official short description: “Multixact age at which VACUUM should trigger failsafe to avoid a wraparound outage.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2100000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Freezing
Upstream classification
Latest boot value Value1600000000
1600000000

Lifecycle

Fact Value
First observed PG14
Present in PG14–19 Beta 3
Removed in No
Introduction commit 1e55e7d1755c — Add wraparound failsafe to VACUUM.
Commit date 2021-04-07
Discussion thread 1 · thread 2

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG14–19 Beta 3 1600000000 — 1600000000

How it works

Multixact age at which VACUUM should trigger failsafe to avoid a wraparound outage. It can be changed at session scope, so different sessions may observe different behavior.

At the failsafe age, a running VACUUM prioritizes advancing the freeze horizon quickly: cost delays stop and optional work such as index cleanup and tail truncation is skipped. This is a last defense against wraparound outage, not a routine performance mode.

Monitor and change vacuum_multixact_failsafe_age together with autovacuum_freeze_max_age, vacuum_freeze_min_age, vacuum_freeze_table_age. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Calibrate vacuum_multixact_failsafe_age against the oldest XID/MXID age in every database and measured vacuum completion rate. Remove long transactions, stale slots, and blocked workers; never raise ages merely to hide a backlog.
OLAP Proactively VACUUM (FREEZE) newly loaded or static partitions in batch windows and reserve I/O time for full scans. Convert age budgets using peak transaction rate, not a wall-clock guess.
Small nodes Upstream defaults are usually safest. A small system still needs anti-wraparound maintenance; monitor every database, not only the application database.

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: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating failsafe as routine instead of an emergency.
  • Monitoring only XID age and missing MXID exhaustion.
  • Ignoring post-failsafe index cleanup debt.
  • Changing the global value while a table storage parameter overrides it.
  • Treating reltuples and cumulative change statistics as exact real-time counts.

Related parameters

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_freeze_table_age · vacuum_failsafe_age · autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age

References

14.32 - vacuum_multixact_freeze_min_age

vacuum_multixact_freeze_min_age — Minimum age at which VACUUM should freeze a MultiXactId in a table row. Observed in PG9.3–19 Beta 3; its last measured boot default is 5000000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Minimum age at which VACUUM should freeze a MultiXactId in a table row.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1000000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Freezing
Upstream classification
Latest boot value Value5000000
5000000

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit fb47de2be6e4 — Separate multixact freezing parameters from xid’s
Commit date 2014-02-13
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 5000000 — 5000000

How it works

Sets the minimum MultiXact age at which VACUUM replaces old tuple xmax MultiXact IDs. It is a user-context setting and is distinct from the XID cutoff.

Lower values make VACUUM process MXIDs earlier; higher values defer that work. PostgreSQL may still remove MultiXacts proactively, and the effective cutoff is capped at half of autovacuum_multixact_freeze_max_age.

Track mxid_age(relminmxid), mxid_age(datminmxid), and pg_multixact member storage. Interpret it with vacuum_multixact_freeze_table_age, autovacuum_multixact_freeze_max_age, and vacuum_multixact_failsafe_age.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune from MXID consumption caused by row locks and multitransaction workloads. Preserve ample distance to autovacuum_multixact_freeze_max_age and monitor member storage as well as age.
OLAP Bulk reads alone rarely justify a change, but concurrent row-locking loaders can consume MXIDs quickly. Measure mxid_age and pg_multixact growth during the real load.
Small nodes Keep the default unless MXID evidence says otherwise. Low transaction volume does not protect a workload that creates many shared row locks.

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: PG9.3–19 Beta 3 unmodified; OLAP: PG9.3–19 Beta 3 unmodified; CRIT: PG9.3–19 Beta 3 unmodified; TINY: PG9.3–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Describing the cutoff as an XID control or monitoring only relfrozenxid.
  • Ignoring pg_multixact member-space pressure, which can force aggressive work before the configured age.
  • Raising the value while long-lived shared row locks continue to generate old MXIDs.
  • Using autovacuum_freeze_max_age instead of the MultiXact-specific maximum when calculating the cap.

Related parameters

autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_table_age · vacuum_multixact_failsafe_age · vacuum_freeze_min_age · autovacuum · log_autovacuum_min_duration

References

14.33 - vacuum_multixact_freeze_table_age

vacuum_multixact_freeze_table_age — Multixact age at which VACUUM should scan whole table to freeze tuples. Observed in PG9.3–19 Beta 3; its last measured boot default is 150000000 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Multixact age at which VACUUM should scan whole table to freeze tuples.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 2000000000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Freezing
Upstream classification
Latest boot value Value150000000
150000000

Lifecycle

Fact Value
First observed PG9.3
Present in PG9.3–19 Beta 3
Removed in No
Introduction commit fb47de2be6e4 — Separate multixact freezing parameters from xid’s
Commit date 2014-02-13
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.3–19 Beta 3 150000000 — 150000000

How it works

Sets the MultiXact age at which VACUUM switches to an aggressive scan so it can advance a table’s relminmxid. It is a user-context setting.

An aggressive MXID scan visits every page not already all-frozen and processes eligible MultiXacts. PostgreSQL caps the effective value at 95% of autovacuum_multixact_freeze_max_age.

Monitor mxid_age(relminmxid), mxid_age(datminmxid), and pg_multixact storage. The XID horizon relfrozenxid is controlled by vacuum_freeze_table_age instead.

Tuning advice

Tip

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

Workload Guidance
OLTP Choose an MXID threshold that leaves enough time to complete aggressive scans before autovacuum_multixact_freeze_max_age. Measure workloads with heavy shared row locking.
OLAP Most read-only analytics consume few MXIDs, but concurrent loaders can differ. Schedule scans from measured mxid_age and member-space growth rather than copying XID settings.
Small nodes Keep the default and monitor relminmxid/datminmxid. A small database can still consume MXIDs rapidly through row-locking patterns.

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: PG9.3–19 Beta 3 unmodified; OLAP: PG9.3–19 Beta 3 unmodified; CRIT: PG9.3–19 Beta 3 unmodified; TINY: PG9.3–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Monitoring relfrozenxid instead of the MultiXact horizon relminmxid.
  • Using autovacuum_freeze_max_age rather than autovacuum_multixact_freeze_max_age for the 95% cap.
  • Copying an XID-age policy into an MXID workload with a very different consumption rate.
  • Ignoring pg_multixact member-space pressure while age still appears comfortable.

Related parameters

autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age · vacuum_multixact_failsafe_age · vacuum_freeze_table_age · autovacuum · log_autovacuum_min_duration

References

14.34 - vacuum_truncate

vacuum_truncate — Enables vacuum to truncate empty pages at the end of the table. Observed in PG18–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables vacuum to truncate empty pages at the end of the table.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVacuuming / Default Behavior
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG18
Present in PG18–19 Beta 3
Removed in No
Introduction commit 0164a0f9ee12 — Add vacuum_truncate configuration parameter.
Commit date 2025-03-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG18–19 Beta 3 on — on

How it works

Enables vacuum to truncate empty pages at the end of the table. It can be changed at session scope, so different sessions may observe different behavior.

At the end of VACUUM, PostgreSQL may take an ACCESS EXCLUSIVE lock and remove wholly empty pages from the physical tail of a table. Disabling truncation avoids that lock episode but leaves the file allocated for later reuse.

Monitor and change vacuum_truncate together with vacuum_max_eager_freeze_failure_rate, vacuum_freeze_table_age, autovacuum_freeze_max_age. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune vacuum_truncate from table size, change rate, and maintenance SLA, using per-table thresholds for large/hot relations. Observe trigger intervals, dead tuples, and ANALYZE/VACUUM duration.
OLAP Run explicit ANALYZE/VACUUM after bulk loads instead of waiting only for proportional triggers; plan freezing and visibility-map advancement separately for append-only partitions.
Small nodes Start with upstream or the measured Pigsty matrix value. Fixed thresholds dominate on small tables; after changes, confirm worker and I/O headroom.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Assuming truncation removes empty pages in the middle of a relation; only a contiguous empty tail can be removed.
  • Ignoring the ACCESS EXCLUSIVE lock attempt and blocking latency on a busy table.
  • Disabling truncation and expecting the operating system file size to shrink anyway.
  • Forgetting a table-level vacuum_truncate storage parameter can override the session/global value.
  • Relying on truncation during wraparound failsafe, when VACUUM can skip it to finish sooner.

Related parameters

vacuum_max_eager_freeze_failure_rate · vacuum_freeze_table_age · autovacuum_freeze_max_age · maintenance_work_mem · autovacuum · autovacuum_analyze_scale_factor

References

15 - Version and Platform Compatibility

Complete dossiers for 12 core PostgreSQL settings in Version and Platform Compatibility.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

15.1 - allow_alter_system

allow_alter_system allows running the ALTER SYSTEM command. It is a sighup setting present in PG17–18; the latest recorded boot default is on.
Note

Fact — official short description: “Allows running the ALTER SYSTEM command.”

Identity

Type Valuebool
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 ValueVersion and Platform Compatibility / Other Platforms and Clients
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit d3ae2a24f265 — Add allow_alter_system GUC.
Commit date 2024-03-29
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 on — on

How it works

Allows running the ALTER SYSTEM command. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

When off, PostgreSQL rejects ALTER SYSTEM before it can rewrite postgresql.auto.conf. The switch neither erases existing auto.conf entries nor prevents an operating-system administrator from editing configuration files, so it is an SQL administration boundary rather than a filesystem security boundary.

Monitor and change allow_alter_system together with config_file, data_directory, hba_file. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP A managed environment whose configuration controller owns postgresql.conf/auto.conf may disable it to narrow the SQL administration surface. Audit existing auto.conf and still restrict filesystem and superuser access.
OLAP Use the same policy as OLTP. If batch tooling calls ALTER SYSTEM, migrate it to the declarative configuration interface first so jobs do not begin failing silently after reload.
Small nodes A single-admin instance may keep the default, but ALTER SYSTEM is not a change-audit system; retain versioned configuration, rollback, and restart/reload records.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

config_file · data_directory · hba_file · ident_file · external_pid_file · transform_null_equals

References

15.2 - array_nulls

array_nulls — Enables input of NULL elements in arrays. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables input of NULL elements in arrays.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

Enables input of NULL elements in arrays. It can be changed at session scope, so different sessions may observe different behavior.

With the normal on value, an unquoted NULL token in an array input denotes a SQL null element; quoting it denotes the text ‘NULL’. The off value restores pre-8.2 input behavior and exists only for migration of legacy clients.

Monitor and change array_nulls together with backslash_quote, escape_string_warning, standard_conforming_strings. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the modern default and repair legacy clients/SQL that depend on array_nulls. Test migration at session scope first; do not make a compatibility switch permanent cluster policy.
OLAP Regression-test ETL, generated SQL, and old drivers, where parsing/quoting assumptions hide. Performance is rarely a reason to change this switch.
Small nodes Keep the default without a legacy requirement. If temporarily enabled, record owner, affected connections, and a removal date.

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

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

backslash_quote · escape_string_warning · standard_conforming_strings · transform_null_equals · quote_all_identifiers · default_with_oids

References

15.3 - backslash_quote

backslash_quote — Sets whether “'” is allowed in string literals. Observed in PG9.0–19 Beta 3; its last measured boot default is safe_encoding in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets whether “'” is allowed in string literals.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuesafe_encoding, on, off
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valuesafe_encoding
safe_encoding

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 safe_encoding — safe_encoding

How it works

Sets whether “'” is allowed in string literals. It can be changed at session scope, so different sessions may observe different behavior.

The safe_encoding mode accepts ' only when the client encoding cannot contain a backslash byte inside a multibyte character. This defense belongs to old string-literal syntax; E’…’ is the explicit escape-string form and standard_conforming_strings governs ordinary strings.

Monitor and change backslash_quote together with array_nulls, escape_string_warning, standard_conforming_strings. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the modern default and repair legacy clients/SQL that depend on backslash_quote. Test migration at session scope first; do not make a compatibility switch permanent cluster policy.
OLAP Regression-test ETL, generated SQL, and old drivers, where parsing/quoting assumptions hide. Performance is rarely a reason to change this switch.
Small nodes Keep the default without a legacy requirement. If temporarily enabled, record owner, affected connections, and a removal date.

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

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

array_nulls · escape_string_warning · standard_conforming_strings · transform_null_equals · quote_all_identifiers · default_with_oids

References

15.4 - default_with_oids

default_with_oids — Create new tables with OIDs by default. Observed in PG9.0–11; its last measured boot default is off in PG11, with user context. It was removed in PG12.
Note

Fact — official short description: “Create new tables with OIDs by default.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–11
Removed in PG12
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–11 off — off

How it works

Create new tables with OIDs by default. The parameter still exists in PG11 and is no longer recognized from PG12. PostgreSQL 12 removed user-table OIDs; use an identity column, sequence, or another explicit key instead.

While present, this changed CREATE TABLE without an explicit WITH/WITHOUT OIDS clause. Table OIDs were neither a durable application key nor guaranteed unique, and the feature disappeared with user-table OIDs in PostgreSQL 12.

Before upgrading, inspect lo_compat_privileges, operator_precedence_warning, synchronize_seqscans, remove the old name from configuration, ALTER SYSTEM, role/database settings, and automation templates, and verify the replacement before starting PG12 or later.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or continue emitting default_with_oids on PG12+. PostgreSQL 12 removed user-table OIDs; use an identity column, sequence, or another explicit key instead. Scan every configuration layer and regression-test the application before upgrade.
OLAP Use the same migration path as OLTP, and also verify long batches, standbys, or large-object/extension workflows; removal of the old switch does not promise identical legacy behavior.
Small nodes Delete the obsolete setting and adopt the supported replacement directly; do not emulate legacy behavior in scripts without a demonstrated compatibility requirement.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG11; 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: PG9.0–11 unmodified; OLAP: PG9.0–11 unmodified; CRIT: PG9.0–11 unmodified; TINY: PG9.0–11 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Continuing to emit unknown parameter default_with_oids on PG12+.
  • Deleting only the setting name without migrating dependent application behavior.
  • Assuming the historical default equals the replacement mechanism’s default.
  • Missing stale entries in ALTER SYSTEM, role/database settings, or automation templates.

Related parameters

lo_compat_privileges · operator_precedence_warning · synchronize_seqscans · standard_conforming_strings · array_nulls · backslash_quote

References

15.5 - escape_string_warning

escape_string_warning — Warn about backslash escapes in ordinary string literals. Observed in PG9.0–18; its last measured boot default is on in PG18, with user context. It was removed in PG19 Beta 3.
Note

Fact — official short description: “Warn about backslash escapes in ordinary string literals.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–18
Removed in PG19 Beta 3
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–18 on — on

How it works

Warn about backslash escapes in ordinary string literals. It can be changed at session scope, so different sessions may observe different behavior.

When standard_conforming_strings is off, this warns about backslashes in ordinary strings so applications can migrate to standard literals or explicit E’…’ strings. It diagnoses legacy SQL; it does not change parsing by itself.

Monitor and change escape_string_warning together with array_nulls, backslash_quote, standard_conforming_strings. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the modern default and repair legacy clients/SQL that depend on escape_string_warning. Test migration at session scope first; do not make a compatibility switch permanent cluster policy.
OLAP Regression-test ETL, generated SQL, and old drivers, where parsing/quoting assumptions hide. Performance is rarely a reason to change this switch.
Small nodes Keep the default without a legacy requirement. If temporarily enabled, record owner, affected connections, and a removal date.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG18; 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: PG9.0–18 unmodified; OLAP: PG9.0–18 unmodified; CRIT: PG9.0–18 unmodified; TINY: PG9.0–18 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

array_nulls · backslash_quote · standard_conforming_strings · transform_null_equals · quote_all_identifiers · default_with_oids

References

15.6 - lo_compat_privileges

lo_compat_privileges — Enables backward compatibility mode for privilege checks on large objects. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables backward compatibility mode for privilege checks on large objects.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

Enables backward compatibility mode for privilege checks on large objects. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

The compatibility mode restores pre-9.0 large-object privilege behavior for old applications. It weakens normal ownership/ACL enforcement around large objects and should be a temporary bridge while explicit GRANTs and ownership are corrected.

Monitor and change lo_compat_privileges together with default_with_oids, operator_precedence_warning, synchronize_seqscans. Validate on the relevant server role and real workload, then use its superuser context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the modern default and repair legacy clients/SQL that depend on lo_compat_privileges. Test migration at session scope first; do not make a compatibility switch permanent cluster policy.
OLAP Regression-test ETL, generated SQL, and old drivers, where parsing/quoting assumptions hide. Performance is rarely a reason to change this switch.
Small nodes Keep the default without a legacy requirement. If temporarily enabled, record owner, affected connections, and a removal date.

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

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

default_with_oids · operator_precedence_warning · synchronize_seqscans · standard_conforming_strings · array_nulls · backslash_quote

References

15.7 - operator_precedence_warning

operator_precedence_warning — Emit a warning for constructs that changed meaning since PostgreSQL 9.4. Observed in PG9.5–13; its last measured boot default is off in PG13, with user context. It was removed in PG14.
Note

Fact — official short description: “Emit a warning for constructs that changed meaning since PostgreSQL 9.4.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–13
Removed in PG14
Introduction commit c6b3c939b7e0 — Make operator precedence follow the SQL standard more closely.
Commit date 2015-03-11
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–13 off — off

How it works

Emit a warning for constructs that changed meaning since PostgreSQL 9.4. The parameter still exists in PG13 and is no longer recognized from PG14. PostgreSQL 14 removed the migration warning; rewrite ambiguous expressions with explicit parentheses and test them on the target release.

This emitted migration warnings for expressions whose operator binding changed in PostgreSQL 9.5. It never restored old precedence, and after its removal the durable fix is explicit parentheses plus regression tests.

Before upgrading, inspect default_with_oids, lo_compat_privileges, synchronize_seqscans, remove the old name from configuration, ALTER SYSTEM, role/database settings, and automation templates, and verify the replacement before starting PG14 or later.

Tuning advice

Tip

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

Workload Guidance
OLTP Do not tune or continue emitting operator_precedence_warning on PG14+. PostgreSQL 14 removed the migration warning; rewrite ambiguous expressions with explicit parentheses and test them on the target release. Scan every configuration layer and regression-test the application before upgrade.
OLAP Use the same migration path as OLTP, and also verify long batches, standbys, or large-object/extension workflows; removal of the old switch does not promise identical legacy behavior.
Small nodes Delete the obsolete setting and adopt the supported replacement directly; do not emulate legacy behavior in scripts without a demonstrated compatibility requirement.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG13; 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: PG9.5–13 unmodified; OLAP: PG9.5–13 unmodified; CRIT: PG9.5–13 unmodified; TINY: PG9.5–13 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Continuing to emit unknown parameter operator_precedence_warning on PG14+.
  • Deleting only the setting name without migrating dependent application behavior.
  • Assuming the historical default equals the replacement mechanism’s default.
  • Missing stale entries in ALTER SYSTEM, role/database settings, or automation templates.

Related parameters

default_with_oids · lo_compat_privileges · synchronize_seqscans · standard_conforming_strings · array_nulls · backslash_quote

References

15.8 - quote_all_identifiers

quote_all_identifiers — When generating SQL fragments, quote all identifiers. Observed in PG9.1–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “When generating SQL fragments, quote all identifiers.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.1
Present in PG9.1–19 Beta 3
Removed in No
Introduction commit ce68df468a41 — Add options to force quoting of all identifiers.
Commit date 2010-07-22
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.1–19 Beta 3 off — off

How it works

When generating SQL fragments, quote all identifiers. It can be changed at session scope, so different sessions may observe different behavior.

This asks server-side SQL deparsers to double-quote every identifier instead of only those that require quoting. It helps transport SQL across keyword/version differences but does not quote values or make arbitrary string concatenation safe.

Monitor and change quote_all_identifiers together with array_nulls, backslash_quote, escape_string_warning. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the modern default and repair legacy clients/SQL that depend on quote_all_identifiers. Test migration at session scope first; do not make a compatibility switch permanent cluster policy.
OLAP Regression-test ETL, generated SQL, and old drivers, where parsing/quoting assumptions hide. Performance is rarely a reason to change this switch.
Small nodes Keep the default without a legacy requirement. If temporarily enabled, record owner, affected connections, and a removal date.

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: PG9.1–19 Beta 3 unmodified; OLAP: PG9.1–19 Beta 3 unmodified; CRIT: PG9.1–19 Beta 3 unmodified; TINY: PG9.1–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

array_nulls · backslash_quote · escape_string_warning · standard_conforming_strings · transform_null_equals · default_with_oids

References

15.9 - sql_inheritance

sql_inheritance — Causes subtables to be included by default in various commands. Observed in PG9.0–9.6; its last measured boot default is on in PG9.6, with user context. It was removed in PG10.
Note

Fact — official short description: “Causes subtables to be included by default in various commands.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.6
Removed in PG10
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.6 on — on

How it works

PostgreSQL describes sql_inheritance as follows: “Causes subtables to be included by default in various commands.” It can be changed per session, which makes plan or behavior comparisons possible without changing every workload. The atlas measures it in PG9.0–9.6; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

When enabled, this compatibility switch made commands operate on inheritance descendants unless ONLY was written. PostgreSQL 10 removed the switch: modern SQL uses ONLY to exclude descendants, while declarative partition pruning and constraint exclusion govern which child relations are scanned.

Read it together with constraint_exclusion, enable_partition_pruning, search_path, default_table_access_method. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.6; 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: PG9.0–9.6 unmodified; OLAP: PG9.0–9.6 unmodified; CRIT: PG9.0–9.6 unmodified; TINY: PG9.0–9.6 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for sql_inheritance as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports user context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

constraint_exclusion · enable_partition_pruning · search_path · default_table_access_method

References

15.10 - standard_conforming_strings

standard_conforming_strings — Nonstandard strings are no longer supported; this can only be true. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Nonstandard strings are no longer supported; this can only be true.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 off — off
PG9.1–19 Beta 3 on — on

How it works

Causes ‘…’ strings to treat backslashes literally. It can be changed at session scope, so different sessions may observe different behavior.

With on, backslashes in ordinary ‘…’ strings are literal and escape processing requires E’…’. Turning it off restores legacy parsing, making client/server disagreement and unsafe SQL construction more likely.

Monitor and change standard_conforming_strings together with array_nulls, backslash_quote, escape_string_warning. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the modern default and repair legacy clients/SQL that depend on standard_conforming_strings. Test migration at session scope first; do not make a compatibility switch permanent cluster policy.
OLAP Regression-test ETL, generated SQL, and old drivers, where parsing/quoting assumptions hide. Performance is rarely a reason to change this switch.
Small nodes Keep the default without a legacy requirement. If temporarily enabled, record owner, affected connections, and a removal date.

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

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

array_nulls · backslash_quote · escape_string_warning · transform_null_equals · quote_all_identifiers · default_with_oids

References

15.11 - synchronize_seqscans

synchronize_seqscans — Enables synchronized sequential scans. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Enables synchronized sequential scans.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Previous PostgreSQL Versions
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

Enables synchronized sequential scans. It can be changed at session scope, so different sessions may observe different behavior.

Concurrent sequential scans of the same large relation may join a shared scan position, improving cache reuse while returning rows in a less predictable physical order. SQL without ORDER BY has no ordering guarantee regardless of this switch.

Monitor and change synchronize_seqscans together with default_with_oids, lo_compat_privileges, operator_precedence_warning. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Normally keep it on so concurrent large-table scans can share cache footprint. Queries that require deterministic order must use ORDER BY; disabling this setting is not an ordering contract.
OLAP Analytical concurrency is the most likely beneficiary. Experiment at session scope only when repeatable benchmarks show the shared scan position harms locality.
Small nodes Keep the default. When data fits in cache or concurrent scans are rare, this setting usually needs no attention and is not a bottleneck.

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

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

default_with_oids · lo_compat_privileges · operator_precedence_warning · standard_conforming_strings · array_nulls · backslash_quote

References

15.12 - transform_null_equals

transform_null_equals — Treats “expr=NULL” as “expr IS NULL”. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Treats “expr=NULL” as “expr IS NULL”.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueVersion and Platform Compatibility / Other Platforms and Clients
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

Treats “expr=NULL” as “expr IS NULL”. It can be changed at session scope, so different sessions may observe different behavior.

The parser rewrites expr = NULL to expr IS NULL for broken legacy clients. SQL’s normal three-valued semantics make equality with NULL yield unknown, so enabling this can hide application defects and does not rewrite other NULL comparisons.

Monitor and change transform_null_equals together with array_nulls, backslash_quote, escape_string_warning. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep the modern default and repair legacy clients/SQL that depend on transform_null_equals. Test migration at session scope first; do not make a compatibility switch permanent cluster policy.
OLAP Regression-test ETL, generated SQL, and old drivers, where parsing/quoting assumptions hide. Performance is rarely a reason to change this switch.
Small nodes Keep the default without a legacy requirement. If temporarily enabled, record owner, affected connections, and a removal date.

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

  • Keeping a compatibility switch permanently instead of fixing the client.
  • Testing in one session and deploying globally to unrelated applications.
  • Confusing parsing compatibility with data or security compatibility.
  • Forgetting to remove an override after the upgrade migration is complete.

Related parameters

array_nulls · backslash_quote · escape_string_warning · standard_conforming_strings · quote_all_identifiers · allow_alter_system

References

16 - Write-Ahead Log

Complete dossiers for 41 core PostgreSQL settings in Write-Ahead Log.

Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.

16.1 - archive_cleanup_command

archive_cleanup_command sets the shell command that will be executed at every restart point. It is a sighup setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the shell command that will be executed at every restart point.”

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 ValueWrite-Ahead Log / Archive Recovery
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the shell command that will be executed at every restart point. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

At every restartpoint during archive recovery, PostgreSQL expands %r to the oldest WAL file still needed for a restartable recovery and runs this command. pg_archivecleanup is the usual implementation, but deleting from an archive shared by several standbys can strand another consumer.

Monitor and change archive_cleanup_command together with archive_mode, archive_command, archive_library. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Manage archive_cleanup_command as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.
OLAP Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.
Small nodes Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Running destructive cleanup against an archive shared by other standbys or restore jobs.
  • Misreading %r as the last replayed file; it is the earliest file needed to keep recovery restartable.
  • Using a command that is not idempotent when a restartpoint repeats or an archive file is already absent.
  • Assuming a reload executes the command immediately; it runs at recovery restartpoints.
  • Letting shell quoting or an unexpected archive path turn cleanup into deletion outside the intended archive.

Related parameters

archive_mode · archive_command · archive_library · archive_timeout · restore_command · recovery_end_command

References

16.2 - archive_command

archive_command — Sets the shell command that will be called to archive a WAL file. Observed in PG9.0–19 Beta 3; its last measured boot default is empty string in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the shell command that will be called to archive a WAL file.”

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 ValueWrite-Ahead Log / Archiving
Upstream classification
Latest boot value Value""
empty string

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

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

How it works

Sets the shell command that will be called to archive a WAL file. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The archiver expands %p to the source path and %f to the WAL file name, and considers exit status zero a durable success. A nonzero result is retried; a false success allows PostgreSQL to recycle the only local copy and silently breaks the archive chain.

Monitor and change archive_command together with archive_mode, archive_library, archive_timeout. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Manage archive_command as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.
OLAP Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.
Small nodes Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.

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 pgbackrest --stanza=fixture archive-push %p different 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
OLAP pgbackrest --stanza=fixture archive-push %p different 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
CRIT pgbackrest --stanza=fixture archive-push %p different 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
TINY pgbackrest --stanza=fixture archive-push %p different 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs); OLAP: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs); CRIT: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs); TINY: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to bind archiving to the pgBackRest stanza used by Pigsty for PITR; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Returning success before the archive copy is durable or verified.
  • Failing to quote %p/%f safely in a shell command.
  • Letting repeated failures fill pg_wal and stop the server.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

archive_mode · archive_library · archive_timeout · archive_cleanup_command · restore_command · recovery_end_command

References

16.3 - archive_library

archive_library sets the library that will be called to archive a WAL file. It is a sighup setting present in PG15–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the library that will be called to archive a WAL file.”

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 ValueWrite-Ahead Log / Archiving
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit 5ef1eefd76f4 — Allow archiving via loadable modules.
Commit date 2022-02-03
Discussion thread 1

Default history

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

How it works

Sets the library that will be called to archive a WAL file. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

A nonempty library selects an archive module through its _PG_archive_module_init callback instead of a shell command. archive_command and archive_library are alternative implementations; changing either is reloadable, while archive_mode must already be active.

Monitor and change archive_library together with archive_mode, archive_command, archive_timeout. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Manage archive_library as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.
OLAP Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.
Small nodes Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Configuring both a library and expecting archive_command to run as a fallback.
  • Loading untrusted in-process archive code.
  • Treating module success as proof that restores work.
  • Reloading to a new module without verifying backlog processing, failure reporting, and rollback behavior.
  • Letting repeated module failures retain WAL until pg_wal fills, without an archive-lag alert.

Related parameters

archive_mode · archive_command · archive_timeout · archive_cleanup_command · restore_command · recovery_end_command

References

16.4 - archive_mode

archive_mode — Allows archiving of WAL files using “archive_command”. Observed in PG9.0–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Allows archiving of WAL files using “archive_command”.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuealways, on, off
— for non-enum types
Category ValueWrite-Ahead Log / Archiving
Upstream classification
Latest boot value Valueoff
off

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 off — off

How it works

When enabled, PostgreSQL runs the WAL archiver and submits each completed segment to archive_command or, in versions that provide it, archive_library before that segment can be recycled. The mode is separate from the command or library, so the archive destination logic can be reloaded while archiving remains enabled.

The on and always modes behave the same during normal primary operation. In recovery or standby mode, on does not archive received WAL, while always also archives segments restored from an archive or received through streaming replication.

Enabling the mode does not prove that an archive is healthy or recoverable. A command that fails causes WAL to accumulate in pg_wal; a command that falsely reports success can create an unrecoverable archive chain. Point-in-time recovery also requires a suitable base backup and tested restore procedure.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable it for a defined PITR or log-shipping requirement, pair it with a reliable idempotent archive implementation, and alert on pg_stat_archiver failures, archive age, and pg_wal growth. Test restores rather than treating successful command exits as sufficient evidence.
OLAP Provision archive bandwidth and destination capacity for bulk-load WAL bursts. If the archive cannot keep up, throttling or scheduling the batch is safer than allowing pg_wal to fill.
Small nodes Use a simple managed tool such as pgBackRest only when retention and restore procedures are understood. Keep the archive off for disposable databases rather than enabling it with a placeholder command.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = on (dcs); OLAP: PG9.0–19 Beta 3 = on (dcs); CRIT: PG9.0–19 Beta 3 = on (dcs); TINY: PG9.0–19 Beta 3 = on (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

  • Enabling archive_mode with an empty or failing command and letting pg_wal fill.
  • Using a command such as /bin/true, which reports success while breaking the recoverable WAL chain.
  • Assuming archive_mode is reloadable even though changing it requires a server restart.
  • Treating WAL archiving as a substitute for a base backup and restore test.
  • Using always with a shared archive without duplicate-safe, race-free handling.

Related parameters

archive_command · archive_library · archive_timeout · wal_level · restore_command · max_wal_size

References

16.5 - archive_timeout

archive_timeout — Sets the amount of time to wait before forcing a switch to the next WAL file. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the amount of time to wait before forcing a switch to the next WAL file.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value0 – 1073741823
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Archiving
Upstream classification
Latest boot value Value0
0 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 s 0 s

How it works

Sets the amount of time to wait before forcing a switch to the next WAL file. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

When no natural segment switch occurs within the interval, PostgreSQL forces one so the current partial segment can be archived. It does not make WAL records durable sooner, and very small values waste archive space because archived segment files retain full segment size.

Monitor and change archive_timeout together with archive_mode, archive_command, archive_library. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Manage archive_timeout as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.
OLAP Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.
Small nodes Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.

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 300 different 300
OLAP 300 different 300
CRIT 300 different 300
TINY 300 different 300
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 300 (dcs); OLAP: PG9.0–19 Beta 3 = 300 (dcs); CRIT: PG9.0–19 Beta 3 = 300 (dcs); TINY: PG9.0–19 Beta 3 = 300 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to bound how long a quiet primary can leave its newest WAL unavailable to the archive; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Treating it as a commit-durability timeout.
  • Choosing a tiny interval and multiplying archive storage by mostly empty full-size segments.
  • Assuming forced switches solve a slow or failed archiver.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

archive_mode · archive_command · archive_library · archive_cleanup_command · restore_command · recovery_end_command

References

16.6 - checkpoint_completion_target

checkpoint_completion_target — Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval. Observed in PG9.0–19 Beta 3; its last measured boot default is 0.9 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval.”

Identity

Type Valuereal
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value—
Raw unit
Range Value0 – 1
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Checkpoints
Upstream classification
Latest boot value Value0.9
0.9

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–13 0.5 — 0.5
PG14–19 Beta 3 0.9 — 0.9

How it works

PostgreSQL throttles checkpoint writes so that they are expected to finish after this fraction of the available interval. The available interval ends at the next timed checkpoint or sooner if WAL volume forces a checkpoint, so this is a pacing target rather than a fixed duration.

A larger fraction generally smooths checkpoint I/O over more time. A smaller fraction finishes writes faster, producing a higher I/O rate followed by an idle gap; the official documentation discourages reducing it for that reason.

Values too close to 1 leave little room for final synchronization and other checkpoint work. PostgreSQL’s historical default change from 0.5 to 0.9 is material when comparing otherwise identical configurations across major versions.

Tuning advice

Tip

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

Workload Guidance
OLTP Start with the version default of 0.9 and optimize only with latency and pg_stat_checkpointer evidence. A value of 0.95 can smooth writes further, but verify that checkpoints consistently finish before the next trigger.
OLAP For bursty bulk workloads, raising max_wal_size is often the first lever because a volume-triggered checkpoint shortens the pacing window. Keep this target high enough to smooth I/O but not so high that final sync work bunches at the end.
Small nodes Use 0.9 unless measurements show a clear benefit. Small or slow storage is especially vulnerable to an end-of-checkpoint sync spike when the target leaves insufficient margin.

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 0.95 different 0.95
OLAP 0.95 different 0.95
CRIT 0.95 different 0.95
TINY 0.95 different 0.95
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 0.95 (dcs); OLAP: PG9.0–19 Beta 3 = 0.95 (dcs); CRIT: PG9.0–19 Beta 3 = 0.95 (dcs); TINY: PG9.0–19 Beta 3 = 0.95 (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

  • Interpreting the value as seconds rather than a fraction.
  • Assuming a lower value reduces total I/O instead of concentrating it.
  • Setting 1.0 and leaving no margin for checkpoint completion overhead.
  • Ignoring early volume-triggered checkpoints from max_wal_size.
  • Overlooking the default change at PostgreSQL 14.

Related parameters

checkpoint_timeout · max_wal_size · checkpoint_flush_after · checkpoint_warning · shared_buffers

References

16.7 - checkpoint_flush_after

checkpoint_flush_after — Number of pages after which previously performed writes are flushed to disk. Observed in PG9.6–19 Beta 3; its last measured boot default is 256 KiB (32 × 8kB) in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Number of pages after which previously performed writes are flushed to disk.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value8kB
Raw unit
Range Value0 – 256
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Checkpoints
Upstream classification
Latest boot value Value32
256 KiB (32 × 8kB)

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit 428b1d6b29ca — Allow to trigger kernel writeback after a configurable number of writes.
Commit date 2016-02-19
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 32 8kB 256 KiB (32 × 8kB)

How it works

Number of pages after which previously performed writes are flushed to disk. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Checkpoint writes are periodically handed to the operating system for writeback after this much data, smoothing the final sync and reducing dirty-cache bursts. Zero disables these intermediate flush requests; the best value is operating-system and storage dependent.

Monitor and change checkpoint_flush_after together with checkpoint_warning, checkpoint_timeout, checkpoint_completion_target. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune checkpoint_flush_after from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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: PG9.6–19 Beta 3 unmodified; OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 unmodified; TINY: PG9.6–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the raw value as bytes even though an unqualified value is measured in database blocks.
  • Setting it too small and increasing writeback calls and I/O fragmentation.
  • Setting it too large and losing the intended smoothing before the checkpoint sync phase.
  • Confusing writeback hints with a durability guarantee; fsync and wal_sync_method still define persistence.
  • Copying a value across operating systems or filesystems without measuring checkpoint latency and dirty-page behavior.

Related parameters

checkpoint_warning · checkpoint_timeout · checkpoint_completion_target · max_wal_size · min_wal_size · archive_cleanup_command

References

16.8 - checkpoint_segments

checkpoint_segments — Sets the maximum distance in log segments between automatic WAL checkpoints. Observed in PG9.0–9.4; its last measured boot default is 3 in PG9.4, with sighup context. It was removed in PG9.5.
Note

Fact — official short description: “Sets the maximum distance in log segments between automatic WAL checkpoints.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value""
Raw unit
Range Value1 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Checkpoints
Upstream classification
Latest boot value Value3
3

Lifecycle

Fact Value
First observed PG9.0 (research boundary)
Present in PG9.0–9.4
Removed in PG9.5
Introduction commit Not asserted: predates the PG9.0 research boundary
Commit date —
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.4 3 — 3

How it works

PostgreSQL describes checkpoint_segments as follows: “Sets the maximum distance in log segments between automatic WAL checkpoints.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG9.0–9.4; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

This was the pre-9.5 checkpoint volume control: once accumulated WAL approached the configured number of segments, PostgreSQL requested an automatic checkpoint. PostgreSQL 9.5 replaced it with max_wal_size, whose soft byte-size budget works with checkpoint_timeout and checkpoint_completion_target rather than exposing a segment count.

Read it together with max_wal_size, checkpoint_timeout, checkpoint_completion_target, wal_segment_size. 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

Tip

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

Workload Guidance
OLTP Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.
OLAP For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.
Small nodes Delete the obsolete override after recording why it existed. On a small node, prefer the successor’s default until measurements justify a new value; an unknown startup parameter can otherwise stop the server.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG9.4; 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: PG9.0–9.4 unmodified; OLAP: PG9.0–9.4 unmodified; CRIT: PG9.0–9.4 unmodified; TINY: PG9.0–9.4 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the measured boot_val for checkpoint_segments as proof of the effective value on an initialized or managed cluster.
  • Applying a change as though it were immediate while pg_settings reports sighup context.
  • Changing this setting in isolation without checking the linked limits, observability, and rollback path.
  • Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor.

Related parameters

max_wal_size · checkpoint_timeout · checkpoint_completion_target · wal_segment_size · min_wal_size

References

16.9 - checkpoint_timeout

checkpoint_timeout — Sets the maximum time between automatic WAL checkpoints. Observed in PG9.0–19 Beta 3; its last measured boot default is 5 min in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum time between automatic WAL checkpoints.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value30 – 86400
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Checkpoints
Upstream classification
Latest boot value Value300
5 min

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 300 s 5 min

How it works

An automatic checkpoint is considered after checkpoint_timeout, but max_wal_size can force one earlier. If no WAL has been written since the preceding checkpoint, PostgreSQL can skip the timed checkpoint, so this setting is a maximum scheduling interval rather than a promise of periodic physical work.

Longer intervals usually reduce checkpoint frequency and full-page-write amplification, while increasing the amount of WAL that crash recovery may need to replay. Shorter intervals bound that replay horizon more tightly but increase dirty-page flushing and post-checkpoint full-page images.

Checkpoint records also constrain restartpoints on standbys. This parameter should not be used to set a WAL-archive recovery point objective; archive_timeout is the control intended to force segment switches for low-WAL systems.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune it together with max_wal_size and keep checkpoint I/O spread with checkpoint_completion_target. Extend the interval only after measuring recovery requirements, requested versus timed checkpoints, write latency, and WAL volume.
OLAP During bulk work, max_wal_size often triggers before the timer. Increase WAL capacity first if volume-driven checkpoints dominate, and retain a timeout that still meets restart and recovery expectations.
Small nodes The upstream 5-minute default is a defensible starting point where recovery time matters and storage is limited. A longer interval needs explicit disk headroom and a tested crash-recovery budget.

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 15min different 15min
OLAP 15min different 15min
CRIT 15min different 15min
TINY 15min different 15min
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 15min (dcs); OLAP: PG9.0–19 Beta 3 = 15min (dcs); CRIT: PG9.0–19 Beta 3 = 15min (dcs); TINY: PG9.0–19 Beta 3 = 15min (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

  • Assuming a checkpoint occurs exactly every configured interval even on an idle system.
  • Forgetting that max_wal_size can trigger a checkpoint earlier.
  • Using checkpoint_timeout instead of archive_timeout to bound archive delay.
  • Increasing it without allowing for a longer crash-recovery replay horizon.
  • Reducing it so far that full-page writes and checkpoint I/O dominate.

Related parameters

max_wal_size · checkpoint_completion_target · checkpoint_warning · archive_timeout · full_page_writes · checkpoint_flush_after

References

16.10 - checkpoint_warning

checkpoint_warning — Sets the maximum time before warning if checkpoints triggered by WAL volume happen too frequently. Observed in PG9.0–19 Beta 3; its last measured boot default is 30 s in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the maximum time before warning if checkpoints triggered by WAL volume happen too frequently.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Values
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Checkpoints
Upstream classification
Latest boot value Value30
30 s

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 30 s 30 s

How it works

Sets the maximum time before warning if checkpoints triggered by WAL volume happen too frequently. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

This parameter only emits a log warning when WAL-volume checkpoints occur closer together than the threshold. It does not delay checkpoints; frequent warnings normally point to max_wal_size being too small for the WAL generation rate.

Monitor and change checkpoint_warning together with checkpoint_flush_after, checkpoint_timeout, checkpoint_completion_target. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune checkpoint_warning from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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

  • Treating the warning threshold as a control that delays or throttles checkpoints.
  • Setting zero and silencing evidence of WAL-volume checkpoints.
  • Raising the threshold instead of investigating WAL rate, max_wal_size, and requested-checkpoint frequency.
  • Setting checkpoint_warning above checkpoint_timeout and expecting time-based checkpoints to produce this warning.

Related parameters

checkpoint_flush_after · checkpoint_timeout · checkpoint_completion_target · max_wal_size · min_wal_size · archive_cleanup_command

References

16.11 - commit_delay

commit_delay — Sets the delay in microseconds between transaction commit and flushing WAL to disk. Observed in PG9.0–19 Beta 3; its last measured boot default is 0 in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the delay in microseconds between transaction commit and flushing WAL to disk.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value0 – 100000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Value0
0

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 0 — 0

How it works

Sets the delay in microseconds between transaction commit and flushing WAL to disk. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

A backend that is about to flush commit WAL may wait this many microseconds so concurrent commits can join the same durable flush. The delay is considered only when at least commit_siblings other transactions are active, trading individual latency for possible group-commit efficiency.

Monitor and change commit_delay together with commit_siblings, synchronous_commit, wal_writer_delay. Validate on the relevant server role and real workload, then use its superuser context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Benchmark commit_delay only under high commit concurrency with material WALSync waits and an acceptable p95/p99 latency budget. Tune commit_delay and commit_siblings as a pair and retain a zero-delay baseline.
OLAP Bulk jobs should usually reduce commit frequency with sensible transaction batches; do not use group-commit delay to compensate for row-at-a-time ETL commits.
Small nodes Low concurrency provides little opportunity, so commit_delay=0 is simplest. Even a microsecond value needs end-to-end latency evidence.

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 20 different 20
OLAP 20 different 20
CRIT 20 different 20
TINY 20 different 20
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 20 (dcs); OLAP: PG9.0–19 Beta 3 = 20 (dcs); CRIT: PG9.0–19 Beta 3 = 20 (dcs); TINY: PG9.0–19 Beta 3 = 20 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to encourage very short group-commit batching under concurrent commit load; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Setting a delay while commit_siblings prevents it from being reached under the real concurrency level.
  • Reading the value as milliseconds even though the unit is microseconds.
  • Increasing average group-commit throughput while violating p95 or p99 commit-latency objectives.
  • Expecting a delay when the commit path does not need to flush WAL.
  • Changing commit_delay without measuring it together with commit_siblings and WALSync waits.

Related parameters

commit_siblings · synchronous_commit · wal_writer_delay · wal_sync_method · fsync · full_page_writes

References

16.12 - commit_siblings

commit_siblings — Sets the minimum number of concurrent open transactions required before performing “commit_delay”. Observed in PG9.0–19 Beta 3; its last measured boot default is 5 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the minimum number of concurrent open transactions required before performing “commit_delay”.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value0 – 1000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Value5
5

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 5 — 5

How it works

Sets the minimum number of concurrent open transactions required before performing “commit_delay”. It can be changed at session scope, so different sessions may observe different behavior.

This is the concurrency gate for commit_delay, counted from other active transactions when a commit flush is needed. It is not a count of commits already waiting and has no useful effect while commit_delay is zero.

Monitor and change commit_siblings together with commit_delay, synchronous_commit, wal_writer_delay. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Benchmark commit_siblings only under high commit concurrency with material WALSync waits and an acceptable p95/p99 latency budget. Tune commit_delay and commit_siblings as a pair and retain a zero-delay baseline.
OLAP Bulk jobs should usually reduce commit frequency with sensible transaction batches; do not use group-commit delay to compensate for row-at-a-time ETL commits.
Small nodes Low concurrency provides little opportunity, so commit_delay=0 is simplest. Even a microsecond value needs end-to-end latency evidence.

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 10 different 10
OLAP 10 different 10
CRIT 10 different 10
TINY 10 different 10
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 10 (dcs); OLAP: PG9.0–19 Beta 3 = 10 (dcs); CRIT: PG9.0–19 Beta 3 = 10 (dcs); TINY: PG9.0–19 Beta 3 = 10 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to apply commit_delay only after the server has substantial concurrent transaction activity; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Tuning it while commit_delay is zero, in which case the threshold has no effect.
  • Treating it as a count of commits already waiting rather than other active transactions.
  • Setting the gate too low and adding latency during ordinary moderate concurrency.
  • Applying a session-level experiment globally without comparing commit latency and WALSync behavior.

Related parameters

commit_delay · synchronous_commit · wal_writer_delay · wal_sync_method · fsync · full_page_writes

References

16.13 - fsync

fsync — Forces synchronization of updates to disk. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Forces synchronization of updates to disk.”

Identity

Type Valuebool
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 ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

Forces synchronization of updates to disk. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

When on, PostgreSQL issues durability barriers so WAL and data ordering survive an operating-system or power failure. Turning it off may improve write benchmarks, but a crash can leave corruption that crash recovery cannot repair; re-enabling it does not retroactively synchronize earlier unsafe writes.

Monitor and change fsync together with data_sync_retry, restart_after_crash, recovery_init_sync_method. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep fsync=on for persistent production data. Address storage latency, checkpoints, WAL compression, and batching instead of exchanging crash safety for throughput.
OLAP Bulk loads still need recoverability. Use explicitly rebuildable UNLOGGED/temporary staging to narrow the durability scope rather than disabling protection cluster-wide.
Small nodes Keep it on for persistent small instances too. Only a clearly isolated, disposable cluster may make an exception after explicitly accepting rebuild risk.

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

  • Disabling it on persistent data and assuming UPS or RAID cache alone is sufficient.
  • Re-enabling it after unsafe operation and assuming earlier writes became durable.
  • Benchmarking only clean shutdowns instead of power-loss recovery.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

data_sync_retry · restart_after_crash · recovery_init_sync_method · full_page_writes · wal_sync_method · synchronous_commit

References

16.14 - full_page_writes

full_page_writes — Writes full pages to WAL when first modified after a checkpoint. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Writes full pages to WAL when first modified after a checkpoint.”

Identity

Type Valuebool
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 ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

Writes full pages to WAL when first modified after a checkpoint. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

After each checkpoint, the first change to a data page logs a complete page image, preventing torn-page recovery from combining old and new sectors. The extra WAL is concentrated after checkpoints and is affected by wal_compression; disabling it is unsafe unless the storage stack provides an equivalent atomic-page guarantee.

Monitor and change full_page_writes together with data_sync_retry, restart_after_crash, recovery_init_sync_method. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep full_page_writes=on for persistent production data. Address storage latency, checkpoints, WAL compression, and batching instead of exchanging crash safety for throughput.
OLAP Bulk loads still need recoverability. Use explicitly rebuildable UNLOGGED/temporary staging to narrow the durability scope rather than disabling protection cluster-wide.
Small nodes Keep it on for persistent small instances too. Only a clearly isolated, disposable cluster may make an exception after explicitly accepting rebuild risk.

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

  • Disabling it without an end-to-end atomic-page guarantee.
  • Confusing its WAL-volume cost with logging every page on every change.
  • Ignoring the post-checkpoint full-page-image burst.
  • Assuming a reload retroactively protects WAL records that were generated while full_page_writes was off.
  • Benchmarking with it disabled without an end-to-end crash, recovery, and torn-page test.

Related parameters

data_sync_retry · restart_after_crash · recovery_init_sync_method · fsync · wal_sync_method · synchronous_commit

References

16.15 - max_wal_size

max_wal_size — Sets the WAL size that triggers a checkpoint. Observed in PG9.5–19 Beta 3; its last measured boot default is 1 GiB in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the WAL size that triggers a checkpoint.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit ValueMB
Raw unit
Range Value2 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Checkpoints
Upstream classification
Latest boot value Value1024
1 GiB

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 88e982302684 — Replace checkpoint_segments with min_wal_size and max_wal_size.
Commit date 2015-02-23
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–9.6 64 16MB 1 GiB (64 × 16MB)
PG10–19 Beta 3 1024 MB 1 GiB

How it works

The checkpointer starts an automatic checkpoint when checkpoint_timeout expires or when WAL growth is about to exceed max_wal_size, whichever happens first. More frequent checkpoints write dirty buffers more often and also cause more full-page images after each checkpoint.

max_wal_size is not a disk quota. WAL can exceed it under heavy write load, during recovery, when archiving is slow or failing, when wal_keep_size retains files, or when a replication slot still needs old WAL.

A larger value usually reduces requested checkpoints and checkpoint-related write churn, but reserves a longer WAL replay horizon after a crash and requires more pg_wal headroom. min_wal_size controls the lower recycling floor; it does not turn max_wal_size into a hard ceiling.

Tuning advice

Tip

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

Workload Guidance
OLTP Size it from measured peak WAL generation and an acceptable checkpoint cadence. Watch pg_stat_checkpointer, checkpoint warnings, write latency, archive lag, and free space; raise it when requested checkpoints are persistently dominant, not merely because a generic formula says so.
OLAP Bulk loads and large maintenance jobs can generate WAL in bursts, so a larger value can avoid checkpoint storms. Confirm that pg_wal capacity and archive throughput can absorb the burst and that the longer crash-recovery window is acceptable.
Small nodes Keep a conservative bounded value on small disks. Account separately for slot retention and archive backlog, and leave emergency free space rather than assigning most of the volume to the nominal checkpoint threshold.

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 20GB different {{ ([pg_size_twentieth * 4, 2000])|min }}GB
OLAP 20GB different {{ ([pg_size_twentieth * 4, 2000])|min }}GB
CRIT 20GB different {{ ([pg_size_twentieth * 4, 2000])|min }}GB
TINY 20GB different {{ ([pg_size_twentieth * 4, 2000])|min }}GB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.5–19 Beta 3 = 20GB (dcs); OLAP: PG9.5–19 Beta 3 = 20GB (dcs); CRIT: PG9.5–19 Beta 3 = 20GB (dcs); TINY: PG9.5–19 Beta 3 = 20GB (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

  • Treating max_wal_size as a hard cap on pg_wal usage.
  • Raising it to conceal a failed archiver or an abandoned replication slot.
  • Lowering it without checking full-page-image volume and checkpoint latency.
  • Ignoring that a bare numeric value is interpreted in megabytes.
  • Tuning it independently of checkpoint_timeout and checkpoint_completion_target.

Related parameters

min_wal_size · checkpoint_timeout · checkpoint_completion_target · checkpoint_warning · wal_keep_size · max_slot_wal_keep_size

References

16.16 - min_wal_size

min_wal_size — Sets the minimum size to shrink the WAL to. Observed in PG9.5–19 Beta 3; its last measured boot default is 80 MiB in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the minimum size to shrink the WAL to.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit ValueMB
Raw unit
Range Value2 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Checkpoints
Upstream classification
Latest boot value Value80
80 MiB

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 88e982302684 — Replace checkpoint_segments with min_wal_size and max_wal_size.
Commit date 2015-02-23
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–9.6 5 16MB 80 MiB (5 × 16MB)
PG10–19 Beta 3 80 MB 80 MiB

How it works

Sets the minimum size to shrink the WAL to. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Below this floor, checkpoint recycling keeps old segment files ready for reuse instead of removing them. It is a retained/recycled space floor, not a cap; archive failures, replication slots, wal_keep_size, and max_wal_size can all make pg_wal much larger.

Monitor and change min_wal_size together with max_wal_size, wal_keep_size, wal_segment_size. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Size the recycled-segment floor from ordinary WAL generated between checkpoints and measured file-creation cost. Keep it well below available pg_wal space and evaluate it together with max_wal_size.
OLAP Large batch loads may benefit from a bigger reusable pool, but derive it from repeatable batch peaks rather than copying an arbitrary GB value; archive and slot retention are separate.
Small nodes Verify that Pigsty’s measured 5GB matrix value fits the actual disk. It is not free on a small volume; lowering it trades space for more segment create/remove churn.

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 5GB different {{ ([pg_size_twentieth, 200])|min }}GB
OLAP 5GB different {{ ([pg_size_twentieth, 200])|min }}GB
CRIT 5GB different {{ ([pg_size_twentieth, 200])|min }}GB
TINY 5GB different {{ ([pg_size_twentieth, 200])|min }}GB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.5–19 Beta 3 = 5GB (dcs); OLAP: PG9.5–19 Beta 3 = 5GB (dcs); CRIT: PG9.5–19 Beta 3 = 5GB (dcs); TINY: PG9.5–19 Beta 3 = 5GB (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to retain a reusable WAL pool large enough to absorb routine bursts without file churn; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Reading it as a maximum pg_wal size.
  • Sizing it without wal_segment_size rounding and burst rate.
  • Ignoring archive/slot retention that can exceed both min_wal_size and max_wal_size.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

max_wal_size · wal_keep_size · wal_segment_size · checkpoint_timeout · checkpoint_completion_target · checkpoint_flush_after

References

16.17 - recovery_end_command

recovery_end_command sets the shell command that will be executed once at the end of recovery. It is a sighup setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the shell command that will be executed once at the end of recovery.”

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 ValueWrite-Ahead Log / Archive Recovery
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the shell command that will be executed once at the end of recovery. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

PostgreSQL runs this shell command once when archive recovery finishes or a standby is promoted. %r expands to the last restart-point file name; command failure is logged but must not be treated as a transactional post-promotion hook.

Monitor and change recovery_end_command together with archive_mode, archive_command, archive_library. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Manage recovery_end_command as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.
OLAP Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.
Small nodes Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Treating the shell command as a transactional promotion hook whose failure rolls recovery back.
  • Misreading %r and deleting WAL still needed by another recovery consumer.
  • Using non-idempotent external side effects without accounting for promotion and recovery retries.
  • Assuming a reload executes the command; it runs once when archive recovery ends.
  • Embedding credentials or unsafe shell expansion in a command executed by the PostgreSQL service account.

Related parameters

archive_mode · archive_command · archive_library · archive_timeout · archive_cleanup_command · restore_command

References

16.18 - recovery_prefetch

recovery_prefetch prefetches referenced blocks during recovery. It is a sighup setting present in PG15–18; the latest recorded boot default is try.
Note

Fact — official short description: “Prefetch referenced blocks during recovery.”

Identity

Type Valueenum
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 Valueoff, on, try
— for non-enum types
Category ValueWrite-Ahead Log / Recovery
Upstream classification
Latest boot value Valuetry
try

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit 1d257577e08d — Optionally prefetch referenced data in recovery.
Commit date 2021-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG15–19 Beta 3 try — try

How it works

Prefetch referenced blocks during recovery. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

During recovery, PostgreSQL can issue read-ahead advice for blocks identified by WAL before replay needs them. try enables it only when the operating system supports the required advice; wal_decode_buffer_size and maintenance_io_concurrency bound how far and how much it can prefetch.

Monitor and change recovery_prefetch together with wal_decode_buffer_size, maintenance_io_concurrency, effective_io_concurrency. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Tune recovery_prefetch with recovery/standby catch-up benchmarks on production-like storage while observing replay I/O wait, cache behavior, and maintenance_io_concurrency. Keep the default without measured benefit.
OLAP Large data with slow random reads may benefit more, but excess prefetch competes with query I/O and cache. Test crash recovery and a query-serving standby separately.
Small nodes The default is usually sufficient. Do not spend scarce memory or I/O queue depth on a larger look-ahead window unless a recovery-time objective is demonstrably missed.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Assuming try always enables prefetch even when the operating system lacks the required read-ahead advice.
  • Increasing look-ahead without considering wal_decode_buffer_size and maintenance_io_concurrency.
  • Letting recovery prefetch compete with queries on a hot standby for cache and I/O queue depth.
  • Benchmarking sequential recovery only, where block prefetch may provide little benefit.

Related parameters

wal_decode_buffer_size · maintenance_io_concurrency · effective_io_concurrency · shared_buffers · archive_cleanup_command · archive_command

References

16.19 - recovery_target

recovery_target can be set to “immediate” to end recovery as soon as a consistent state is reached. It is a postmaster setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Set to “immediate” to end recovery as soon as a consistent state is reached.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Set to “immediate” to end recovery as soon as a consistent state is reached. The value is fixed when the server starts, so changing it requires a restart.

The only accepted value is immediate, which stops targeted recovery at the first consistent point—normally the end of an online base backup. It is mutually exclusive with the LSN, name, time, and XID target selectors.

At most one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, and recovery_target_xid may be set; timeline, inclusive, and action are modifiers. Rehearse from the same base backup through a complete WAL chain—an unreachable target makes targeted recovery fail.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Setting immediate together with an LSN, name, time, or XID selector.
  • Confusing the first consistent point after an online backup with the desired business recovery point.
  • Leaving immediate in a normal standby configuration and ending recovery unexpectedly.
  • Starting without recovery.signal and assuming the target will control crash recovery.
  • Assuming success when the required WAL chain never reaches a consistent point.

Related parameters

recovery_target_time · recovery_target_xid · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action

References

16.20 - recovery_target_action

recovery_target_action sets the action to perform upon reaching the recovery target. It is a postmaster setting present in PG12–18; the latest recorded boot default is pause.
Note

Fact — official short description: “Sets the action to perform upon reaching the recovery target.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuepause, promote, shutdown
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Valuepause
pause

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 pause — pause

How it works

Selects what PostgreSQL does after it reaches a configured recovery target. The value is read when recovery starts.

pause leaves recovery paused for inspection, promote ends recovery and opens the server for normal service, and shutdown stops the server at the target. pause requires hot_standby for query inspection.

The setting has no effect without a stopping target. With shutdown, recovery.signal is not removed, so an unchanged restart reaches the target and shuts down again; remove or change the recovery configuration deliberately after validation.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target_action only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Expecting an action when no stopping target is configured.
  • Using pause with hot_standby disabled and expecting to inspect the database with queries.
  • Using promote before the recovered state has been verified.
  • Using shutdown and restarting with recovery.signal and the same target still present.
  • Treating shutdown as permanent removal of later WAL; the next start still replays from the last checkpoint to the target.

Related parameters

recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_inclusive · recovery_target_timeline · hot_standby

References

16.21 - recovery_target_inclusive

recovery_target_inclusive sets whether to include or exclude transaction with recovery target. It is a postmaster setting present in PG12–18; the latest recorded boot default is on.
Note

Fact — official short description: “Sets whether to include or exclude transaction with recovery target.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 on — on

How it works

Chooses which side of an exact recovery boundary is retained. The value is read when targeted recovery starts.

on stops just after and includes the target LSN, commit time, or XID; off stops just before and excludes it. The setting applies only to recovery_target_lsn, recovery_target_time, and recovery_target_xid.

It has no effect on immediate or named restore-point targets. Select the boundary from identified WAL/business evidence and validate recovered rows and transactions, not only the displayed timestamp or LSN.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target_inclusive only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Expecting it to affect immediate or named restore-point targets.
  • Selecting on/off without identifying the exact boundary transaction or WAL record.
  • Assuming equal timestamps imply one deterministic commit boundary.
  • Validating only the reported replay position instead of recovered application data.
  • Leaving the value in a reusable recovery template without documenting the intended side of the boundary.

Related parameters

recovery_target_lsn · recovery_target_time · recovery_target_xid · recovery_target_action · recovery_target_timeline · restore_command

References

16.22 - recovery_target_lsn

recovery_target_lsn sets the LSN of the write-ahead log location up to which recovery will proceed. It is a postmaster setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the LSN of the write-ahead log location up to which recovery will proceed.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the LSN of the write-ahead log location up to which recovery will proceed. The value is fixed when the server starts, so changing it requires a restart.

Recovery replays up to a pg_lsn location, with recovery_target_inclusive selecting the side of the boundary. The LSN must lie on the chosen recovery timeline and be reachable from the base backup’s WAL chain.

At most one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, and recovery_target_xid may be set; timeline, inclusive, and action are modifiers. Rehearse from the same base backup through a complete WAL chain—an unreachable target makes targeted recovery fail.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target_lsn only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Using an LSN from a different cluster or a timeline not descended from the base backup.
  • Setting another recovery target selector at the same time.
  • Choosing inclusive without identifying which WAL record must be included.
  • Requesting an LSN beyond the available archive/streaming WAL and getting an unreachable target.
  • Comparing LSNs as ordinary decimal numbers instead of pg_lsn values.

Related parameters

recovery_target · recovery_target_time · recovery_target_xid · recovery_target_name · recovery_target_inclusive · recovery_target_action

References

16.23 - recovery_target_name

recovery_target_name sets the named restore point up to which recovery will proceed. It is a postmaster setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the named restore point up to which recovery will proceed.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the named restore point up to which recovery will proceed. The value is fixed when the server starts, so changing it requires a restart.

Recovery stops at a restore point previously recorded by pg_create_restore_point(). Restore-point names are meaningful only if the corresponding WAL record is present on the selected timeline.

At most one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, and recovery_target_xid may be set; timeline, inclusive, and action are modifiers. Rehearse from the same base backup through a complete WAL chain—an unreachable target makes targeted recovery fail.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target_name only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Naming a restore point whose WAL record is absent from the selected timeline.
  • Assuming recovery_target_inclusive changes a named restore-point boundary.
  • Setting another recovery target selector at the same time.
  • Mistyping a case-sensitive restore-point name and making the target unreachable.
  • Creating a business label without recording the cluster, timeline, and base-backup relationship.

Related parameters

recovery_target · recovery_target_time · recovery_target_xid · recovery_target_lsn · recovery_target_inclusive · recovery_target_action

References

16.24 - recovery_target_time

recovery_target_time sets the time stamp up to which recovery will proceed. It is a postmaster setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the time stamp up to which recovery will proceed.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the time stamp up to which recovery will proceed. The value is fixed when the server starts, so changing it requires a restart.

Recovery compares transaction commit records with this timestamp; numeric UTC offsets or full time-zone names avoid abbreviation ambiguity. recovery_target_inclusive selects whether commits exactly at the boundary are replayed.

At most one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, and recovery_target_xid may be set; timeline, inclusive, and action are modifiers. Rehearse from the same base backup through a complete WAL chain—an unreachable target makes targeted recovery fail.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target_time only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Using an ambiguous time-zone abbreviation instead of a numeric offset or full zone name.
  • Assuming one wall-clock timestamp uniquely identifies a business transaction.
  • Setting another recovery target selector at the same time.
  • Choosing inclusive on/off without identifying the exact boundary commit.
  • Requesting a time outside the reachable WAL range or on the wrong timeline.

Related parameters

recovery_target · recovery_target_xid · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action

References

16.25 - recovery_target_timeline

recovery_target_timeline specifies the timeline to recover into. It is a postmaster setting present in PG12–18; the latest recorded boot default is latest.
Note

Fact — official short description: “Specifies the timeline to recover into.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Valuelatest
latest

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 latest — latest

How it works

Specifies the timeline history that recovery follows. The value is read at server start for the recovery run.

latest follows the newest timeline found in the archive, current stays on the timeline current when the base backup was taken, and an explicit decimal or 0x-prefixed hexadecimal ID selects a particular branch. A timeline can be selected with or without an earlier stopping target.

The chosen timeline must descend from the base backup and its history/WAL files must be available. This setting selects a branch; it does not itself choose a transaction boundary or promote the server.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target_timeline only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Using latest when a deliberate re-recovery must stay on an older branch.
  • Using current when the required WAL exists only on a descendant timeline.
  • Selecting a timeline not descended from the base backup.
  • Failing to retain the timeline history file and corresponding WAL.
  • Treating timeline selection as a stopping target or promotion command.

Related parameters

recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_action · restore_command · primary_conninfo

References

16.26 - recovery_target_xid

recovery_target_xid sets the transaction ID up to which recovery will proceed. It is a postmaster setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the transaction ID up to which recovery will proceed.”

Identity

Type Valuestring
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery Target
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the transaction ID up to which recovery will proceed. The value is fixed when the server starts, so changing it requires a restart.

The target is a commit record for the named transaction ID, not a simple numeric ordering of all transactions: XIDs are assigned at start and can commit out of order. recovery_target_inclusive controls whether that target transaction is included.

At most one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, and recovery_target_xid may be set; timeline, inclusive, and action are modifiers. Rehearse from the same base backup through a complete WAL chain—an unreachable target makes targeted recovery fail.

Tuning advice

Tip

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

Workload Guidance
OLTP This is not a steady-state performance knob. Set recovery_target_xid only on an isolated recovery instance after recording target evidence, base backup, timeline, and expected boundary; rehearse and require a second-person review.
OLAP For a large restore, budget WAL replay and inspection time first. Validate the reached point read-only; do not let heavy analytical queries delay or contaminate the recovery decision.
Small nodes Prefer a backup tool that generates a controlled recovery configuration. Never leave target settings in ordinary primary/standby templates, and clean up signal files and targets afterward.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Assuming numeric XID order equals commit order; XIDs are assigned when transactions start.
  • Using an XID copied from another cluster or unrelated timeline.
  • Setting another recovery target selector at the same time.
  • Choosing inclusive without deciding whether the target transaction itself must be present.
  • Treating an XID as a globally unique business identifier across wraparound and clusters.

Related parameters

recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action

References

16.27 - restore_command

restore_command sets the shell command that will be called to retrieve an archived WAL file. It is a sighup setting present in PG12–18; the latest recorded boot default is empty.
Note

Fact — official short description: “Sets the shell command that will be called to retrieve an archived WAL file.”

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 ValueWrite-Ahead Log / Archive Recovery
Upstream classification
Latest boot value Value""
empty string

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
Commit date 2018-11-25
Discussion thread 1

Default history

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

How it works

Sets the shell command that will be called to retrieve an archived WAL file. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

During archive recovery PostgreSQL expands %f to the requested file and %p to its destination. Success must mean the exact file was copied durably; a normal not-found result must be nonzero so recovery can try streaming or pg_wal, while shell quoting must resist unusual paths.

Monitor and change restore_command together with archive_mode, archive_command, archive_library. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Manage restore_command as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.
OLAP Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.
Small nodes Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Returning zero for a missing or wrong WAL file.
  • Failing to quote %f and %p safely.
  • Using an archive that can return a segment from the wrong timeline or cluster.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

archive_mode · archive_command · archive_library · archive_timeout · archive_cleanup_command · recovery_end_command

References

16.28 - summarize_wal

summarize_wal starts the WAL summarizer process to enable incremental backup. It is a sighup setting present in PG17–18; the latest recorded boot default is off.
Note

Fact — official short description: “Starts the WAL summarizer process to enable incremental backup.”

Identity

Type Valuebool
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 ValueWrite-Ahead Log / Summarization
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 174c480508ac — Add a new WAL summarizer process.
Commit date 2023-12-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 off — off

How it works

Starts the WAL summarizer process to enable incremental backup. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The WAL summarizer records which blocks changed over WAL ranges so pg_basebackup can construct incremental backups. It can run on a primary or standby, but cannot summarize WAL generated at wal_level=minimal.

Monitor and change summarize_wal together with wal_summary_keep_time, wal_level, archive_mode. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable or tune summarize_wal only when using PostgreSQL incremental backup. Monitor summarizer progress and retain summaries across the complete WAL range between every dependent backup pair.
OLAP Bulk writes increase summarizer work. Capacity-test backup interval, WAL peak, and backup window together; a summary gap makes an incremental backup fail.
Small nodes Keep summarize_wal off when incremental backup is not used. If enabled, derive retention from the real backup chain and alert on summary-directory capacity.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Enabling it with wal_level=minimal and expecting usable summary files.
  • Treating WAL summaries as a WAL archive or a backup by themselves.
  • Turning the summarizer off and expecting wal_summary_keep_time cleanup to continue.
  • Taking an incremental backup without checking summarizer progress and summary coverage.

Related parameters

wal_summary_keep_time · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command

References

16.29 - synchronous_commit

synchronous_commit — Sets the current transaction’s synchronization level. Observed in PG9.0–19 Beta 3; its last measured boot default is on in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the current transaction’s synchronization level.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuelocal, remote_write, remote_apply, on, off
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valueon
on

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 on — on

How it works

All modes except off wait for the transaction’s WAL to be flushed locally. With off, success can be returned before local durable flush; a crash can lose recent acknowledged transactions, but recovery remains transactionally consistent and does not introduce the corruption risk associated with fsync = off.

When synchronous_standby_names selects synchronous standbys, remote_write waits for receipt and an operating-system write on a standby, on waits for a durable standby flush, and remote_apply waits for replay and query visibility. local waits only for local durable flush. Without a selected synchronous standby, the remote modes add no remote guarantee.

The effective mode is the value in force when a transaction commits. Applications can use SET LOCAL for one transaction, allowing critical and replaceable work to use different durability policies on the same server.

Tuning advice

Tip

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

Workload Guidance
OLTP Keep on as the general default. Use off only for explicitly replaceable transactions, and use remote_apply only when post-commit reads on a synchronous standby require causal visibility; include network round-trip and standby health in the latency budget.
OLAP For a reproducible bulk load, transaction-local off can improve throughput if losing the final unflushed portion is acceptable and the load can be rerun. Keep catalog changes, handoff markers, and externally visible completion records synchronous.
Small nodes Retain on. Small systems rarely gain enough from a global durability downgrade to justify the operational ambiguity; tune individual noncritical jobs instead.

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

  • Equating synchronous_commit = off with fsync = off; the former risks recent data loss, not structural corruption.
  • Expecting remote_write, on, or remote_apply to wait remotely when no synchronous standby is selected.
  • Using remote_write while assuming the standby is durable across an operating-system crash.
  • Allowing an unavailable synchronous standby to stall commits without an HA response plan.
  • Leaking a session-level SET through a connection pool instead of using SET LOCAL or reset discipline.

Related parameters

synchronous_standby_names · fsync · wal_writer_delay · wal_sync_method · commit_delay · wal_level

References

16.30 - wal_buffers

wal_buffers — Sets the number of disk-page buffers in shared memory for WAL. Observed in PG9.0–19 Beta 3; its last measured boot default is -1 8kB in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the number of disk-page buffers in shared memory for WAL.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value8kB
Raw unit
Range Value-1 – 262143
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Value-1
-1 8kB

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0 8 8kB 64 KiB (8 × 8kB)
PG9.1–19 Beta 3 -1 8kB -1 8kB

How it works

Sets the number of disk-page buffers in shared memory for WAL. The value is fixed when the server starts, so changing it requires a restart.

The automatic -1 value chooses about 1/32 of shared_buffers, bounded below and by one WAL segment. The buffer absorbs WAL records before writes; too little can add WALWrite pressure during bursts, while oversized allocation consumes startup shared memory without replacing durable flushes.

Monitor and change wal_buffers together with fsync, full_page_writes, wal_sync_method. 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

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_buffers from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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 16MB different 16MB
OLAP 16MB different 16MB
CRIT 16MB different 16MB
TINY 16MB different 16MB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 16MB (dcs); OLAP: PG9.0–19 Beta 3 = 16MB (dcs); CRIT: PG9.0–19 Beta 3 = 16MB (dcs); TINY: PG9.0–19 Beta 3 = 16MB (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to use the normal one-segment ceiling explicitly for burst absorption; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Reading -1 as a negative allocation rather than automatic sizing.
  • Forgetting that the automatic choice is based on shared_buffers and capped at one WAL segment.
  • Reading an unqualified positive value as bytes rather than WAL blocks; very small positives are raised to the minimum.
  • Allocating a large manual buffer without evidence of WALInsert/WALWrite pressure.
  • Expecting more WAL buffers to replace durable flushes or improve a storage-bound WALSync path.

Related parameters

fsync · full_page_writes · wal_sync_method · synchronous_commit · wal_writer_delay · wal_writer_flush_after

References

16.31 - wal_compression

wal_compression — Compresses full-page writes written in WAL file with specified method. Observed in PG9.5–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Compresses full-page writes written in WAL file with specified method.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valuepglz, lz4, zstd, on, off
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.5
Present in PG9.5–19 Beta 3
Removed in No
Introduction commit 57aa5b2bb11a — Add GUC to enable compression of full page images stored in WAL.
Commit date 2015-03-11
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.5–19 Beta 3 off — off

How it works

Compresses full-page writes written in WAL file with specified method. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

Compression applies to full-page images produced by full_page_writes, backup, or hint logging, not to every WAL record. pglz is built in; lz4/zstd availability depends on the build, and replay pays decompression CPU in exchange for lower WAL volume.

Monitor and change wal_compression together with full_page_writes, wal_log_hints, wal_level. Validate on the relevant server role and real workload, then use its superuser context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_compression from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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 lz4 different lz4
OLAP lz4 different lz4
CRIT lz4 different lz4
TINY lz4 different lz4
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.5–14 unmodified, PG15–19 Beta 3 = lz4 (dcs); OLAP: PG9.5–14 unmodified, PG15–19 Beta 3 = lz4 (dcs); CRIT: PG9.5–14 unmodified, PG15–19 Beta 3 = lz4 (dcs); TINY: PG9.5–14 unmodified, PG15–19 Beta 3 = lz4 (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to reduce full-page-image WAL volume with LZ4 on releases that support the enum method; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Expecting compression to affect every WAL record rather than full-page images.
  • Selecting lz4 or zstd on a server build that does not provide that method.
  • Ignoring compression CPU on the primary and decompression CPU during replay.
  • Changing a privileged session value and assuming other sessions or future connections inherited it.
  • Comparing WAL bytes without controlling checkpoint frequency and full_page_writes activity.

Related parameters

full_page_writes · wal_log_hints · wal_level · wal_buffers · commit_delay · commit_siblings

References

16.32 - wal_decode_buffer_size

wal_decode_buffer_size sets the buffer size for reading ahead in the WAL during recovery. It is a postmaster setting present in PG15–18; the latest recorded boot default is 512 KiB.
Note

Fact — official short description: “Buffer size for reading ahead in the WAL during recovery.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit ValueB
Raw unit
Range Value65536 – 1073741823
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Recovery
Upstream classification
Latest boot value Value524288
512 KiB

Lifecycle

Fact Value
First observed PG15
Present in PG15–19 Beta 3
Removed in No
Introduction commit 1d257577e08d — Optionally prefetch referenced data in recovery.
Commit date 2021-04-08
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG15–19 Beta 3 524288 B 512 KiB

How it works

Buffer size for reading ahead in the WAL during recovery. The value is fixed when the server starts, so changing it requires a restart.

Recovery scans this far ahead in decoded WAL to discover future block references for prefetch. It is a restart-time memory/lead limit, not a logical-decoding output buffer, and only helps when recovery_prefetch and the storage workload benefit.

Monitor and change wal_decode_buffer_size together with recovery_prefetch, maintenance_io_concurrency, effective_io_concurrency. 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

Tip

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

Workload Guidance
OLTP Tune wal_decode_buffer_size with recovery/standby catch-up benchmarks on production-like storage while observing replay I/O wait, cache behavior, and maintenance_io_concurrency. Keep the default without measured benefit.
OLAP Large data with slow random reads may benefit more, but excess prefetch competes with query I/O and cache. Test crash recovery and a query-serving standby separately.
Small nodes The default is usually sufficient. Do not spend scarce memory or I/O queue depth on a larger look-ahead window unless a recovery-time objective is demonstrably missed.

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: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.
  • Ignoring interactions with checkpoints, replication slots, or archive failure.
  • Reloading a restart-context value and assuming it became active.

Related parameters

recovery_prefetch · maintenance_io_concurrency · effective_io_concurrency · shared_buffers · archive_cleanup_command · archive_command

References

16.33 - wal_init_zero

wal_init_zero writes zeroes to new WAL files before first use. It is a superuser setting present in PG12–18; the latest recorded boot default is on.
Note

Fact — official short description: “Writes zeroes to new WAL files before first use.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 475861b2615d — Add wal_recycle and wal_init_zero GUCs.
Commit date 2019-04-02
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 on — on

How it works

Writes zeroes to new WAL files before first use. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

With on, newly created WAL segments are zero-filled, which preallocates blocks on many filesystems. Copy-on-write filesystems may turn that work into unnecessary allocation and fragmentation; off still creates a correctly sized file by writing its last byte.

Monitor and change wal_init_zero together with wal_recycle, wal_segment_size, min_wal_size. Validate on the relevant server role and real workload, then use its superuser context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_init_zero from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Disabling zero-fill on a conventional filesystem and moving allocation stalls into peak WAL creation.
  • Keeping zero-fill on copy-on-write storage without measuring allocation and fragmentation cost.
  • Assuming an apparently sparse file means PostgreSQL changed wal_segment_size.
  • Changing a session value and expecting already-created WAL segments to be rewritten.

Related parameters

wal_recycle · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings

References

16.34 - wal_level

wal_level — Sets the level of information written to the WAL. Observed in PG9.0–19 Beta 3; its last measured boot default is replica in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Sets the level of information written to the WAL.”

Identity

Type Valueenum
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Valueminimal, replica, logical
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valuereplica
replica

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–9.6 minimal — minimal
PG10–19 Beta 3 replica — replica

How it works

Sets the level of information written to the WAL. The value is fixed when the server starts, so changing it requires a restart.

minimal logs only crash-recovery needs and is incompatible with archiving/streaming modes that require replica data; replica supports physical replication and archive recovery; logical adds logical-decoding information. Changing level requires restart and may change WAL volume.

Monitor and change wal_level together with wal_compression, full_page_writes, wal_log_hints. 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

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_level from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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 logical different logical
OLAP logical different logical
CRIT logical different logical
TINY logical different logical
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = logical (dcs); OLAP: PG9.0–19 Beta 3 = logical (dcs); CRIT: PG9.0–19 Beta 3 = logical (dcs); TINY: PG9.0–19 Beta 3 = logical (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to enable logical decoding by default across Pigsty profiles; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Selecting minimal while expecting archiving, streaming replication, or logical decoding.
  • Raising it without budgeting extra WAL and restart downtime.
  • Lowering it while slots/subscriptions still depend on the higher level.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

wal_compression · full_page_writes · wal_log_hints · wal_buffers · max_wal_senders · max_replication_slots

References

16.35 - wal_log_hints

wal_log_hints — Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification. Observed in PG9.4–19 Beta 3; its last measured boot default is off in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuepostmaster
Requires a server restart
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valueoff
off

Lifecycle

Fact Value
First observed PG9.4
Present in PG9.4–19 Beta 3
Removed in No
Introduction commit 961bf59fb7a7 — Rename wal_log_hintbits to wal_log_hints, per discussion on pgsql-hackers.
Commit date 2013-12-21
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.4–19 Beta 3 off — off

How it works

Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification. The value is fixed when the server starts, so changing it requires a restart.

When data checksums are off, this forces full-page WAL for the first hint-bit change after a checkpoint, giving pg_rewind the block-change safety it needs. With checksums enabled, equivalent hint logging already occurs, so the setting adds no further effect.

Monitor and change wal_log_hints together with wal_compression, full_page_writes, wal_level. 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

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_log_hints from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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 on different 'on'
OLAP on different 'on'
CRIT on different 'on'
TINY on different 'on'
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.4–19 Beta 3 = on (dcs); OLAP: PG9.4–19 Beta 3 = on (dcs); CRIT: PG9.4–19 Beta 3 = on (dcs); TINY: PG9.4–19 Beta 3 = on (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to keep pg_rewind viable even when data checksums are not the mechanism forcing hint-bit WAL; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Assuming it logs every hint update rather than the first page image after a checkpoint.
  • Turning it on but not completing the restart before relying on pg_rewind.
  • Forgetting that checksums already force the relevant hint WAL behavior.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

wal_compression · full_page_writes · wal_level · wal_buffers · max_wal_senders · max_replication_slots

References

16.36 - wal_recycle

wal_recycle recycles WAL files by renaming them. It is a superuser setting present in PG12–18; the latest recorded boot default is on.
Note

Fact — official short description: “Recycles WAL files by renaming them.”

Identity

Type Valuebool
Upstream pg_settings type
Context Valuesuperuser
Settable at runtime by a superuser
Unit Value—
Raw unit
Range Value—
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valueon
on

Lifecycle

Fact Value
First observed PG12
Present in PG12–19 Beta 3
Removed in No
Introduction commit 475861b2615d — Add wal_recycle and wal_init_zero GUCs.
Commit date 2019-04-02
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG12–19 Beta 3 on — on

How it works

Recycles WAL files by renaming them. A superuser or a role granted SET privilege can change it for the relevant session or configuration scope.

With on, PostgreSQL renames no-longer-needed WAL segments for future use rather than creating new files. Reuse is usually cheaper, but on copy-on-write storage fresh allocation can perform better and avoid preserving extents.

Monitor and change wal_recycle together with wal_init_zero, wal_segment_size, min_wal_size. Validate on the relevant server role and real workload, then use its superuser context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_recycle from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Assuming recycled renames are always faster than new allocation on copy-on-write storage.
  • Disabling recycling without measuring segment creation latency during WAL bursts.
  • Expecting a session change to alter files already recycled or removed.
  • Treating recycling as a WAL retention limit rather than a file-reuse policy.

Related parameters

wal_init_zero · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings

References

16.37 - wal_skip_threshold

wal_skip_threshold sets the minimum size of new file to fsync instead of writing WAL. It is a user setting present in PG13–18; the latest recorded boot default is 2 MiB.
Note

Fact — official short description: “Minimum size of new file to fsync instead of writing WAL.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valueuser
Settable by an ordinary user
Unit ValuekB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Value2048
2 MiB

Lifecycle

Fact Value
First observed PG13
Present in PG13–19 Beta 3
Removed in No
Introduction commit cb2fd7eac285 — Skip WAL for new relfilenodes, under wal_level=minimal.
Commit date 2020-03-21
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG13–19 Beta 3 2048 kB 2 MiB

How it works

Minimum size of new file to fsync instead of writing WAL. It can be changed at session scope, so different sessions may observe different behavior.

Only at wal_level=minimal, creating or rewriting a permanent relation can either WAL-log its new data or fsync the files directly. This threshold chooses fsync for larger relations and has no effect at replica or logical levels.

Monitor and change wal_skip_threshold together with commit_delay, commit_siblings, fsync. Validate on the relevant server role and real workload, then use its user context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_skip_threshold from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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: PG13–19 Beta 3 unmodified; OLAP: PG13–19 Beta 3 unmodified; CRIT: PG13–19 Beta 3 unmodified; TINY: PG13–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Tuning it at wal_level=replica or logical, where the setting has no effect.
  • Applying it to ordinary row changes even though it concerns newly created or rewritten relation files.
  • Reading an unqualified value as bytes instead of kilobytes.
  • Choosing fsync versus WAL logging without benchmarking the actual storage and concurrent-commit impact.

Related parameters

commit_delay · commit_siblings · fsync · full_page_writes · synchronous_commit · wal_buffers

References

16.38 - wal_summary_keep_time

wal_summary_keep_time sets the time for which WAL summary files should be kept. It is a sighup setting present in PG17–18; the latest recorded boot default is 10 d.
Note

Fact — official short description: “Time for which WAL summary files should be kept.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuemin
Raw unit
Range Value0 – 35791394
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Summarization
Upstream classification
Latest boot value Value14400
10 d

Lifecycle

Fact Value
First observed PG17
Present in PG17–19 Beta 3
Removed in No
Introduction commit 174c480508ac — Add a new WAL summarizer process.
Commit date 2023-12-20
Discussion thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG17–19 Beta 3 14400 min 10 d

How it works

Time for which WAL summary files should be kept. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The summarizer deletes summary files older than this age, using file timestamps. The retention must exceed the longest interval between an incremental backup and the earlier backup it depends on; zero keeps summaries indefinitely, and cleanup stops while summarize_wal is off.

Monitor and change wal_summary_keep_time together with summarize_wal, wal_level, archive_mode. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Enable or tune wal_summary_keep_time only when using PostgreSQL incremental backup. Monitor summarizer progress and retain summaries across the complete WAL range between every dependent backup pair.
OLAP Bulk writes increase summarizer work. Capacity-test backup interval, WAL peak, and backup window together; a summary gap makes an incremental backup fail.
Small nodes Keep summarize_wal off when incremental backup is not used. If enabled, derive retention from the real backup chain and alert on summary-directory capacity.

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: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

  • Deleting summaries still needed to bridge the prior and next incremental backup.
  • Setting zero and never monitoring unbounded summary growth.
  • Turning summarize_wal off and expecting retention cleanup to continue.
  • Confusing pg_settings base units with human-readable configuration units.
  • Benchmarking throughput without a crash-recovery and archive-restore test.

Related parameters

summarize_wal · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command

References

16.39 - wal_sync_method

wal_sync_method — Selects the method used for forcing WAL updates to disk. Observed in PG9.0–19 Beta 3; its last measured boot default is fdatasync in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Selects the method used for forcing WAL updates to disk.”

Identity

Type Valueenum
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 Valuefsync, fdatasync, open_sync, open_datasync
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Valuefdatasync
fdatasync

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 fdatasync — fdatasync

How it works

Selects the method used for forcing WAL updates to disk. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

This chooses the operating-system primitive used to force WAL to durable storage, such as fdatasync, fsync, or open-sync variants. Availability and performance are platform/filesystem specific; all supported choices preserve the durability contract when the stack is honest.

Monitor and change wal_sync_method together with fsync, full_page_writes, synchronous_commit. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_sync_method from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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

  • Selecting a method that the operating system or filesystem does not support.
  • Benchmarking on a different kernel, mount option, or storage cache than production.
  • Confusing write throughput with durable-sync latency.
  • Changing the method without a crash/power-loss durability test.
  • Assuming the fastest method on data files is also the best method for WAL.

Related parameters

fsync · full_page_writes · synchronous_commit · wal_buffers · wal_writer_delay · commit_delay

References

16.40 - wal_writer_delay

wal_writer_delay — Time between WAL flushes performed in the WAL writer. Observed in PG9.0–19 Beta 3; its last measured boot default is 200 ms in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Time between WAL flushes performed in the WAL writer.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Valuems
Raw unit
Range Value1 – 10000
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Value200
200 ms

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

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.0–19 Beta 3 200 ms 200 ms

How it works

Time between WAL flushes performed in the WAL writer. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The WAL writer sleeps for this interval between activity checks, but may wake earlier under pressure. Shorter delays can move writes out of foreground commits at the price of wakeups; durability timing still depends on wal_writer_flush_after and commit behavior.

Monitor and change wal_writer_delay together with fsync, full_page_writes, wal_sync_method. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_writer_delay from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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 20ms different 20ms
OLAP 20ms different 20ms
CRIT 10ms different 10ms
TINY 20ms different 20ms
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 20ms (dcs); OLAP: PG9.0–19 Beta 3 = 20ms (dcs); CRIT: PG9.0–19 Beta 3 = 10ms (dcs); TINY: PG9.0–19 Beta 3 = 20ms (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to move WAL out of foreground backends more frequently, with an even shorter CRIT cadence; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Treating the interval as a strict commit-flush deadline; the writer can wake earlier and foreground commits can flush independently.
  • Setting it very low and paying excessive wakeup and small-write overhead.
  • Setting it very high and moving more WAL writes into foreground backends.
  • Ignoring wal_writer_flush_after when interpreting write versus durable-flush timing.
  • Using asynchronous commit without budgeting its possible loss window.

Related parameters

fsync · full_page_writes · wal_sync_method · synchronous_commit · wal_buffers · commit_delay

References

16.41 - wal_writer_flush_after

wal_writer_flush_after — Amount of WAL written out by WAL writer that triggers a flush. Observed in PG9.6–19 Beta 3; its last measured boot default is 1 MiB (128 × 8kB) in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
Note

Fact — official short description: “Amount of WAL written out by WAL writer that triggers a flush.”

Identity

Type Valueinteger
Upstream pg_settings type
Context Valuesighup
Takes effect after configuration reload
Unit Value8kB
Raw unit
Range Value0 – 2147483647
Raw limits in the last observed version
Enum values Value—
— for non-enum types
Category ValueWrite-Ahead Log / Settings
Upstream classification
Latest boot value Value128
1 MiB (128 × 8kB)

Lifecycle

Fact Value
First observed PG9.6
Present in PG9.6–19 Beta 3
Removed in No
Introduction commit 7975c5e0a992 — Allow the WAL writer to flush WAL at a reduced rate.
Commit date 2016-02-15
Discussion —

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions Raw boot_val Unit Human value
PG9.6–19 Beta 3 128 8kB 1 MiB (128 × 8kB)

How it works

Amount of WAL written out by WAL writer that triggers a flush. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

After this volume since its last flush, the WAL writer forces written WAL to durable storage; otherwise it may only write to the OS. Zero flushes immediately, while larger values trade background smoothing against a bigger dirty-WAL window for asynchronous commits.

Monitor and change wal_writer_flush_after together with wal_buffers, wal_writer_delay, wal_sync_method. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

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

Workload Guidance
OLTP Establish durability and recovery objectives first, then tune wal_writer_flush_after from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.
OLAP Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.
Small nodes Start from safe defaults or the measured Pigsty value and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.

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 1MB same as boot 1MB
OLAP 1MB same as boot 1MB
CRIT 0 different 0
TINY 1MB same as boot 1MB
Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.6–19 Beta 3 = 1MB (dcs); OLAP: PG9.6–19 Beta 3 = 1MB (dcs); CRIT: PG9.6–19 Beta 3 = 0 (dcs); TINY: PG9.6–19 Beta 3 = 1MB (dcs). Advice, pending human review — Editorial interpretation, pending human maintainer review: the override appears intended to flush WAL writer output in 1 MiB batches, while CRIT requests immediate flushes; confirm it against the current Pigsty templates, hardware fixture, and operational guarantees before publication.

Common pitfalls

  • Reading an unqualified value as bytes rather than WAL blocks.
  • Forgetting that zero requests an immediate flush from the WAL writer.
  • Choosing a large batch without considering asynchronous-commit loss exposure and dirty WAL.
  • Treating the setting as a replacement for synchronous commit flushes.
  • Tuning it without wal_writer_delay and storage flush latency.

Related parameters

wal_buffers · wal_writer_delay · wal_sync_method · synchronous_commit · commit_delay · commit_siblings

References