On Sat, Sep 14, 2019 at 07:00:54PM -0400, James Coleman wrote:
> Updated (plus some additional wordsmithing).
+ The rewind operation is not expected to result in a consistent data
+ directory state either internally to the node or with respect to the rest
+ of the cluster. Instead the resulting data directory will only be consistent
+ after WAL replay has completed to at least the LSN at which changed blocks
+ copied from the source were originally written on the source.
That's not necessarily true. pg_rewind enforces in the control file
of the target the minimum consistency LSN to be
pg_current_wal_insert_lsn() when using a live source or the last
checkpoint LSN for a stopped source, so while that sounds true from
the point of view of all the blocks copied, the control file may still
cause a complain that the target recovering has not reached its
consistent point even if all the blocks are already at a position
not-so-far from what has been registered in the control file.
+ the point at which the WAL timelines of the source and target diverged plus
+ the current state on the source of any blocks changed on the target after
+ that divergence. While only changed blocks from existing relation files are
And here we could mention that all the blocks copied from the source
are the ones which are found in the WAL records of the target until
the end of WAL of its timeline. Still, that's basically what is
mentioned in the first part of "How It Works", which explains things
better. I honestly don't really see that all this paragraph is an
improvement over the simplicity of the original when it comes to
understand the global idea of what pg_rewind does.
+ <para>
+ Because <application>pg_rewind</application> copies configuration files
+ entirely from the source, correcting recovery configuration options before
+ restarting the server is necessary if you intend to re-introduce the target
+ as a replica of the source. If you restart the server after the rewind
+ operation has finished but without configuring recovery, the target will
+ again diverge from the primary.
+ </para>
No objections regarding that part. Now it seems to me that we had
better apply that to the last part of "How it works" instead? I kind
of agree that the last paragraph could provide more details regarding
the risks of overwriting the wanted configuration. The existing docs
also mention that pg_rewind only creates a backup_label file to start
recovery, perhaps we could mention up to which point recovery happens
in this section? There is a bit more here than just "apply the WAL".
--
Michael