Commit a7cc5237 authored by Michael Paquier's avatar Michael Paquier

Reorganize Notes section in documentation of pg_checksums

This commit reorders the paragraphs of the Notes section in order of
importance, and clarifies better the safe uses of pg_checksums for
replication setups.

Author: Fabien Coelho
Discussion: https://postgr.es/m/alpine.DEB.2.21.1903231404280.18811@lancre
parent c0a2ff47
...@@ -179,29 +179,27 @@ PostgreSQL documentation ...@@ -179,29 +179,27 @@ PostgreSQL documentation
<refsect1> <refsect1>
<title>Notes</title> <title>Notes</title>
<para> <para>
When disabling or enabling checksums in a replication setup of multiple Enabling checksums in a large cluster can potentially take a long time.
clusters, it is recommended to stop all the clusters before doing During this operation, the cluster or other programs that write to the
the switch to all the clusters consistently. When using a replication data directory must not be started or else data loss may occur.
setup with tools which perform direct copies of relation file blocks
(for example <xref linkend="app-pgrewind"/>), enabling or disabling
checksums can lead to page corruptions in the shape of incorrect
checksums if the operation is not done consistently across all nodes.
Destroying all the standbys in the setup first, enabling or disabling
checksums on the primary and finally recreating the standbys from
scratch is also safe.
</para> </para>
<para> <para>
If <application>pg_checksums</application> is aborted or killed in When using a replication setup with tools which perform direct copies
its operation while enabling or disabling checksums, the cluster of relation file blocks (for example <xref linkend="app-pgrewind"/>),
will have the same state with respect of checksums as before the enabling or disabling checksums can lead to page corruptions in the
operation and <application>pg_checksums</application> needs to be shape of incorrect checksums if the operation is not done consistently
restarted. across all nodes. When enabling or disabling checksums in a replication
setup, it is thus recommended to stop all the clusters before switching
them all consistently. Destroying all standbys, performing the operation
on the primary and finally recreating the standbys from scratch is also
safe.
</para> </para>
<para> <para>
When enabling checksums in a cluster, the operation can potentially If <application>pg_checksums</application> is aborted or killed while
take a long time if the data directory is large. During this operation, enabling or disabling checksums, the cluster will keep the same
the cluster or other programs that write to the data directory must not configuration for data checksums as before the operation attempted.
be started or else data loss may occur. <application>pg_checksums</application> can be restarted to
</para> attempt again the same operation.
</para>
</refsect1> </refsect1>
</refentry> </refentry>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment