This is the multi-page printable view of this section. .
Error Handling
Dossier URLs remain flat; this category exists only to organize browsing and the sidebar.
1 - data_sync_retry
Fact — official short description: “Whether to continue running after a failure to sync data files.”
Identity
Type,- Upstream pg_settings type
Context,- Requires a server restart
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- 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
| 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
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 | — | — |
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
2 - exit_on_error
Fact — official short description: “Terminate session on any error.”
Identity
Type,- Upstream pg_settings type
Context,- Settable by an ordinary user
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- 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
| 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
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 | — | — |
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
3 - recovery_init_sync_method
Fact — official short description: “Sets the method for synchronizing the data directory before crash recovery.”
Identity
Type,- Upstream pg_settings type
Context,- Takes effect after configuration reload
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- 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
| 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
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 | — | — |
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
4 - restart_after_crash
Fact — official short description: “Reinitialize server after backend crash.”
Identity
Type,- Upstream pg_settings type
Context,- Takes effect after configuration reload
Unit,- Raw unit
Range,- Raw limits in the last observed version
Enum values,- — for non-enum types
Category,- Upstream classification
Latest boot value,- 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
| 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
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 | — | — |
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