????
Your IP : 3.141.33.133
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>20.5. Write Ahead Log</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-resource.html" title="20.4. Resource Consumption" /><link rel="next" href="runtime-config-replication.html" title="20.6. Replication" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.5. Write Ahead Log</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-resource.html" title="20.4. Resource Consumption">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-replication.html" title="20.6. Replication">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-WAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.5. Write Ahead Log <a href="#RUNTIME-CONFIG-WAL" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS">20.5.1. Settings</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS">20.5.2. Checkpoints</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING">20.5.3. Archiving</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY">20.5.4. Recovery</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY">20.5.5. Archive Recovery</a></span></dt><dt><span class="sect2"><a href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET">20.5.6. Recovery Target</a></span></dt></dl></div><p>
For additional information on tuning these settings,
see <a class="xref" href="wal-configuration.html" title="30.5. WAL Configuration">Section 30.5</a>.
</p><div class="sect2" id="RUNTIME-CONFIG-WAL-SETTINGS"><div class="titlepage"><div><div><h3 class="title">20.5.1. Settings <a href="#RUNTIME-CONFIG-WAL-SETTINGS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-WAL-LEVEL"><span class="term"><code class="varname">wal_level</code> (<code class="type">enum</code>)
<a id="id-1.6.7.8.3.2.1.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-LEVEL" class="id_link">#</a></dt><dd><p>
<code class="varname">wal_level</code> determines how much information is written to
the WAL. The default value is <code class="literal">replica</code>, which writes enough
data to support WAL archiving and replication, including running
read-only queries on a standby server. <code class="literal">minimal</code> removes all
logging except the information required to recover from a crash or
immediate shutdown. Finally,
<code class="literal">logical</code> adds information necessary to support logical
decoding. Each level includes the information logged at all lower
levels. This parameter can only be set at server start.
</p><p>
The <code class="literal">minimal</code> level generates the least WAL
volume. It logs no row information for permanent relations
in transactions that create or
rewrite them. This can make operations much faster (see
<a class="xref" href="populate.html#POPULATE-PITR" title="14.4.7. Disable WAL Archival and Streaming Replication">Section 14.4.7</a>). Operations that initiate this
optimization include:
</p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="command">ALTER ... SET TABLESPACE</code></td></tr><tr><td><code class="command">CLUSTER</code></td></tr><tr><td><code class="command">CREATE TABLE</code></td></tr><tr><td><code class="command">REFRESH MATERIALIZED VIEW</code>
(without <code class="option">CONCURRENTLY</code>)</td></tr><tr><td><code class="command">REINDEX</code></td></tr><tr><td><code class="command">TRUNCATE</code></td></tr></table><p>
However, minimal WAL does not contain sufficient information for
point-in-time recovery, so <code class="literal">replica</code> or
higher must be used to enable continuous archiving
(<a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-MODE">archive_mode</a>) and streaming binary replication.
In fact, the server will not even start in this mode if
<code class="varname">max_wal_senders</code> is non-zero.
Note that changing <code class="varname">wal_level</code> to
<code class="literal">minimal</code> makes previous base backups unusable
for point-in-time recovery and standby servers.
</p><p>
In <code class="literal">logical</code> level, the same information is logged as
with <code class="literal">replica</code>, plus information needed to
extract logical change sets from the WAL. Using a level of
<code class="literal">logical</code> will increase the WAL volume, particularly if many
tables are configured for <code class="literal">REPLICA IDENTITY FULL</code> and
many <code class="command">UPDATE</code> and <code class="command">DELETE</code> statements are
executed.
</p><p>
In releases prior to 9.6, this parameter also allowed the
values <code class="literal">archive</code> and <code class="literal">hot_standby</code>.
These are still accepted but mapped to <code class="literal">replica</code>.
</p></dd><dt id="GUC-FSYNC"><span class="term"><code class="varname">fsync</code> (<code class="type">boolean</code>)
<a id="id-1.6.7.8.3.2.2.1.3" class="indexterm"></a>
</span> <a href="#GUC-FSYNC" class="id_link">#</a></dt><dd><p>
If this parameter is on, the <span class="productname">PostgreSQL</span> server
will try to make sure that updates are physically written to
disk, by issuing <code class="function">fsync()</code> system calls or various
equivalent methods (see <a class="xref" href="runtime-config-wal.html#GUC-WAL-SYNC-METHOD">wal_sync_method</a>).
This ensures that the database cluster can recover to a
consistent state after an operating system or hardware crash.
</p><p>
While turning off <code class="varname">fsync</code> is often a performance
benefit, this can result in unrecoverable data corruption in
the event of a power failure or system crash. Thus it
is only advisable to turn off <code class="varname">fsync</code> if
you can easily recreate your entire database from external
data.
</p><p>
Examples of safe circumstances for turning off
<code class="varname">fsync</code> include the initial loading of a new
database cluster from a backup file, using a database cluster
for processing a batch of data after which the database
will be thrown away and recreated,
or for a read-only database clone which
gets recreated frequently and is not used for failover. High
quality hardware alone is not a sufficient justification for
turning off <code class="varname">fsync</code>.
</p><p>
For reliable recovery when changing <code class="varname">fsync</code>
off to on, it is necessary to force all modified buffers in the
kernel to durable storage. This can be done while the cluster
is shutdown or while <code class="varname">fsync</code> is on by running <code class="command">initdb
--sync-only</code>, running <code class="command">sync</code>, unmounting the
file system, or rebooting the server.
</p><p>
In many situations, turning off <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a>
for noncritical transactions can provide much of the potential
performance benefit of turning off <code class="varname">fsync</code>, without
the attendant risks of data corruption.
</p><p>
<code class="varname">fsync</code> can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
If you turn this parameter off, also consider turning off
<a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a>.
</p></dd><dt id="GUC-SYNCHRONOUS-COMMIT"><span class="term"><code class="varname">synchronous_commit</code> (<code class="type">enum</code>)
<a id="id-1.6.7.8.3.2.3.1.3" class="indexterm"></a>
</span> <a href="#GUC-SYNCHRONOUS-COMMIT" class="id_link">#</a></dt><dd><p>
Specifies how much WAL processing must complete before
the database server returns a <span class="quote">“<span class="quote">success</span>”</span>
indication to the client. Valid values are
<code class="literal">remote_apply</code>, <code class="literal">on</code>
(the default), <code class="literal">remote_write</code>,
<code class="literal">local</code>, and <code class="literal">off</code>.
</p><p>
If <code class="varname">synchronous_standby_names</code> is empty,
the only meaningful settings are <code class="literal">on</code> and
<code class="literal">off</code>; <code class="literal">remote_apply</code>,
<code class="literal">remote_write</code> and <code class="literal">local</code>
all provide the same local synchronization level
as <code class="literal">on</code>. The local behavior of all
non-<code class="literal">off</code> modes is to wait for local flush of WAL
to disk. In <code class="literal">off</code> mode, there is no waiting,
so there can be a delay between when success is reported to the
client and when the transaction is later guaranteed to be safe
against a server crash. (The maximum
delay is three times <a class="xref" href="runtime-config-wal.html#GUC-WAL-WRITER-DELAY">wal_writer_delay</a>.) Unlike
<a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a>, setting this parameter to <code class="literal">off</code>
does not create any risk of database inconsistency: an operating
system or database crash might
result in some recent allegedly-committed transactions being lost, but
the database state will be just the same as if those transactions had
been aborted cleanly. So, turning <code class="varname">synchronous_commit</code> off
can be a useful alternative when performance is more important than
exact certainty about the durability of a transaction. For more
discussion see <a class="xref" href="wal-async-commit.html" title="30.4. Asynchronous Commit">Section 30.4</a>.
</p><p>
If <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a> is non-empty,
<code class="varname">synchronous_commit</code> also controls whether
transaction commits will wait for their WAL records to be
processed on the standby server(s).
</p><p>
When set to <code class="literal">remote_apply</code>, commits will wait
until replies from the current synchronous standby(s) indicate they
have received the commit record of the transaction and applied
it, so that it has become visible to queries on the standby(s),
and also written to durable storage on the standbys. This will
cause much larger commit delays than previous settings since
it waits for WAL replay. When set to <code class="literal">on</code>,
commits wait until replies
from the current synchronous standby(s) indicate they have received
the commit record of the transaction and flushed it to durable storage. This
ensures the transaction will not be lost unless both the primary and
all synchronous standbys suffer corruption of their database storage.
When set to <code class="literal">remote_write</code>, commits will wait until replies
from the current synchronous standby(s) indicate they have
received the commit record of the transaction and written it to
their file systems. This setting ensures data preservation if a standby instance of
<span class="productname">PostgreSQL</span> crashes, but not if the standby
suffers an operating-system-level crash because the data has not
necessarily reached durable storage on the standby.
The setting <code class="literal">local</code> causes commits to wait for
local flush to disk, but not for replication. This is usually not
desirable when synchronous replication is in use, but is provided for
completeness.
</p><p>
This parameter can be changed at any time; the behavior for any
one transaction is determined by the setting in effect when it
commits. It is therefore possible, and useful, to have some
transactions commit synchronously and others asynchronously.
For example, to make a single multistatement transaction commit
asynchronously when the default is the opposite, issue <code class="command">SET
LOCAL synchronous_commit TO OFF</code> within the transaction.
</p><p>
<a class="xref" href="runtime-config-wal.html#SYNCHRONOUS-COMMIT-MATRIX" title="Table 20.1. synchronous_commit Modes">Table 20.1</a> summarizes the
capabilities of the <code class="varname">synchronous_commit</code> settings.
</p><div class="table" id="SYNCHRONOUS-COMMIT-MATRIX"><p class="title"><strong>Table 20.1. synchronous_commit Modes</strong></p><div class="table-contents"><table class="table" summary="synchronous_commit Modes" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /><col class="col4" /><col class="col5" /></colgroup><thead><tr><th>synchronous_commit setting</th><th>local durable commit</th><th>standby durable commit after PG crash</th><th>standby durable commit after OS crash</th><th>standby query consistency</th></tr></thead><tbody><tr><td>remote_apply</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center">•</td></tr><tr><td>on</td><td align="center">•</td><td align="center">•</td><td align="center">•</td><td align="center"> </td></tr><tr><td>remote_write</td><td align="center">•</td><td align="center">•</td><td align="center"> </td><td align="center"> </td></tr><tr><td>local</td><td align="center">•</td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td>off</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr></tbody></table></div></div><br class="table-break" /></dd><dt id="GUC-WAL-SYNC-METHOD"><span class="term"><code class="varname">wal_sync_method</code> (<code class="type">enum</code>)
<a id="id-1.6.7.8.3.2.4.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-SYNC-METHOD" class="id_link">#</a></dt><dd><p>
Method used for forcing WAL updates out to disk.
If <code class="varname">fsync</code> is off then this setting is irrelevant,
since WAL file updates will not be forced out at all.
Possible values are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">open_datasync</code> (write WAL files with <code class="function">open()</code> option <code class="symbol">O_DSYNC</code>)
</p></li><li class="listitem"><p>
<code class="literal">fdatasync</code> (call <code class="function">fdatasync()</code> at each commit)
</p></li><li class="listitem"><p>
<code class="literal">fsync</code> (call <code class="function">fsync()</code> at each commit)
</p></li><li class="listitem"><p>
<code class="literal">fsync_writethrough</code> (call <code class="function">fsync()</code> at each commit, forcing write-through of any disk write cache)
</p></li><li class="listitem"><p>
<code class="literal">open_sync</code> (write WAL files with <code class="function">open()</code> option <code class="symbol">O_SYNC</code>)
</p></li></ul></div><p>
Not all of these choices are available on all platforms.
The default is the first method in the above list that is supported
by the platform, except that <code class="literal">fdatasync</code> is the default on
Linux and FreeBSD. The default is not necessarily ideal; it might be
necessary to change this setting or other aspects of your system
configuration in order to create a crash-safe configuration or
achieve optimal performance.
These aspects are discussed in <a class="xref" href="wal-reliability.html" title="30.1. Reliability">Section 30.1</a>.
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd><dt id="GUC-FULL-PAGE-WRITES"><span class="term"><code class="varname">full_page_writes</code> (<code class="type">boolean</code>)
<a id="id-1.6.7.8.3.2.5.1.3" class="indexterm"></a>
</span> <a href="#GUC-FULL-PAGE-WRITES" class="id_link">#</a></dt><dd><p>
When this parameter is on, the <span class="productname">PostgreSQL</span> server
writes the entire content of each disk page to WAL during the
first modification of that page after a checkpoint.
This is needed because
a page write that is in process during an operating system crash might
be only partially completed, leading to an on-disk page
that contains a mix of old and new data. The row-level change data
normally stored in WAL will not be enough to completely restore
such a page during post-crash recovery. Storing the full page image
guarantees that the page can be correctly restored, but at the price
of increasing the amount of data that must be written to WAL.
(Because WAL replay always starts from a checkpoint, it is sufficient
to do this during the first change of each page after a checkpoint.
Therefore, one way to reduce the cost of full-page writes is to
increase the checkpoint interval parameters.)
</p><p>
Turning this parameter off speeds normal operation, but
might lead to either unrecoverable data corruption, or silent
data corruption, after a system failure. The risks are similar to turning off
<code class="varname">fsync</code>, though smaller, and it should be turned off
only based on the same circumstances recommended for that parameter.
</p><p>
Turning off this parameter does not affect use of
WAL archiving for point-in-time recovery (PITR)
(see <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>).
</p><p>
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
The default is <code class="literal">on</code>.
</p></dd><dt id="GUC-WAL-LOG-HINTS"><span class="term"><code class="varname">wal_log_hints</code> (<code class="type">boolean</code>)
<a id="id-1.6.7.8.3.2.6.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-LOG-HINTS" class="id_link">#</a></dt><dd><p>
When this parameter is <code class="literal">on</code>, the <span class="productname">PostgreSQL</span>
server writes the entire content of each disk page to WAL during the
first modification of that page after a checkpoint, even for
non-critical modifications of so-called hint bits.
</p><p>
If data checksums are enabled, hint bit updates are always WAL-logged
and this setting is ignored. You can use this setting to test how much
extra WAL-logging would occur if your database had data checksums
enabled.
</p><p>
This parameter can only be set at server start. The default value is <code class="literal">off</code>.
</p></dd><dt id="GUC-WAL-COMPRESSION"><span class="term"><code class="varname">wal_compression</code> (<code class="type">enum</code>)
<a id="id-1.6.7.8.3.2.7.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-COMPRESSION" class="id_link">#</a></dt><dd><p>
This parameter enables compression of WAL using the specified
compression method.
When enabled, the <span class="productname">PostgreSQL</span>
server compresses full page images written to WAL when
<a class="xref" href="runtime-config-wal.html#GUC-FULL-PAGE-WRITES">full_page_writes</a> is on or during a base backup.
A compressed page image will be decompressed during WAL replay.
The supported methods are <code class="literal">pglz</code>,
<code class="literal">lz4</code> (if <span class="productname">PostgreSQL</span>
was compiled with <code class="option">--with-lz4</code>) and
<code class="literal">zstd</code> (if <span class="productname">PostgreSQL</span>
was compiled with <code class="option">--with-zstd</code>).
The default value is <code class="literal">off</code>.
Only superusers and users with the appropriate <code class="literal">SET</code>
privilege can change this setting.
</p><p>
Enabling compression can reduce the WAL volume without
increasing the risk of unrecoverable data corruption,
but at the cost of some extra CPU spent on the compression during
WAL logging and on the decompression during WAL replay.
</p></dd><dt id="GUC-WAL-INIT-ZERO"><span class="term"><code class="varname">wal_init_zero</code> (<code class="type">boolean</code>)
<a id="id-1.6.7.8.3.2.8.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-INIT-ZERO" class="id_link">#</a></dt><dd><p>
If set to <code class="literal">on</code> (the default), this option causes new
WAL files to be filled with zeroes. On some file systems, this ensures
that space is allocated before we need to write WAL records. However,
<em class="firstterm">Copy-On-Write</em> (COW) file systems may not benefit
from this technique, so the option is given to skip the unnecessary
work. If set to <code class="literal">off</code>, only the final byte is written
when the file is created so that it has the expected size.
</p></dd><dt id="GUC-WAL-RECYCLE"><span class="term"><code class="varname">wal_recycle</code> (<code class="type">boolean</code>)
<a id="id-1.6.7.8.3.2.9.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-RECYCLE" class="id_link">#</a></dt><dd><p>
If set to <code class="literal">on</code> (the default), this option causes WAL
files to be recycled by renaming them, avoiding the need to create new
ones. On COW file systems, it may be faster to create new ones, so the
option is given to disable this behavior.
</p></dd><dt id="GUC-WAL-BUFFERS"><span class="term"><code class="varname">wal_buffers</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.3.2.10.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-BUFFERS" class="id_link">#</a></dt><dd><p>
The amount of shared memory used for WAL data that has not yet been
written to disk. The default setting of -1 selects a size equal to
1/32nd (about 3%) of <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>, but not less
than <code class="literal">64kB</code> nor more than the size of one WAL
segment, typically <code class="literal">16MB</code>. This value can be set
manually if the automatic choice is too large or too small,
but any positive value less than <code class="literal">32kB</code> will be
treated as <code class="literal">32kB</code>.
If this value is specified without units, it is taken as WAL blocks,
that is <code class="symbol">XLOG_BLCKSZ</code> bytes, typically 8kB.
This parameter can only be set at server start.
</p><p>
The contents of the WAL buffers are written out to disk at every
transaction commit, so extremely large values are unlikely to
provide a significant benefit. However, setting this value to at
least a few megabytes can improve write performance on a busy
server where many clients are committing at once. The auto-tuning
selected by the default setting of -1 should give reasonable
results in most cases.
</p></dd><dt id="GUC-WAL-WRITER-DELAY"><span class="term"><code class="varname">wal_writer_delay</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.3.2.11.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-WRITER-DELAY" class="id_link">#</a></dt><dd><p>
Specifies how often the WAL writer flushes WAL, in time terms.
After flushing WAL the writer sleeps for the length of time given
by <code class="varname">wal_writer_delay</code>, unless woken up sooner
by an asynchronously committing transaction. If the last flush
happened less than <code class="varname">wal_writer_delay</code> ago and less
than <code class="varname">wal_writer_flush_after</code> worth of WAL has been
produced since, then WAL is only written to the operating system, not
flushed to disk.
If this value is specified without units, it is taken as milliseconds.
The default value is 200 milliseconds (<code class="literal">200ms</code>). Note that
on many systems, the effective resolution of sleep delays is 10
milliseconds; setting <code class="varname">wal_writer_delay</code> to a value that is
not a multiple of 10 might have the same results as setting it to the
next higher multiple of 10. This parameter can only be set in the
<code class="filename">postgresql.conf</code> file or on the server command line.
</p></dd><dt id="GUC-WAL-WRITER-FLUSH-AFTER"><span class="term"><code class="varname">wal_writer_flush_after</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.3.2.12.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-WRITER-FLUSH-AFTER" class="id_link">#</a></dt><dd><p>
Specifies how often the WAL writer flushes WAL, in volume terms.
If the last flush happened less
than <code class="varname">wal_writer_delay</code> ago and less
than <code class="varname">wal_writer_flush_after</code> worth of WAL has been
produced since, then WAL is only written to the operating system, not
flushed to disk. If <code class="varname">wal_writer_flush_after</code> is set
to <code class="literal">0</code> then WAL data is always flushed immediately.
If this value is specified without units, it is taken as WAL blocks,
that is <code class="symbol">XLOG_BLCKSZ</code> bytes, typically 8kB.
The default is <code class="literal">1MB</code>.
This parameter can only be set in the
<code class="filename">postgresql.conf</code> file or on the server command line.
</p></dd><dt id="GUC-WAL-SKIP-THRESHOLD"><span class="term"><code class="varname">wal_skip_threshold</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.3.2.13.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-SKIP-THRESHOLD" class="id_link">#</a></dt><dd><p>
When <code class="varname">wal_level</code> is <code class="literal">minimal</code> and a
transaction commits after creating or rewriting a permanent relation,
this setting determines how to persist the new data. If the data is
smaller than this setting, write it to the WAL log; otherwise, use an
fsync of affected files. Depending on the properties of your storage,
raising or lowering this value might help if such commits are slowing
concurrent transactions. If this value is specified without units, it
is taken as kilobytes. The default is two megabytes
(<code class="literal">2MB</code>).
</p></dd><dt id="GUC-COMMIT-DELAY"><span class="term"><code class="varname">commit_delay</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.3.2.14.1.3" class="indexterm"></a>
</span> <a href="#GUC-COMMIT-DELAY" class="id_link">#</a></dt><dd><p>
Setting <code class="varname">commit_delay</code> adds a time delay
before a WAL flush is initiated. This can improve
group commit throughput by allowing a larger number of transactions
to commit via a single WAL flush, if system load is high enough
that additional transactions become ready to commit within the
given interval. However, it also increases latency by up to the
<code class="varname">commit_delay</code> for each WAL
flush. Because the delay is just wasted if no other transactions
become ready to commit, a delay is only performed if at least
<code class="varname">commit_siblings</code> other transactions are active
when a flush is about to be initiated. Also, no delays are
performed if <code class="varname">fsync</code> is disabled.
If this value is specified without units, it is taken as microseconds.
The default <code class="varname">commit_delay</code> is zero (no delay).
Only superusers and users with the appropriate <code class="literal">SET</code>
privilege can change this setting.
</p><p>
In <span class="productname">PostgreSQL</span> releases prior to 9.3,
<code class="varname">commit_delay</code> behaved differently and was much
less effective: it affected only commits, rather than all WAL flushes,
and waited for the entire configured delay even if the WAL flush
was completed sooner. Beginning in <span class="productname">PostgreSQL</span> 9.3,
the first process that becomes ready to flush waits for the configured
interval, while subsequent processes wait only until the leader
completes the flush operation.
</p></dd><dt id="GUC-COMMIT-SIBLINGS"><span class="term"><code class="varname">commit_siblings</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.3.2.15.1.3" class="indexterm"></a>
</span> <a href="#GUC-COMMIT-SIBLINGS" class="id_link">#</a></dt><dd><p>
Minimum number of concurrent open transactions to require
before performing the <code class="varname">commit_delay</code> delay. A larger
value makes it more probable that at least one other
transaction will become ready to commit during the delay
interval. The default is five transactions.
</p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-CHECKPOINTS"><div class="titlepage"><div><div><h3 class="title">20.5.2. Checkpoints <a href="#RUNTIME-CONFIG-WAL-CHECKPOINTS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-CHECKPOINT-TIMEOUT"><span class="term"><code class="varname">checkpoint_timeout</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.4.2.1.1.3" class="indexterm"></a>
</span> <a href="#GUC-CHECKPOINT-TIMEOUT" class="id_link">#</a></dt><dd><p>
Maximum time between automatic WAL checkpoints.
If this value is specified without units, it is taken as seconds.
The valid range is between 30 seconds and one day.
The default is five minutes (<code class="literal">5min</code>).
Increasing this parameter can increase the amount of time needed
for crash recovery.
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd><dt id="GUC-CHECKPOINT-COMPLETION-TARGET"><span class="term"><code class="varname">checkpoint_completion_target</code> (<code class="type">floating point</code>)
<a id="id-1.6.7.8.4.2.2.1.3" class="indexterm"></a>
</span> <a href="#GUC-CHECKPOINT-COMPLETION-TARGET" class="id_link">#</a></dt><dd><p>
Specifies the target of checkpoint completion, as a fraction of
total time between checkpoints. The default is 0.9, which spreads the
checkpoint across almost all of the available interval, providing fairly
consistent I/O load while also leaving some time for checkpoint
completion overhead. Reducing this parameter is not recommended because
it causes the checkpoint to complete faster. This results in a higher
rate of I/O during the checkpoint followed by a period of less I/O between
the checkpoint completion and the next scheduled checkpoint. This
parameter can only be set in the <code class="filename">postgresql.conf</code> file
or on the server command line.
</p></dd><dt id="GUC-CHECKPOINT-FLUSH-AFTER"><span class="term"><code class="varname">checkpoint_flush_after</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.4.2.3.1.3" class="indexterm"></a>
</span> <a href="#GUC-CHECKPOINT-FLUSH-AFTER" class="id_link">#</a></dt><dd><p>
Whenever more than this amount of data has been
written while performing a checkpoint, attempt to force the
OS to issue these writes to the underlying storage. Doing so will
limit the amount of dirty data in the kernel's page cache, reducing
the likelihood of stalls when an <code class="function">fsync</code> is issued at the end of the
checkpoint, or when the OS writes data back in larger batches in the
background. Often that will result in greatly reduced transaction
latency, but there also are some cases, especially with workloads
that are bigger than <a class="xref" href="runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</a>, but smaller
than the OS's page cache, where performance might degrade. This
setting may have no effect on some platforms.
If this value is specified without units, it is taken as blocks,
that is <code class="symbol">BLCKSZ</code> bytes, typically 8kB.
The valid range is
between <code class="literal">0</code>, which disables forced writeback,
and <code class="literal">2MB</code>. The default is <code class="literal">256kB</code> on
Linux, <code class="literal">0</code> elsewhere. (If <code class="symbol">BLCKSZ</code> is not
8kB, the default and maximum values scale proportionally to it.)
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd><dt id="GUC-CHECKPOINT-WARNING"><span class="term"><code class="varname">checkpoint_warning</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.4.2.4.1.3" class="indexterm"></a>
</span> <a href="#GUC-CHECKPOINT-WARNING" class="id_link">#</a></dt><dd><p>
Write a message to the server log if checkpoints caused by
the filling of WAL segment files happen closer together
than this amount of time (which suggests that
<code class="varname">max_wal_size</code> ought to be raised).
If this value is specified without units, it is taken as seconds.
The default is 30 seconds (<code class="literal">30s</code>).
Zero disables the warning.
No warnings will be generated if <code class="varname">checkpoint_timeout</code>
is less than <code class="varname">checkpoint_warning</code>.
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd><dt id="GUC-MAX-WAL-SIZE"><span class="term"><code class="varname">max_wal_size</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.4.2.5.1.3" class="indexterm"></a>
</span> <a href="#GUC-MAX-WAL-SIZE" class="id_link">#</a></dt><dd><p>
Maximum size to let the WAL grow during automatic
checkpoints. This is a soft limit; WAL size can exceed
<code class="varname">max_wal_size</code> under special circumstances, such as
heavy load, a failing <code class="varname">archive_command</code> or <code class="varname">archive_library</code>, or a high
<code class="varname">wal_keep_size</code> setting.
If this value is specified without units, it is taken as megabytes.
The default is 1 GB.
Increasing this parameter can increase the amount of time needed for
crash recovery.
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd><dt id="GUC-MIN-WAL-SIZE"><span class="term"><code class="varname">min_wal_size</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.4.2.6.1.3" class="indexterm"></a>
</span> <a href="#GUC-MIN-WAL-SIZE" class="id_link">#</a></dt><dd><p>
As long as WAL disk usage stays below this setting, old WAL files are
always recycled for future use at a checkpoint, rather than removed.
This can be used to ensure that enough WAL space is reserved to
handle spikes in WAL usage, for example when running large batch
jobs.
If this value is specified without units, it is taken as megabytes.
The default is 80 MB.
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-ARCHIVING"><div class="titlepage"><div><div><h3 class="title">20.5.3. Archiving <a href="#RUNTIME-CONFIG-WAL-ARCHIVING" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-ARCHIVE-MODE"><span class="term"><code class="varname">archive_mode</code> (<code class="type">enum</code>)
<a id="id-1.6.7.8.5.2.1.1.3" class="indexterm"></a>
</span> <a href="#GUC-ARCHIVE-MODE" class="id_link">#</a></dt><dd><p>
When <code class="varname">archive_mode</code> is enabled, completed WAL segments
are sent to archive storage by setting
<a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
<a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a>. In addition to <code class="literal">off</code>,
to disable, there are two modes: <code class="literal">on</code>, and
<code class="literal">always</code>. During normal operation, there is no
difference between the two modes, but when set to <code class="literal">always</code>
the WAL archiver is enabled also during archive recovery or standby
mode. In <code class="literal">always</code> mode, all files restored from the archive
or streamed with streaming replication will be archived (again). See
<a class="xref" href="warm-standby.html#CONTINUOUS-ARCHIVING-IN-STANDBY" title="27.2.9. Continuous Archiving in Standby">Section 27.2.9</a> for details.
</p><p>
<code class="varname">archive_mode</code> is a separate setting from
<code class="varname">archive_command</code> and
<code class="varname">archive_library</code> so that
<code class="varname">archive_command</code> and
<code class="varname">archive_library</code> can be changed without leaving
archiving mode.
This parameter can only be set at server start.
<code class="varname">archive_mode</code> cannot be enabled when
<code class="varname">wal_level</code> is set to <code class="literal">minimal</code>.
</p></dd><dt id="GUC-ARCHIVE-COMMAND"><span class="term"><code class="varname">archive_command</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.5.2.2.1.3" class="indexterm"></a>
</span> <a href="#GUC-ARCHIVE-COMMAND" class="id_link">#</a></dt><dd><p>
The local shell command to execute to archive a completed WAL file
segment. Any <code class="literal">%p</code> in the string is
replaced by the path name of the file to archive, and any
<code class="literal">%f</code> is replaced by only the file name.
(The path name is relative to the working directory of the server,
i.e., the cluster's data directory.)
Use <code class="literal">%%</code> to embed an actual <code class="literal">%</code> character in the
command. It is important for the command to return a zero
exit status only if it succeeds. For more information see
<a class="xref" href="continuous-archiving.html#BACKUP-ARCHIVING-WAL" title="26.3.1. Setting Up WAL Archiving">Section 26.3.1</a>.
</p><p>
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line. It is only used if
<code class="varname">archive_mode</code> was enabled at server start and
<code class="varname">archive_library</code> is set to an empty string. If both
<code class="varname">archive_command</code> and <code class="varname">archive_library</code>
are set, an error will be raised.
If <code class="varname">archive_command</code> is an empty string (the default) while
<code class="varname">archive_mode</code> is enabled (and <code class="varname">archive_library</code>
is set to an empty string), WAL archiving is temporarily
disabled, but the server continues to accumulate WAL segment files in
the expectation that a command will soon be provided. Setting
<code class="varname">archive_command</code> to a command that does nothing but
return true, e.g., <code class="literal">/bin/true</code> (<code class="literal">REM</code> on
Windows), effectively disables
archiving, but also breaks the chain of WAL files needed for
archive recovery, so it should only be used in unusual circumstances.
</p></dd><dt id="GUC-ARCHIVE-LIBRARY"><span class="term"><code class="varname">archive_library</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.5.2.3.1.3" class="indexterm"></a>
</span> <a href="#GUC-ARCHIVE-LIBRARY" class="id_link">#</a></dt><dd><p>
The library to use for archiving completed WAL file segments. If set to
an empty string (the default), archiving via shell is enabled, and
<a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> is used. If both
<code class="varname">archive_command</code> and <code class="varname">archive_library</code>
are set, an error will be raised. Otherwise, the specified
shared library is used for archiving. The WAL archiver process is
restarted by the postmaster when this parameter changes. For more
information, see <a class="xref" href="continuous-archiving.html#BACKUP-ARCHIVING-WAL" title="26.3.1. Setting Up WAL Archiving">Section 26.3.1</a> and
<a class="xref" href="archive-modules.html" title="Chapter 51. Archive Modules">Chapter 51</a>.
</p><p>
This parameter can only be set in the
<code class="filename">postgresql.conf</code> file or on the server command line.
</p></dd><dt id="GUC-ARCHIVE-TIMEOUT"><span class="term"><code class="varname">archive_timeout</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.5.2.4.1.3" class="indexterm"></a>
</span> <a href="#GUC-ARCHIVE-TIMEOUT" class="id_link">#</a></dt><dd><p>
The <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> is only invoked for
completed WAL segments. Hence, if your server generates little WAL
traffic (or has slack periods where it does so), there could be a
long delay between the completion of a transaction and its safe
recording in archive storage. To limit how old unarchived
data can be, you can set <code class="varname">archive_timeout</code> to force the
server to switch to a new WAL segment file periodically. When this
parameter is greater than zero, the server will switch to a new
segment file whenever this amount of time has elapsed since the last
segment file switch, and there has been any database activity,
including a single checkpoint (checkpoints are skipped if there is
no database activity). Note that archived files that are closed
early due to a forced switch are still the same length as completely
full files. Therefore, it is unwise to use a very short
<code class="varname">archive_timeout</code> — it will bloat your archive
storage. <code class="varname">archive_timeout</code> settings of a minute or so are
usually reasonable. You should consider using streaming replication,
instead of archiving, if you want data to be copied off the primary
server more quickly than that.
If this value is specified without units, it is taken as seconds.
This parameter can only be set in the
<code class="filename">postgresql.conf</code> file or on the server command line.
</p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-RECOVERY"><div class="titlepage"><div><div><h3 class="title">20.5.4. Recovery <a href="#RUNTIME-CONFIG-WAL-RECOVERY" class="id_link">#</a></h3></div></div></div><a id="id-1.6.7.8.6.2" class="indexterm"></a><p>
This section describes the settings that apply to recovery in general,
affecting crash recovery, streaming replication and archive-based
replication.
</p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RECOVERY-PREFETCH"><span class="term"><code class="varname">recovery_prefetch</code> (<code class="type">enum</code>)
<a id="id-1.6.7.8.6.4.1.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-PREFETCH" class="id_link">#</a></dt><dd><p>
Whether to try to prefetch blocks that are referenced in the WAL that
are not yet in the buffer pool, during recovery. Valid values are
<code class="literal">off</code>, <code class="literal">on</code> and
<code class="literal">try</code> (the default). The setting
<code class="literal">try</code> enables
prefetching only if the operating system provides the
<code class="function">posix_fadvise</code> function, which is currently used
to implement prefetching. Note that some operating systems provide the
function, but it doesn't do anything.
</p><p>
Prefetching blocks that will soon be needed can reduce I/O wait times
during recovery with some workloads.
See also the <a class="xref" href="runtime-config-wal.html#GUC-WAL-DECODE-BUFFER-SIZE">wal_decode_buffer_size</a> and
<a class="xref" href="runtime-config-resource.html#GUC-MAINTENANCE-IO-CONCURRENCY">maintenance_io_concurrency</a> settings, which limit
prefetching activity.
</p></dd><dt id="GUC-WAL-DECODE-BUFFER-SIZE"><span class="term"><code class="varname">wal_decode_buffer_size</code> (<code class="type">integer</code>)
<a id="id-1.6.7.8.6.4.2.1.3" class="indexterm"></a>
</span> <a href="#GUC-WAL-DECODE-BUFFER-SIZE" class="id_link">#</a></dt><dd><p>
A limit on how far ahead the server can look in the WAL, to find
blocks to prefetch. If this value is specified without units, it is
taken as bytes.
The default is 512kB.
</p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY"><div class="titlepage"><div><div><h3 class="title">20.5.5. Archive Recovery <a href="#RUNTIME-CONFIG-WAL-ARCHIVE-RECOVERY" class="id_link">#</a></h3></div></div></div><a id="id-1.6.7.8.7.2" class="indexterm"></a><p>
This section describes the settings that apply only for the duration of
the recovery. They must be reset for any subsequent recovery you wish to
perform.
</p><p>
<span class="quote">“<span class="quote">Recovery</span>”</span> covers using the server as a standby or for
executing a targeted recovery. Typically, standby mode would be used to
provide high availability and/or read scalability, whereas a targeted
recovery is used to recover from data loss.
</p><p>
To start the server in standby mode, create a file called
<code class="filename">standby.signal</code><a id="id-1.6.7.8.7.5.2" class="indexterm"></a>
in the data directory. The server will enter recovery and will not stop
recovery when the end of archived WAL is reached, but will keep trying to
continue recovery by connecting to the sending server as specified by the
<code class="varname">primary_conninfo</code> setting and/or by fetching new WAL
segments using <code class="varname">restore_command</code>. For this mode, the
parameters from this section and <a class="xref" href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY" title="20.6.3. Standby Servers">Section 20.6.3</a> are of interest.
Parameters from <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET" title="20.5.6. Recovery Target">Section 20.5.6</a> will
also be applied but are typically not useful in this mode.
</p><p>
To start the server in targeted recovery mode, create a file called
<code class="filename">recovery.signal</code><a id="id-1.6.7.8.7.6.2" class="indexterm"></a>
in the data directory. If both <code class="filename">standby.signal</code> and
<code class="filename">recovery.signal</code> files are created, standby mode
takes precedence. Targeted recovery mode ends when the archived WAL is
fully replayed, or when <code class="varname">recovery_target</code> is reached.
In this mode, the parameters from both this section and <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET" title="20.5.6. Recovery Target">Section 20.5.6</a> will be used.
</p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RESTORE-COMMAND"><span class="term"><code class="varname">restore_command</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.7.7.1.1.3" class="indexterm"></a>
</span> <a href="#GUC-RESTORE-COMMAND" class="id_link">#</a></dt><dd><p>
The local shell command to execute to retrieve an archived segment of
the WAL file series. This parameter is required for archive recovery,
but optional for streaming replication.
Any <code class="literal">%f</code> in the string is
replaced by the name of the file to retrieve from the archive,
and any <code class="literal">%p</code> is replaced by the copy destination path name
on the server.
(The path name is relative to the current working directory,
i.e., the cluster's data directory.)
Any <code class="literal">%r</code> is replaced by the name of the file containing the
last valid restart point. That is the earliest file that must be kept
to allow a restore to be restartable, so this information can be used
to truncate the archive to just the minimum required to support
restarting from the current restore. <code class="literal">%r</code> is typically only
used by warm-standby configurations
(see <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>).
Write <code class="literal">%%</code> to embed an actual <code class="literal">%</code> character.
</p><p>
It is important for the command to return a zero exit status
only if it succeeds. The command <span class="emphasis"><em>will</em></span> be asked for file
names that are not present in the archive; it must return nonzero
when so asked. Examples:
</p><pre class="programlisting">
restore_command = 'cp /mnt/server/archivedir/%f "%p"'
restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
</pre><p>
An exception is that if the command was terminated by a signal (other
than <span class="systemitem">SIGTERM</span>, which is used as part of a
database server shutdown) or an error by the shell (such as command
not found), then recovery will abort and the server will not start up.
</p><p>
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd><dt id="GUC-ARCHIVE-CLEANUP-COMMAND"><span class="term"><code class="varname">archive_cleanup_command</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.7.7.2.1.3" class="indexterm"></a>
</span> <a href="#GUC-ARCHIVE-CLEANUP-COMMAND" class="id_link">#</a></dt><dd><p>
This optional parameter specifies a shell command that will be executed
at every restartpoint. The purpose of
<code class="varname">archive_cleanup_command</code> is to provide a mechanism for
cleaning up old archived WAL files that are no longer needed by the
standby server.
Any <code class="literal">%r</code> is replaced by the name of the file containing the
last valid restart point.
That is the earliest file that must be <span class="emphasis"><em>kept</em></span> to allow a
restore to be restartable, and so all files earlier than <code class="literal">%r</code>
may be safely removed.
This information can be used to truncate the archive to just the
minimum required to support restart from the current restore.
The <a class="xref" href="pgarchivecleanup.html" title="pg_archivecleanup"><span class="refentrytitle"><span class="application">pg_archivecleanup</span></span></a> module
is often used in <code class="varname">archive_cleanup_command</code> for
single-standby configurations, for example:
</p><pre class="programlisting">archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</pre><p>
Note however that if multiple standby servers are restoring from the
same archive directory, you will need to ensure that you do not delete
WAL files until they are no longer needed by any of the servers.
<code class="varname">archive_cleanup_command</code> would typically be used in a
warm-standby configuration (see <a class="xref" href="warm-standby.html" title="27.2. Log-Shipping Standby Servers">Section 27.2</a>).
Write <code class="literal">%%</code> to embed an actual <code class="literal">%</code> character in the
command.
</p><p>
If the command returns a nonzero exit status then a warning log
message will be written. An exception is that if the command was
terminated by a signal or an error by the shell (such as command not
found), a fatal error will be raised.
</p><p>
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd><dt id="GUC-RECOVERY-END-COMMAND"><span class="term"><code class="varname">recovery_end_command</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.7.7.3.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-END-COMMAND" class="id_link">#</a></dt><dd><p>
This parameter specifies a shell command that will be executed once only
at the end of recovery. This parameter is optional. The purpose of the
<code class="varname">recovery_end_command</code> is to provide a mechanism for cleanup
following replication or recovery.
Any <code class="literal">%r</code> is replaced by the name of the file containing the
last valid restart point, like in <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-CLEANUP-COMMAND">archive_cleanup_command</a>.
</p><p>
If the command returns a nonzero exit status then a warning log
message will be written and the database will proceed to start up
anyway. An exception is that if the command was terminated by a
signal or an error by the shell (such as command not found), the
database will not proceed with startup.
</p><p>
This parameter can only be set in the <code class="filename">postgresql.conf</code>
file or on the server command line.
</p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-WAL-RECOVERY-TARGET"><div class="titlepage"><div><div><h3 class="title">20.5.6. Recovery Target <a href="#RUNTIME-CONFIG-WAL-RECOVERY-TARGET" class="id_link">#</a></h3></div></div></div><p>
By default, recovery will recover to the end of the WAL log. The
following parameters can be used to specify an earlier stopping point.
At most one of <code class="varname">recovery_target</code>,
<code class="varname">recovery_target_lsn</code>, <code class="varname">recovery_target_name</code>,
<code class="varname">recovery_target_time</code>, or <code class="varname">recovery_target_xid</code>
can be used; if more than one of these is specified in the configuration
file, an error will be raised.
These parameters can only be set at server start.
</p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RECOVERY-TARGET"><span class="term"><code class="varname">recovery_target</code><code class="literal"> = 'immediate'</code>
<a id="id-1.6.7.8.8.3.1.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET" class="id_link">#</a></dt><dd><p>
This parameter specifies that recovery should end as soon as a
consistent state is reached, i.e., as early as possible. When restoring
from an online backup, this means the point where taking the backup
ended.
</p><p>
Technically, this is a string parameter, but <code class="literal">'immediate'</code>
is currently the only allowed value.
</p></dd><dt id="GUC-RECOVERY-TARGET-NAME"><span class="term"><code class="varname">recovery_target_name</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.8.3.2.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET-NAME" class="id_link">#</a></dt><dd><p>
This parameter specifies the named restore point (created with
<code class="function">pg_create_restore_point()</code>) to which recovery will proceed.
</p></dd><dt id="GUC-RECOVERY-TARGET-TIME"><span class="term"><code class="varname">recovery_target_time</code> (<code class="type">timestamp</code>)
<a id="id-1.6.7.8.8.3.3.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET-TIME" class="id_link">#</a></dt><dd><p>
This parameter specifies the time stamp up to which recovery
will proceed.
The precise stopping point is also influenced by
<a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-INCLUSIVE">recovery_target_inclusive</a>.
</p><p>
The value of this parameter is a time stamp in the same format
accepted by the <code class="type">timestamp with time zone</code> data type,
except that you cannot use a time zone abbreviation (unless the
<a class="xref" href="runtime-config-client.html#GUC-TIMEZONE-ABBREVIATIONS">timezone_abbreviations</a> variable has been set
earlier in the configuration file). Preferred style is to use a
numeric offset from UTC, or you can write a full time zone name,
e.g., <code class="literal">Europe/Helsinki</code> not <code class="literal">EEST</code>.
</p></dd><dt id="GUC-RECOVERY-TARGET-XID"><span class="term"><code class="varname">recovery_target_xid</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.8.3.4.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET-XID" class="id_link">#</a></dt><dd><p>
This parameter specifies the transaction ID up to which recovery
will proceed. Keep in mind
that while transaction IDs are assigned sequentially at transaction
start, transactions can complete in a different numeric order.
The transactions that will be recovered are those that committed
before (and optionally including) the specified one.
The precise stopping point is also influenced by
<a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-INCLUSIVE">recovery_target_inclusive</a>.
</p></dd><dt id="GUC-RECOVERY-TARGET-LSN"><span class="term"><code class="varname">recovery_target_lsn</code> (<code class="type">pg_lsn</code>)
<a id="id-1.6.7.8.8.3.5.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET-LSN" class="id_link">#</a></dt><dd><p>
This parameter specifies the LSN of the write-ahead log location up
to which recovery will proceed. The precise stopping point is also
influenced by <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-INCLUSIVE">recovery_target_inclusive</a>. This
parameter is parsed using the system data type
<a class="link" href="datatype-pg-lsn.html" title="8.20. pg_lsn Type"><code class="type">pg_lsn</code></a>.
</p></dd></dl></div><p>
The following options further specify the recovery target, and affect
what happens when the target is reached:
</p><div class="variablelist"><dl class="variablelist"><dt id="GUC-RECOVERY-TARGET-INCLUSIVE"><span class="term"><code class="varname">recovery_target_inclusive</code> (<code class="type">boolean</code>)
<a id="id-1.6.7.8.8.5.1.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET-INCLUSIVE" class="id_link">#</a></dt><dd><p>
Specifies whether to stop just after the specified recovery target
(<code class="literal">on</code>), or just before the recovery target
(<code class="literal">off</code>).
Applies when <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-LSN">recovery_target_lsn</a>,
<a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-TIME">recovery_target_time</a>, or
<a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-XID">recovery_target_xid</a> is specified.
This setting controls whether transactions
having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will
be included in the recovery. Default is <code class="literal">on</code>.
</p></dd><dt id="GUC-RECOVERY-TARGET-TIMELINE"><span class="term"><code class="varname">recovery_target_timeline</code> (<code class="type">string</code>)
<a id="id-1.6.7.8.8.5.2.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET-TIMELINE" class="id_link">#</a></dt><dd><p>
Specifies recovering into a particular timeline. The value can be a
numeric timeline ID or a special value. The value
<code class="literal">current</code> recovers along the same timeline that was
current when the base backup was taken. The
value <code class="literal">latest</code> recovers
to the latest timeline found in the archive, which is useful in
a standby server. <code class="literal">latest</code> is the default.
</p><p>
To specify a timeline ID in hexadecimal (for example, if extracted
from a WAL file name or history file), prefix it with a
<code class="literal">0x</code>. For instance, if the WAL file name is
<code class="filename">00000011000000A10000004F</code>, then the timeline ID is
<code class="literal">0x11</code> (or 17 decimal).
</p><p>
You usually only need to set this parameter
in complex re-recovery situations, where you need to return to
a state that itself was reached after a point-in-time recovery.
See <a class="xref" href="continuous-archiving.html#BACKUP-TIMELINES" title="26.3.5. Timelines">Section 26.3.5</a> for discussion.
</p></dd><dt id="GUC-RECOVERY-TARGET-ACTION"><span class="term"><code class="varname">recovery_target_action</code> (<code class="type">enum</code>)
<a id="id-1.6.7.8.8.5.3.1.3" class="indexterm"></a>
</span> <a href="#GUC-RECOVERY-TARGET-ACTION" class="id_link">#</a></dt><dd><p>
Specifies what action the server should take once the recovery target is
reached. The default is <code class="literal">pause</code>, which means recovery will
be paused. <code class="literal">promote</code> means the recovery process will finish
and the server will start to accept connections.
Finally <code class="literal">shutdown</code> will stop the server after reaching the
recovery target.
</p><p>
The intended use of the <code class="literal">pause</code> setting is to allow queries
to be executed against the database to check if this recovery target
is the most desirable point for recovery.
The paused state can be resumed by
using <code class="function">pg_wal_replay_resume()</code> (see
<a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL-TABLE" title="Table 9.93. Recovery Control Functions">Table 9.93</a>), which then
causes recovery to end. If this recovery target is not the
desired stopping point, then shut down the server, change the
recovery target settings to a later target and restart to
continue recovery.
</p><p>
The <code class="literal">shutdown</code> setting is useful to have the instance ready
at the exact replay point desired. The instance will still be able to
replay more WAL records (and in fact will have to replay WAL records
since the last checkpoint next time it is started).
</p><p>
Note that because <code class="filename">recovery.signal</code> will not be
removed when <code class="varname">recovery_target_action</code> is set to <code class="literal">shutdown</code>,
any subsequent start will end with immediate shutdown unless the
configuration is changed or the <code class="filename">recovery.signal</code>
file is removed manually.
</p><p>
This setting has no effect if no recovery target is set.
If <a class="xref" href="runtime-config-replication.html#GUC-HOT-STANDBY">hot_standby</a> is not enabled, a setting of
<code class="literal">pause</code> will act the same as <code class="literal">shutdown</code>.
If the recovery target is reached while a promotion is ongoing,
a setting of <code class="literal">pause</code> will act the same as
<code class="literal">promote</code>.
</p><p>
In any case, if a recovery target is configured but the archive
recovery ends before the target is reached, the server will shut down
with a fatal error.
</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-resource.html" title="20.4. Resource Consumption">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-replication.html" title="20.6. Replication">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.4. Resource Consumption </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 20.6. Replication</td></tr></table></div></body></html>