pg_rewind

Synchronize target directory with source directory

$ pg_rewind [[-D|--target-pgdata]] [path/to/target_data] --source-pgdata [path/to/source_data]

$ pg_rewind [[-D|--target-pgdata]] [path/to/target_data] --source-server [connstr]

$ pg_rewind [[-D|--target-pgdata]] [path/to/target_data] --source-pgdata [path/to/source_data] [[-n|--dry-run]]

$ pg_rewind [[-D|--target-pgdata]] [path/to/target_data] --source-pgdata [path/to/source_data] [[-P|--progress]]

$ pg_rewind [[-?|--help]]

pg_rewind [ OPTION... ] -D TARGET_DATA_DIRECTORY { --source-data-directory=SOURCE_DATA_DIRECTORY | --source-server=CONNSTR }

-D directory
    Specifies the target data directory that needs to be synchronized. This is the cluster that has diverged and will be modified to match the source. This option is mandatory.

--target-data-directory=directory
    Long form of the -D option, specifying the target data directory.

--source-data-directory=directory
    Specifies the path to the source data directory. This is used when the source cluster is available as a local file system directory (e.g., a stopped primary or another standby).

--source-server=CONNSTR
    Specifies a connection string for connecting to a running source PostgreSQL server. This allows pg_rewind to operate remotely, fetching necessary data and WAL files over a network connection.

-N
    Disables the forced synchronization of WAL files to disk using fsync(). This can speed up the operation but is unsafe for production use and should only be used for testing.

--no-sync
    Long form of the -N option.

-P
    Enables progress reporting, showing the current status and progress of the operation.

--progress
    Long form of the -P option.

-v
    Enables verbose output, providing more detailed messages about the operation's steps.

--verbose
    Long form of the -v option.

-V
    Prints the pg_rewind version and exits.

--version
    Long form of the -V option.

--help
    Shows help about pg_rewind command line arguments and exits.

The pg_rewind utility is designed to quickly synchronize a PostgreSQL cluster that has diverged from another copy of the same cluster. This scenario typically arises after a failover event where a standby server is promoted to become the new primary, and the original primary server, now outdated, needs to be brought back online, usually as a new standby for the promoted server.

Instead of performing a full base backup (which can be time-consuming and resource-intensive for large databases), pg_rewind intelligently identifies the point of divergence between the two clusters. It then copies only the changed data blocks and necessary Write-Ahead Log (WAL) files from the source cluster to the target cluster, effectively 'rewinding' the target to a state compatible with the source's timeline. This makes the target cluster ready to start as a new standby server, or even potentially as a new primary if needed, significantly reducing recovery time and network bandwidth usage.

• The target server must be cleanly shut down before running pg_rewind; it cannot be crash-recovered.


• The source server (either the running instance or the data directory) must have wal_log_hints enabled in its postgresql.conf.


• full_page_writes must be on in the source configuration (which is the default).


• The target data directory must not contain any symlinks pointing outside of the data directory itself.


• pg_rewind cannot be used to rewind a server that has already been rewound from the same source without an intermediate full base backup or a new timeline diverging from the source.


• The utility rewrites files directly in the target data directory, so ensure you have proper backups before use.

For pg_rewind to function correctly, several conditions must be met:

• The target cluster must be shut down cleanly, not in a crash-recovered state.


• The source cluster must have wal_log_hints = on in its postgresql.conf. This enables the tracking of page-level changes needed by pg_rewind.


• The source's timeline history must encompass or be ahead of the target's timeline at the point of divergence.


• Sufficient disk space must be available on the target system for the copied files.

pg_rewind operates by identifying the common ancestor checkpoint between the target and source clusters. It then performs the following steps:

• It scans the data directories of both the source and target to find all data blocks that have changed since the last common checkpoint.


• It copies the 'rewound' blocks (those that are different on the target compared to the source and needed to be reverted or updated) from the source to the target.


• It copies all necessary WAL segments from the source that are required to bring the target up to the current state of the source's timeline. This includes WAL files generated after the common ancestor.


• After completion, the target data directory is in a state where it can be started as a standby of the source cluster.

pg_rewind was introduced in PostgreSQL 9.3. It was developed to significantly improve the recovery process for failover scenarios. Before its introduction, if a primary server failed and a standby was promoted, the former primary could only be brought back online as a new standby by taking a full new base backup from the new primary. pg_rewind revolutionized this by providing a much faster and more efficient way to reconcile the divergent histories, saving considerable time and bandwidth, especially for large databases.

pg_basebackup(1), pg_ctl(1), psql(1), rsync(1)