mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-23 13:50:40 +02:00
doc: improve description of synchronous_commit modes
Previously it wasn't clear exactly what each of the synchronous_commit modes accomplished. This clarifies that, and adds a table describing it. Only backpatched through 9.6 since 9.5 doesn't have all the options. Reported-by: kghost0@gmail.com Discussion: https://postgr.es/m/159741195522.14321.13812604195366728976@wrigleys.postgresql.org Backpatch-through: 9.6
This commit is contained in:
parent
85834023a9
commit
3c4b520685
@ -2432,14 +2432,26 @@ include_dir 'conf.d'
|
|||||||
</term>
|
</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Specifies whether transaction commit will wait for WAL records
|
Specifies how much WAL processing must complete before
|
||||||
to be written to disk before the command returns a <quote>success</quote>
|
the database server returns a <quote>success</quote>
|
||||||
indication to the client. Valid values are <literal>on</literal>,
|
indication to the client. Valid values are
|
||||||
<literal>remote_apply</literal>, <literal>remote_write</literal>, <literal>local</literal>,
|
<literal>remote_apply</literal>, <literal>on</literal>
|
||||||
and <literal>off</literal>. The default, and safe, setting
|
(the default), <literal>remote_write</literal>,
|
||||||
is <literal>on</literal>. When <literal>off</literal>, there can be a delay between
|
<literal>local</literal>, and <literal>off</literal>.
|
||||||
when success is reported to the client and when the transaction is
|
</para>
|
||||||
really guaranteed to be safe against a server crash. (The maximum
|
|
||||||
|
<para>
|
||||||
|
If <varname>synchronous_standby_names</varname> is empty,
|
||||||
|
the only meaningful settings are <literal>on</literal> and
|
||||||
|
<literal>off</literal>; <literal>remote_apply</literal>,
|
||||||
|
<literal>remote_write</literal> and <literal>local</literal>
|
||||||
|
all provide the same local synchronization level
|
||||||
|
as <literal>on</literal>. The local behavior of all
|
||||||
|
non-<literal>off</literal> modes is to wait for local flush of WAL
|
||||||
|
to disk. In <literal>off</literal> 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 <xref linkend="guc-wal-writer-delay"/>.) Unlike
|
delay is three times <xref linkend="guc-wal-writer-delay"/>.) Unlike
|
||||||
<xref linkend="guc-fsync"/>, setting this parameter to <literal>off</literal>
|
<xref linkend="guc-fsync"/>, setting this parameter to <literal>off</literal>
|
||||||
does not create any risk of database inconsistency: an operating
|
does not create any risk of database inconsistency: an operating
|
||||||
@ -2451,38 +2463,40 @@ include_dir 'conf.d'
|
|||||||
exact certainty about the durability of a transaction. For more
|
exact certainty about the durability of a transaction. For more
|
||||||
discussion see <xref linkend="wal-async-commit"/>.
|
discussion see <xref linkend="wal-async-commit"/>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If <xref linkend="guc-synchronous-standby-names"/> is non-empty, this
|
If <xref linkend="guc-synchronous-standby-names"/> is non-empty,
|
||||||
parameter also controls whether or not transaction commits will wait
|
<varname>synchronous_commit</varname> also controls whether
|
||||||
for their WAL records to be replicated to the standby server(s).
|
transaction commits will wait for their WAL records to be
|
||||||
When set to <literal>on</literal>, commits will wait until replies
|
processed on the standby server(s).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
When set to <literal>remote_apply</literal>, 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 <literal>on</literal>,
|
||||||
|
commits wait until replies
|
||||||
from the current synchronous standby(s) indicate they have received
|
from the current synchronous standby(s) indicate they have received
|
||||||
the commit record of the transaction and flushed it to disk. This
|
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
|
ensures the transaction will not be lost unless both the primary and
|
||||||
all synchronous standbys suffer corruption of their database storage.
|
all synchronous standbys suffer corruption of their database storage.
|
||||||
When set to <literal>remote_apply</literal>, 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).
|
|
||||||
When set to <literal>remote_write</literal>, commits will wait until replies
|
When set to <literal>remote_write</literal>, commits will wait until replies
|
||||||
from the current synchronous standby(s) indicate they have
|
from the current synchronous standby(s) indicate they have
|
||||||
received the commit record of the transaction and written it out to
|
received the commit record of the transaction and written it to
|
||||||
their operating system. This setting is sufficient to
|
their file systems. This setting ensures data preservation if a standby instance of
|
||||||
ensure data preservation even if a standby instance of
|
<productname>PostgreSQL</productname> crashes, but not if the standby
|
||||||
<productname>PostgreSQL</productname> were to crash, but not if the standby
|
suffers an operating-system-level crash because the data has not
|
||||||
suffers an operating-system-level crash, since the data has not
|
|
||||||
necessarily reached durable storage on the standby.
|
necessarily reached durable storage on the standby.
|
||||||
Finally, the setting <literal>local</literal> causes commits to wait for
|
The setting <literal>local</literal> causes commits to wait for
|
||||||
local flush to disk, but not for replication. This is not usually
|
local flush to disk, but not for replication. This is usually not
|
||||||
desirable when synchronous replication is in use, but is provided for
|
desirable when synchronous replication is in use, but is provided for
|
||||||
completeness.
|
completeness.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
|
||||||
If <varname>synchronous_standby_names</varname> is empty, the settings
|
|
||||||
<literal>on</literal>, <literal>remote_apply</literal>, <literal>remote_write</literal>
|
|
||||||
and <literal>local</literal> all provide the same synchronization level:
|
|
||||||
transaction commits only wait for local flush to disk.
|
|
||||||
</para>
|
|
||||||
<para>
|
<para>
|
||||||
This parameter can be changed at any time; the behavior for any
|
This parameter can be changed at any time; the behavior for any
|
||||||
one transaction is determined by the setting in effect when it
|
one transaction is determined by the setting in effect when it
|
||||||
@ -2492,6 +2506,76 @@ include_dir 'conf.d'
|
|||||||
asynchronously when the default is the opposite, issue <command>SET
|
asynchronously when the default is the opposite, issue <command>SET
|
||||||
LOCAL synchronous_commit TO OFF</command> within the transaction.
|
LOCAL synchronous_commit TO OFF</command> within the transaction.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<xref linkend="synchronous-commit-matrix"/> summarizes the
|
||||||
|
capabilities of the <varname>synchronous_commit</varname> settings.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<table id="synchronous-commit-matrix">
|
||||||
|
<title>synchronous_commit Modes</title>
|
||||||
|
<tgroup cols="5">
|
||||||
|
<colspec colname="col1" colwidth="1.1*"/>
|
||||||
|
<colspec colname="col2" colwidth="1*"/>
|
||||||
|
<colspec colname="col3" colwidth="1*"/>
|
||||||
|
<colspec colname="col4" colwidth="1*"/>
|
||||||
|
<colspec colname="col5" colwidth="1*"/>
|
||||||
|
<thead>
|
||||||
|
<row>
|
||||||
|
<entry>synchronous_commit setting</entry>
|
||||||
|
<entry>local durable commit</entry>
|
||||||
|
<entry>standby durable commit after PG crash</entry>
|
||||||
|
<entry>standby durable commit after OS crash</entry>
|
||||||
|
<entry>standby query consistency</entry>
|
||||||
|
</row>
|
||||||
|
</thead>
|
||||||
|
|
||||||
|
<tbody>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>remote_apply</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>on</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>remote_write</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>local</entry>
|
||||||
|
<entry align="center">•</entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>off</entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
<entry align="center"></entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table>
|
||||||
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
@ -68,7 +68,8 @@ typedef enum
|
|||||||
SYNCHRONOUS_COMMIT_REMOTE_WRITE, /* wait for local flush and remote
|
SYNCHRONOUS_COMMIT_REMOTE_WRITE, /* wait for local flush and remote
|
||||||
* write */
|
* write */
|
||||||
SYNCHRONOUS_COMMIT_REMOTE_FLUSH, /* wait for local and remote flush */
|
SYNCHRONOUS_COMMIT_REMOTE_FLUSH, /* wait for local and remote flush */
|
||||||
SYNCHRONOUS_COMMIT_REMOTE_APPLY /* wait for local flush and remote apply */
|
SYNCHRONOUS_COMMIT_REMOTE_APPLY /* wait for local and remote flush
|
||||||
|
and remote apply */
|
||||||
} SyncCommitLevel;
|
} SyncCommitLevel;
|
||||||
|
|
||||||
/* Define the default setting for synchronous_commit */
|
/* Define the default setting for synchronous_commit */
|
||||||
|
Loading…
Reference in New Issue
Block a user