begriffs open source - ai-pg/blob - full-docs/txt/app-pgrewind.txt

   1
   2 pg_rewind
   3
   4    pg_rewind — synchronize a PostgreSQL data directory with another data
   5    directory that was forked from it
   6
   7 Synopsis
   8
   9    pg_rewind [option...] { -D | --target-pgdata } directory {
  10    --source-pgdata=directory | --source-server=connstr }
  11
  12 Description
  13
  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 primary server back online after
  17    failover as a standby that follows the new primary.
  18
  19    After a successful rewind, the state of the target data directory is
  20    analogous to a base backup of the source data directory. Unlike taking
  21    a new base backup or using a tool like rsync, pg_rewind does not
  22    require comparing or copying unchanged relation blocks in the cluster.
  23    Only changed blocks from existing relation files are copied; all other
  24    files, including new relation files, configuration files, and WAL
  25    segments, are copied in full. As such the rewind operation is
  26    significantly faster than other approaches when the database is large
  27    and only a small fraction of blocks differ between the clusters.
  28
  29    pg_rewind examines the timeline histories of the source and target
  30    clusters to determine the point where they diverged, and expects to
  31    find WAL in the target cluster's pg_wal directory reaching all the way
  32    back to the point of divergence. The point of divergence can be found
  33    either on the target timeline, the source timeline, or their common
  34    ancestor. In the typical failover scenario where the target cluster was
  35    shut down soon after the divergence, this is not a problem, but if the
  36    target cluster ran for a long time after the divergence, its old WAL
  37    files might no longer be present. In this case, you can manually copy
  38    them from the WAL archive to the pg_wal directory, or run pg_rewind
  39    with the -c option to automatically retrieve them from the WAL archive.
  40    The use of pg_rewind is not limited to failover, e.g., a standby server
  41    can be promoted, run some write transactions, and then rewound to
  42    become a standby again.
  43
  44    After running pg_rewind, WAL replay needs to complete for the data
  45    directory to be in a consistent state. When the target server is
  46    started again it will enter archive recovery and replay all WAL
  47    generated in the source server from the last checkpoint before the
  48    point of divergence. If some of the WAL was no longer available in the
  49    source server when pg_rewind was run, and therefore could not be copied
  50    by the pg_rewind session, it must be made available when the target
  51    server is started. This can be done by creating a recovery.signal file
  52    in the target data directory and by configuring a suitable
  53    restore_command in postgresql.conf.
  54
  55    pg_rewind requires that the target server either has the wal_log_hints
  56    option enabled in postgresql.conf or data checksums enabled when the
  57    cluster was initialized with initdb. Neither of these are currently on
  58    by default. full_page_writes must also be set to on, but is enabled by
  59    default.
  60
  61 Warning: Failures While Rewinding
  62
  63    If pg_rewind fails while processing, then the data folder of the target
  64    is likely not in a state that can be recovered. In such a case, taking
  65    a new fresh backup is recommended.
  66
  67    As pg_rewind copies configuration files entirely from the source, it
  68    may be required to correct the configuration used for recovery before
  69    restarting the target server, especially if the target is reintroduced
  70    as a standby of the source. If you restart the server after the rewind
  71    operation has finished but without configuring recovery, the target may
  72    again diverge from the primary.
  73
  74    pg_rewind will fail immediately if it finds files it cannot write
  75    directly to. This can happen for example when the source and the target
  76    server use the same file mapping for read-only SSL keys and
  77    certificates. If such files are present on the target server it is
  78    recommended to remove them before running pg_rewind. After doing the
  79    rewind, some of those files may have been copied from the source, in
  80    which case it may be necessary to remove the data copied and restore
  81    back the set of links used before the rewind.
  82
  83 Options
  84
  85    pg_rewind accepts the following command-line arguments:
  86
  87    -D directory
  88           --target-pgdata=directory
  89           This option specifies the target data directory that is
  90           synchronized with the source. The target server must be shut
  91           down cleanly before running pg_rewind
  92
  93    --source-pgdata=directory
  94           Specifies the file system path to the data directory of the
  95           source server to synchronize the target with. This option
  96           requires the source server to be cleanly shut down.
  97
  98    --source-server=connstr
  99           Specifies a libpq connection string to connect to the source
 100           PostgreSQL server to synchronize the target with. The connection
 101           must be a normal (non-replication) connection with a role having
 102           sufficient permissions to execute the functions used by
 103           pg_rewind on the source server (see Notes section for details)
 104           or a superuser role. This option requires the source server to
 105           be running and accepting connections.
 106
 107    -R
 108           --write-recovery-conf
 109           Create standby.signal and append connection settings to
 110           postgresql.auto.conf in the output directory. The dbname will be
 111           recorded only if the dbname was specified explicitly in the
 112           connection string or environment variable. --source-server is
 113           mandatory with this option.
 114
 115    -n
 116           --dry-run
 117           Do everything except actually modifying the target directory.
 118
 119    -N
 120           --no-sync
 121           By default, pg_rewind will wait for all files to be written
 122           safely to disk. This option causes pg_rewind to return without
 123           waiting, which is faster, but means that a subsequent operating
 124           system crash can leave the data directory corrupt. Generally,
 125           this option is useful for testing but should not be used on a
 126           production installation.
 127
 128    -P
 129           --progress
 130           Enables progress reporting. Turning this on will deliver an
 131           approximate progress report while copying data from the source
 132           cluster.
 133
 134    -c
 135           --restore-target-wal
 136           Use restore_command defined in the target cluster configuration
 137           to retrieve WAL files from the WAL archive if these files are no
 138           longer available in the pg_wal directory.
 139
 140    --config-file=filename
 141           Use the specified main server configuration file for the target
 142           cluster. This affects pg_rewind when it uses internally the
 143           postgres command for the rewind operation on this cluster (when
 144           retrieving restore_command with the option
 145           -c/--restore-target-wal and when forcing a completion of crash
 146           recovery).
 147
 148    --debug
 149           Print verbose debugging output that is mostly useful for
 150           developers debugging pg_rewind.
 151
 152    --no-ensure-shutdown
 153           pg_rewind requires that the target server is cleanly shut down
 154           before rewinding. By default, if the target server is not shut
 155           down cleanly, pg_rewind starts the target server in single-user
 156           mode to complete crash recovery first, and stops it. By passing
 157           this option, pg_rewind skips this and errors out immediately if
 158           the server is not cleanly shut down. Users are expected to
 159           handle the situation themselves in that case.
 160
 161    --sync-method=method
 162           When set to fsync, which is the default, pg_rewind will
 163           recursively open and synchronize all files in the data
 164           directory. The search for files will follow symbolic links for
 165           the WAL directory and each configured tablespace.
 166
 167           On Linux, syncfs may be used instead to ask the operating system
 168           to synchronize the whole file systems that contain the data
 169           directory, the WAL files, and each tablespace. See
 170           recovery_init_sync_method for information about the caveats to
 171           be aware of when using syncfs.
 172
 173           This option has no effect when --no-sync is used.
 174
 175    -V
 176           --version
 177           Display version information, then exit.
 178
 179    -?
 180           --help
 181           Show help, then exit.
 182
 183 Environment
 184
 185    When --source-server option is used, pg_rewind also uses the
 186    environment variables supported by libpq (see Section 32.15).
 187
 188    The environment variable PG_COLOR specifies whether to use color in
 189    diagnostic messages. Possible values are always, auto and never.
 190
 191 Notes
 192
 193    When executing pg_rewind using an online cluster as source, a role
 194    having sufficient permissions to execute the functions used by
 195    pg_rewind on the source cluster can be used instead of a superuser.
 196    Here is how to create such a role, named rewind_user here:
 197 CREATE USER rewind_user LOGIN;
 198 GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind
 199 _user;
 200 GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;
 201 GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;
 202 GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, b
 203 oolean) TO rewind_user;
 204
 205 How It Works
 206
 207    The basic idea is to copy all file system-level changes from the source
 208    cluster to the target cluster:
 209     1. Scan the WAL log of the target cluster, starting from the last
 210        checkpoint before the point where the source cluster's timeline
 211        history forked off from the target cluster. For each WAL record,
 212        record each data block that was touched. This yields a list of all
 213        the data blocks that were changed in the target cluster, after the
 214        source cluster forked off. If some of the WAL files are no longer
 215        available, try re-running pg_rewind with the -c option to search
 216        for the missing files in the WAL archive.
 217     2. Copy all those changed blocks from the source cluster to the target
 218        cluster, either using direct file system access (--source-pgdata)
 219        or SQL (--source-server). Relation files are now in a state
 220        equivalent to the moment of the last completed checkpoint prior to
 221        the point at which the WAL timelines of the source and target
 222        diverged plus the current state on the source of any blocks changed
 223        on the target after that divergence.
 224     3. Copy all other files, including new relation files, WAL segments,
 225        pg_xact, and configuration files from the source cluster to the
 226        target cluster. Similarly to base backups, the contents of the
 227        directories pg_dynshmem/, pg_notify/, pg_replslot/, pg_serial/,
 228        pg_snapshots/, pg_stat_tmp/, and pg_subtrans/ are omitted from the
 229        data copied from the source cluster. The files backup_label,
 230        tablespace_map, pg_internal.init, postmaster.opts, postmaster.pid
 231        and .DS_Store as well as any file or directory beginning with
 232        pgsql_tmp, are omitted.
 233     4. Create a backup_label file to begin WAL replay at the checkpoint
 234        created at failover and configure the pg_control file with a
 235        minimum consistency LSN defined as the result of
 236        pg_current_wal_insert_lsn() when rewinding from a live source or
 237        the last checkpoint LSN when rewinding from a stopped source.
 238     5. When starting the target, PostgreSQL replays all the required WAL,
 239        resulting in a data directory in a consistent state.