1PG_REWIND(1)             PostgreSQL 12.2 Documentation            PG_REWIND(1)
2
3
4

NAME

6       pg_rewind - synchronize a PostgreSQL data directory with another data
7       directory that was forked from it
8

SYNOPSIS

10       pg_rewind [option...] {-D  | --target-pgdata} directory
11                 {--source-pgdata=directory | --source-server=connstr}
12

DESCRIPTION

14       pg_rewind is a tool for synchronizing a PostgreSQL cluster with another
15       copy of the same cluster, after the clusters' timelines have diverged.
16       A typical scenario is to bring an old master server back online after
17       failover as a standby that follows the new master.
18
19       The result is equivalent to replacing the target data directory with
20       the source one. Only changed blocks from relation files are copied; all
21       other files are copied in full, including configuration files. The
22       advantage of pg_rewind over taking a new base backup, or tools like
23       rsync, is that pg_rewind does not require reading through unchanged
24       blocks in the cluster. This makes it a lot faster when the database is
25       large and only a small fraction of blocks differ between the clusters.
26
27       pg_rewind examines the timeline histories of the source and target
28       clusters to determine the point where they diverged, and expects to
29       find WAL in the target cluster's pg_wal directory reaching all the way
30       back to the point of divergence. The point of divergence can be found
31       either on the target timeline, the source timeline, or their common
32       ancestor. In the typical failover scenario where the target cluster was
33       shut down soon after the divergence, this is not a problem, but if the
34       target cluster ran for a long time after the divergence, the old WAL
35       files might no longer be present. In that case, they can be manually
36       copied from the WAL archive to the pg_wal directory, or fetched on
37       startup by configuring primary_conninfo or restore_command. The use of
38       pg_rewind is not limited to failover, e.g. a standby server can be
39       promoted, run some write transactions, and then rewinded to become a
40       standby again.
41
42       When the target server is started for the first time after running
43       pg_rewind, it will go into recovery mode and replay all WAL generated
44       in the source server after the point of divergence. If some of the WAL
45       was no longer available in the source server when pg_rewind was run,
46       and therefore could not be copied by the pg_rewind session, it must be
47       made available when the target server is started. This can be done by
48       creating a recovery.signal file in the target data directory and
49       configuring suitable restore_command in postgresql.conf.
50
51       pg_rewind requires that the target server either has the wal_log_hints
52       option enabled in postgresql.conf or data checksums enabled when the
53       cluster was initialized with initdb. Neither of these are currently on
54       by default.  full_page_writes must also be set to on, but is enabled by
55       default.
56
57           Warning
58           If pg_rewind fails while processing, then the data folder of the
59           target is likely not in a state that can be recovered. In such a
60           case, taking a new fresh backup is recommended.
61
62           pg_rewind will fail immediately if it finds files it cannot write
63           directly to. This can happen for example when the source and the
64           target server use the same file mapping for read-only SSL keys and
65           certificates. If such files are present on the target server it is
66           recommended to remove them before running pg_rewind. After doing
67           the rewind, some of those files may have been copied from the
68           source, in which case it may be necessary to remove the data copied
69           and restore back the set of links used before the rewind.
70

OPTIONS

72       pg_rewind accepts the following command-line arguments:
73
74       -D directory
75       --target-pgdata=directory
76           This option specifies the target data directory that is
77           synchronized with the source. The target server must be shut down
78           cleanly before running pg_rewind
79
80       --source-pgdata=directory
81           Specifies the file system path to the data directory of the source
82           server to synchronize the target with. This option requires the
83           source server to be cleanly shut down.
84
85       --source-server=connstr
86           Specifies a libpq connection string to connect to the source
87           PostgreSQL server to synchronize the target with. The connection
88           must be a normal (non-replication) connection with a role having
89           sufficient permissions to execute the functions used by pg_rewind
90           on the source server (see Notes section for details) or a superuser
91           role. This option requires the source server to be running and not
92           in recovery mode.
93
94       -n
95       --dry-run
96           Do everything except actually modifying the target directory.
97
98       -N
99       --no-sync
100           By default, pg_rewind will wait for all files to be written safely
101           to disk. This option causes pg_rewind to return without waiting,
102           which is faster, but means that a subsequent operating system crash
103           can leave the synchronized data directory corrupt. Generally, this
104           option is useful for testing but should not be used when creating a
105           production installation.
106
107       -P
108       --progress
109           Enables progress reporting. Turning this on will deliver an
110           approximate progress report while copying data from the source
111           cluster.
112
113       --debug
114           Print verbose debugging output that is mostly useful for developers
115           debugging pg_rewind.
116
117       -V
118       --version
119           Display version information, then exit.
120
121       -?
122       --help
123           Show help, then exit.
124

ENVIRONMENT

126       When --source-server option is used, pg_rewind also uses the
127       environment variables supported by libpq (see Section 33.14).
128
129       The environment variable PG_COLOR specifies whether to use color in
130       diagnostics messages. Possible values are always, auto, never.
131

NOTES

133       When executing pg_rewind using an online cluster as source, a role
134       having sufficient permissions to execute the functions used by
135       pg_rewind on the source cluster can be used instead of a superuser.
136       Here is how to create such a role, named rewind_user here:
137
138           CREATE USER rewind_user LOGIN;
139           GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;
140           GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;
141           GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;
142           GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;
143
144       When executing pg_rewind using an online cluster as source which has
145       been recently promoted, it is necessary to execute a CHECKPOINT after
146       promotion so as its control file reflects up-to-date timeline
147       information, which is used by pg_rewind to check if the target cluster
148       can be rewound using the designated source cluster.
149
150   How It Works
151       The basic idea is to copy all file system-level changes from the source
152       cluster to the target cluster:
153
154        1. Scan the WAL log of the target cluster, starting from the last
155           checkpoint before the point where the source cluster's timeline
156           history forked off from the target cluster. For each WAL record,
157           record each data block that was touched. This yields a list of all
158           the data blocks that were changed in the target cluster, after the
159           source cluster forked off.
160
161        2. Copy all those changed blocks from the source cluster to the target
162           cluster, either using direct file system access (--source-pgdata)
163           or SQL (--source-server).
164
165        3. Copy all other files such as pg_xact and configuration files from
166           the source cluster to the target cluster (everything except the
167           relation files). Similarly to base backups, the contents of the
168           directories pg_dynshmem/, pg_notify/, pg_replslot/, pg_serial/,
169           pg_snapshots/, pg_stat_tmp/, and pg_subtrans/ are omitted from the
170           data copied from the source cluster. Any file or directory
171           beginning with pgsql_tmp is omitted, as well as are backup_label,
172           tablespace_map, pg_internal.init, postmaster.opts and
173           postmaster.pid.
174
175        4. Apply the WAL from the source cluster, starting from the checkpoint
176           created at failover. (Strictly speaking, pg_rewind doesn't apply
177           the WAL, it just creates a backup label file that makes PostgreSQL
178           start by replaying all WAL from that checkpoint forward.)
179
180
181
182PostgreSQL 12.2                      2020                         PG_REWIND(1)
Impressum