diff options
Diffstat (limited to 'doc/src/sgml/ref/pg_rewind.sgml')
| -rw-r--r-- | doc/src/sgml/ref/pg_rewind.sgml | 418 |
1 files changed, 418 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml new file mode 100644 index 0000000..69d6924 --- /dev/null +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -0,0 +1,418 @@ +<!-- +doc/src/sgml/ref/pg_rewind.sgml +PostgreSQL documentation +--> + +<refentry id="app-pgrewind"> + <indexterm zone="app-pgrewind"> + <primary>pg_rewind</primary> + </indexterm> + + <refmeta> + <refentrytitle><application>pg_rewind</application></refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>pg_rewind</refname> + <refpurpose>synchronize a <productname>PostgreSQL</productname> data directory with another data directory that was forked from it</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>pg_rewind</command> + <arg rep="repeat"><replaceable>option</replaceable></arg> + <group choice="plain"> + <group choice="req"> + <arg choice="plain"><option>-D</option></arg> + <arg choice="plain"><option>--target-pgdata</option></arg> + </group> + <replaceable> directory</replaceable> + <group choice="req"> + <arg choice="plain"><option>--source-pgdata=<replaceable>directory</replaceable></option></arg> + <arg choice="plain"><option>--source-server=<replaceable>connstr</replaceable></option></arg> + </group> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <application>pg_rewind</application> is a tool for synchronizing a PostgreSQL cluster + with another copy of the same cluster, after the clusters' timelines have + diverged. A typical scenario is to bring an old primary server back online + after failover as a standby that follows the new primary. + </para> + + <para> + After a successful rewind, the state of the target data directory is + analogous to a base backup of the source data directory. Unlike taking + a new base backup or using a tool like <application>rsync</application>, + <application>pg_rewind</application> does not require comparing or copying + unchanged relation blocks in the cluster. Only changed blocks from existing + relation files are copied; all other files, including new relation files, + configuration files, and WAL segments, are copied in full. As such the + rewind operation is significantly faster than other approaches when the + database is large and only a small fraction of blocks differ between the + clusters. + </para> + + <para> + <application>pg_rewind</application> examines the timeline histories of the source + and target clusters to determine the point where they diverged, and + expects to find WAL in the target cluster's <filename>pg_wal</filename> directory + reaching all the way back to the point of divergence. The point of divergence + can be found either on the target timeline, the source timeline, or their common + ancestor. In the typical failover scenario where the target cluster was + shut down soon after the divergence, this is not a problem, but if the + target cluster ran for a long time after the divergence, its old WAL + files might no longer be present. In this case, you can manually copy them + from the WAL archive to the <filename>pg_wal</filename> directory, or run + <application>pg_rewind</application> with the <literal>-c</literal> option to + automatically retrieve them from the WAL archive. The use of + <application>pg_rewind</application> is not limited to failover, e.g., a standby + server can be promoted, run some write transactions, and then rewound + to become a standby again. + </para> + + <para> + After running <application>pg_rewind</application>, WAL replay needs to + complete for the data directory to be in a consistent state. When the + target server is started again it will enter archive recovery and replay + all WAL generated in the source server from the last checkpoint before + the point of divergence. If some of the WAL was no longer available in the + source server when <application>pg_rewind</application> was run, and + therefore could not be copied by the <application>pg_rewind</application> + session, it must be made available when the target server is started. + This can be done by creating a <filename>recovery.signal</filename> file + in the target data directory and by configuring a suitable + <xref linkend="guc-restore-command"/> in + <filename>postgresql.conf</filename>. + </para> + + <para> + <application>pg_rewind</application> requires that the target server either has + the <xref linkend="guc-wal-log-hints"/> option enabled + in <filename>postgresql.conf</filename> or data checksums enabled when + the cluster was initialized with <application>initdb</application>. Neither of these + are currently on by default. <xref linkend="guc-full-page-writes"/> + must also be set to <literal>on</literal>, but is enabled by default. + </para> + + <warning> + <para> + If <application>pg_rewind</application> fails while processing, then + the data folder of the target is likely not in a state that can be + recovered. In such a case, taking a new fresh backup is recommended. + </para> + + <para> + As <application>pg_rewind</application> copies configuration files + entirely from the source, it may be required to correct the configuration + used for recovery before restarting the target server, especially if + the target is reintroduced as a standby of the source. If you restart + the server after the rewind operation has finished but without configuring + recovery, the target may again diverge from the primary. + </para> + + <para> + <application>pg_rewind</application> will fail immediately if it finds + files it cannot write directly to. This can happen for example when + the source and the target server use the same file mapping for read-only + SSL keys and certificates. If such files are present on the target server + it is recommended to remove them before running + <application>pg_rewind</application>. After doing the rewind, some of + those files may have been copied from the source, in which case it may + be necessary to remove the data copied and restore back the set of links + used before the rewind. + </para> + </warning> + </refsect1> + + <refsect1> + <title>Options</title> + + <para> + <application>pg_rewind</application> accepts the following command-line + arguments: + + <variablelist> + <varlistentry> + <term><option>-D <replaceable class="parameter">directory</replaceable></option></term> + <term><option>--target-pgdata=<replaceable class="parameter">directory</replaceable></option></term> + <listitem> + <para> + This option specifies the target data directory that is synchronized + with the source. The target server must be shut down cleanly before + running <application>pg_rewind</application> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--source-pgdata=<replaceable class="parameter">directory</replaceable></option></term> + <listitem> + <para> + Specifies the file system path to the data directory of the source + server to synchronize the target with. This option requires the + source server to be cleanly shut down. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--source-server=<replaceable class="parameter">connstr</replaceable></option></term> + <listitem> + <para> + Specifies a libpq connection string to connect to the source + <productname>PostgreSQL</productname> server to synchronize the target + with. The connection must be a normal (non-replication) connection + with a role having sufficient permissions to execute the functions + used by <application>pg_rewind</application> on the source server + (see Notes section for details) or a superuser role. This option + requires the source server to be running and accepting connections. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-R</option></term> + <term><option>--write-recovery-conf</option></term> + <listitem> + <para> + Create <filename>standby.signal</filename> and append connection + settings to <filename>postgresql.auto.conf</filename> in the output + directory. <literal>--source-server</literal> is mandatory with + this option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <term><option>--dry-run</option></term> + <listitem> + <para> + Do everything except actually modifying the target directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-N</option></term> + <term><option>--no-sync</option></term> + <listitem> + <para> + By default, <command>pg_rewind</command> will wait for all files + to be written safely to disk. This option causes + <command>pg_rewind</command> to return without waiting, which is + faster, but means that a subsequent operating system crash can leave + the data directory corrupt. Generally, this option is useful for + testing but should not be used on a production + installation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <term><option>--progress</option></term> + <listitem> + <para> + Enables progress reporting. Turning this on will deliver an approximate + progress report while copying data from the source cluster. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + <term><option>--restore-target-wal</option></term> + <listitem> + <para> + Use <varname>restore_command</varname> defined in the target cluster + configuration to retrieve WAL files from the WAL archive if these + files are no longer available in the <filename>pg_wal</filename> + directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--config-file=<replaceable class="parameter">filename</replaceable></option></term> + <listitem> + <para> + Use the specified main server configuration file for the target + cluster. This affects <application>pg_rewind</application> when + it uses internally the <application>postgres</application> command + for the rewind operation on this cluster (when retrieving + <varname>restore_command</varname> with the option + <option>-c/--restore-target-wal</option> and when forcing a + completion of crash recovery). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--debug</option></term> + <listitem> + <para> + Print verbose debugging output that is mostly useful for developers + debugging <application>pg_rewind</application>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-ensure-shutdown</option></term> + <listitem> + <para> + <application>pg_rewind</application> requires that the target server + is cleanly shut down before rewinding. By default, if the target server + is not shut down cleanly, <application>pg_rewind</application> starts + the target server in single-user mode to complete crash recovery first, + and stops it. + By passing this option, <application>pg_rewind</application> skips + this and errors out immediately if the server is not cleanly shut + down. Users are expected to handle the situation themselves in that + case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-V</option></term> + <term><option>--version</option></term> + <listitem><para>Display version information, then exit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-?</option></term> + <term><option>--help</option></term> + <listitem><para>Show help, then exit.</para></listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <para> + When <option>--source-server</option> option is used, + <application>pg_rewind</application> also uses the environment variables + supported by <application>libpq</application> (see <xref linkend="libpq-envars"/>). + </para> + + <para> + The environment variable <envar>PG_COLOR</envar> specifies whether to use + color in diagnostic messages. Possible values are + <literal>always</literal>, <literal>auto</literal> and + <literal>never</literal>. + </para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + When executing <application>pg_rewind</application> using an online + cluster as source, a role having sufficient permissions to execute the + functions used by <application>pg_rewind</application> on the source + cluster can be used instead of a superuser. Here is how to create such + a role, named <literal>rewind_user</literal> here: +<programlisting> +CREATE USER rewind_user LOGIN; +GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user; +GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user; +GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user; +GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user; +</programlisting> + </para> + + <para> + When executing <application>pg_rewind</application> using an online + cluster as source which has been recently promoted, it is necessary + to execute a <command>CHECKPOINT</command> after promotion such that its + control file reflects up-to-date timeline information, which is used by + <application>pg_rewind</application> to check if the target cluster + can be rewound using the designated source cluster. + </para> + + <refsect2> + <title>How It Works</title> + + <para> + The basic idea is to copy all file system-level changes from the source + cluster to the target cluster: + </para> + + <procedure> + <step> + <para> + Scan the WAL log of the target cluster, starting from the last + checkpoint before the point where the source cluster's timeline + history forked off from the target cluster. For each WAL record, + record each data block that was touched. This yields a list of all + the data blocks that were changed in the target cluster, after the + source cluster forked off. If some of the WAL files are no longer + available, try re-running <application>pg_rewind</application> with + the <option>-c</option> option to search for the missing files in + the WAL archive. + </para> + </step> + <step> + <para> + Copy all those changed blocks from the source cluster to + the target cluster, either using direct file system access + (<option>--source-pgdata</option>) or SQL (<option>--source-server</option>). + Relation files are now in a state equivalent to the moment of the last + completed checkpoint prior to 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. + </para> + </step> + <step> + <para> + Copy all other files, including new relation files, WAL segments, + <filename>pg_xact</filename>, and configuration files from the source + cluster to the target cluster. Similarly to base backups, the contents + of the directories <filename>pg_dynshmem/</filename>, + <filename>pg_notify/</filename>, <filename>pg_replslot/</filename>, + <filename>pg_serial/</filename>, <filename>pg_snapshots/</filename>, + <filename>pg_stat_tmp/</filename>, and <filename>pg_subtrans/</filename> + are omitted from the data copied from the source cluster. The files + <filename>backup_label</filename>, + <filename>tablespace_map</filename>, + <filename>pg_internal.init</filename>, + <filename>postmaster.opts</filename>, and + <filename>postmaster.pid</filename>, as well as any file or directory + beginning with <filename>pgsql_tmp</filename>, are omitted. + </para> + </step> + <step> + <para> + Create a <filename>backup_label</filename> file to begin WAL replay at + the checkpoint created at failover and configure the + <filename>pg_control</filename> file with a minimum consistency LSN + defined as the result of <literal>pg_current_wal_insert_lsn()</literal> + when rewinding from a live source or the last checkpoint LSN when + rewinding from a stopped source. + </para> + </step> + <step> + <para> + When starting the target, <productname>PostgreSQL</productname> replays + all the required WAL, resulting in a data directory in a consistent + state. + </para> + </step> + </procedure> + </refsect2> + </refsect1> + +</refentry> |