{"Entry":{"collection":"tool","key":"pg-rewind","name":"pg_rewind","aliases":["pg_rewind"],"metadata":{"aliases":["pg_rewind"],"category":"Server applications","content_hash":"972142a26f177cc984d85aa8249d432ea7952b400317e35aa322a96423eb951e","imported_at":"2026-09-30T00:40:34.42316+08:00","name":"pg_rewind","name_zh":"","slug":"pg-rewind","summary":"pg_rewind — synchronize a PostgreSQL data directory with another data directory that was forked from it"}},"Definition":{"Collection":"tool","Key":"pg-rewind","SourceDatabase":"center","Version":"18","SourceTable":"command_tool","SourceKey":"pg-rewind","SourceRevision":"ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8","Facts":{"comparison_data":{"environment":[],"options":[{"description":"This option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running pg_rewind","names":["-D directory","--target-pgdata= directory"],"signature":"-D directory --target-pgdata= directory"},{"description":"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.","names":["--source-pgdata= directory"],"signature":"--source-pgdata= directory"},{"description":"Specifies a libpq connection string to connect to the source PostgreSQL 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 pg_rewind 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.","names":["--source-server= connstr"],"signature":"--source-server= connstr"},{"description":"Create standby.signal and append connection settings to postgresql.auto.conf in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or environment variable . --source-server is mandatory with this option.","names":["-R","--write-recovery-conf"],"signature":"-R --write-recovery-conf"},{"description":"Do everything except actually modifying the target directory.","names":["-n","--dry-run"],"signature":"-n --dry-run"},{"description":"By default, pg_rewind will wait for all files to be written safely to disk. This option causes pg_rewind 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.","names":["-N","--no-sync"],"signature":"-N --no-sync"},{"description":"Enables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster.","names":["-P","--progress"],"signature":"-P --progress"},{"description":"Use restore_command defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the pg_wal directory.","names":["-c","--restore-target-wal"],"signature":"-c --restore-target-wal"},{"description":"Use the specified main server configuration file for the target cluster. This affects pg_rewind when it uses internally the postgres command for the rewind operation on this cluster (when retrieving restore_command with the option -c/--restore-target-wal and when forcing a completion of crash recovery).","names":["--config-file= filename"],"signature":"--config-file= filename"},{"description":"Print verbose debugging output that is mostly useful for developers debugging pg_rewind .","names":["--debug"],"signature":"--debug"},{"description":"pg_rewind requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, pg_rewind starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, pg_rewind 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.","names":["--no-ensure-shutdown"],"signature":"--no-ensure-shutdown"},{"description":"When set to fsync , which is the default, pg_rewind will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace. On Linux, syncfs may be used instead to ask the operating system to synchronize the whole file systems that contain the data directory, the WAL files, and each tablespace. See recovery_init_sync_method for information about the caveats to be aware of when using syncfs . This option has no effect when --no-sync is used.","names":["--sync-method= method"],"signature":"--sync-method= method"},{"description":"Display version information, then exit.","names":["-V","--version"],"signature":"-V --version"},{"description":"Show help, then exit.","names":["-?","--help"],"signature":"-? --help"}],"synopsis":["pg_rewind [ option ...] { -D | --target-pgdata } directory { --source-pgdata= directory | --source-server= connstr }"]},"comparison_hash":"65184284b9b782562c5b09cffbc1b933ebbf723a803dbe3a7320b5b328307823","description":["pg_rewind — synchronize a PostgreSQL data directory with another data directory that was forked from it"],"environment":[],"facts":[{"label":"Documented executable","value":"pg_rewind"},{"label":"Executable version","value":"18.6"},{"label":"Reference inventory","value":"Server applications"},{"label":"Option definition groups","value":"14"}],"manual_html":"\u003cdiv\u003e\u003cdiv class=\"refentry\" id=\"APP-PGREWIND\"\u003e\n\u003cdiv class=\"titlepage\"\u003e\u003c/div\u003e\n\u003cdiv class=\"refnamediv\"\u003e\n\u003ch2\u003e\u003cspan class=\"refentrytitle\"\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e\u003c/span\u003e\u003c/h2\u003e\n\u003cp\u003epg_rewind — synchronize a \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e data directory with another data directory that was forked from it\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsynopsisdiv\"\u003e\n\u003ch2\u003eSynopsis\u003c/h2\u003e\n\u003cdiv class=\"cmdsynopsis\"\u003e\n\u003cp id=\"id-1.9.5.10.4.1\"\u003e\u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e [\u003cem class=\"replaceable\"\u003e\u003ccode\u003eoption\u003c/code\u003e\u003c/em\u003e...] { \u003ccode class=\"option\"\u003e-D\u003c/code\u003e | \u003ccode class=\"option\"\u003e--target-pgdata\u003c/code\u003e } \u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e { \u003ccode class=\"option\"\u003e--source-pgdata=\u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e | \u003ccode class=\"option\"\u003e--source-server=\u003cem class=\"replaceable\"\u003e\u003ccode\u003econnstr\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e }\u003c/p\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.5\"\u003e\n\u003ch2\u003eDescription\u003c/h2\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAfter 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 \u003cspan class=\"application\"\u003ersync\u003c/span\u003e, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e 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 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e directory, or run \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e with the \u003ccode class=\"literal\"\u003e-c\u003c/code\u003e option to automatically retrieve them from the WAL archive. The use of \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAfter running \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e, 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e was run, and therefore could not be copied by the \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e session, it must be made available when the target server is started. This can be done by creating a \u003ccode class=\"filename\"\u003erecovery.signal\u003c/code\u003e file in the target data directory and by configuring a suitable \u003ca class=\"xref\" href=\"/docs/18/runtime-config-wal.html#GUC-RESTORE-COMMAND\"\u003erestore_command\u003c/a\u003e in \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e.\u003c/p\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e requires that the target server either has the \u003ca class=\"xref\" href=\"/docs/18/runtime-config-wal.html#GUC-WAL-LOG-HINTS\"\u003ewal_log_hints\u003c/a\u003e option enabled in \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e or data checksums enabled when the cluster was initialized with \u003cspan class=\"application\"\u003einitdb\u003c/span\u003e (the default). \u003ca class=\"xref\" href=\"/docs/18/runtime-config-wal.html#GUC-FULL-PAGE-WRITES\"\u003efull_page_writes\u003c/a\u003e must also be set to \u003ccode class=\"literal\"\u003eon\u003c/code\u003e, but is enabled by default.\u003c/p\u003e\n\u003cdiv class=\"warning\"\u003e\n\u003ch3 class=\"title\"\u003eWarning: Failures While Rewinding\u003c/h3\u003e\n\u003cp\u003eIf \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAs \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e. 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.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.6\"\u003e\n\u003ch2\u003eOptions\u003c/h2\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e accepts the following command-line arguments:\u003c/p\u003e\n\u003cdiv class=\"variablelist\"\u003e\n\u003cdl class=\"variablelist\"\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-D \u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--target-pgdata=\u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThis option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--source-pgdata=\u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eSpecifies 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--source-server=\u003cem class=\"replaceable\"\u003e\u003ccode\u003econnstr\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eSpecifies a libpq connection string to connect to the source \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-R\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--write-recovery-conf\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eCreate \u003ccode class=\"filename\"\u003estandby.signal\u003c/code\u003e and append connection settings to \u003ccode class=\"filename\"\u003epostgresql.auto.conf\u003c/code\u003e in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or \u003ca class=\"link\" href=\"/docs/18/libpq-envars.html\" title=\"32.15. Environment Variables\"\u003eenvironment variable\u003c/a\u003e. \u003ccode class=\"literal\"\u003e--source-server\u003c/code\u003e is mandatory with this option.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-n\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--dry-run\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eDo everything except actually modifying the target directory.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-N\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--no-sync\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eBy default, \u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e will wait for all files to be written safely to disk. This option causes \u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-P\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--progress\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eEnables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-c\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--restore-target-wal\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eUse \u003ccode class=\"varname\"\u003erestore_command\u003c/code\u003e defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e directory.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--config-file=\u003cem class=\"replaceable\"\u003e\u003ccode\u003efilename\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eUse the specified main server configuration file for the target cluster. This affects \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e when it uses internally the \u003cspan class=\"application\"\u003epostgres\u003c/span\u003e command for the rewind operation on this cluster (when retrieving \u003ccode class=\"varname\"\u003erestore_command\u003c/code\u003e with the option \u003ccode class=\"option\"\u003e-c/--restore-target-wal\u003c/code\u003e and when forcing a completion of crash recovery).\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--debug\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003ePrint verbose debugging output that is mostly useful for developers debugging \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--no-ensure-shutdown\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--sync-method=\u003cem class=\"replaceable\"\u003e\u003ccode\u003emethod\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eWhen set to \u003ccode class=\"literal\"\u003efsync\u003c/code\u003e, which is the default, \u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace.\u003c/p\u003e\n\u003cp\u003eOn Linux, \u003ccode class=\"literal\"\u003esyncfs\u003c/code\u003e may be used instead to ask the operating system to synchronize the whole file systems that contain the data directory, the WAL files, and each tablespace. See \u003ca class=\"xref\" href=\"/docs/18/runtime-config-error-handling.html#GUC-RECOVERY-INIT-SYNC-METHOD\"\u003erecovery_init_sync_method\u003c/a\u003e for information about the caveats to be aware of when using \u003ccode class=\"literal\"\u003esyncfs\u003c/code\u003e.\u003c/p\u003e\n\u003cp\u003eThis option has no effect when \u003ccode class=\"option\"\u003e--no-sync\u003c/code\u003e is used.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-V\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--version\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eDisplay version information, then exit.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-?\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--help\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eShow help, then exit.\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.7\"\u003e\n\u003ch2\u003eEnvironment\u003c/h2\u003e\n\u003cp\u003eWhen \u003ccode class=\"option\"\u003e--source-server\u003c/code\u003e option is used, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e also uses the environment variables supported by \u003cspan class=\"application\"\u003elibpq\u003c/span\u003e (see \u003ca class=\"xref\" href=\"/docs/18/libpq-envars.html\" title=\"32.15. Environment Variables\"\u003eSection 32.15\u003c/a\u003e).\u003c/p\u003e\n\u003cp\u003eThe environment variable \u003ccode class=\"envar\"\u003ePG_COLOR\u003c/code\u003e specifies whether to use color in diagnostic messages. Possible values are \u003ccode class=\"literal\"\u003ealways\u003c/code\u003e, \u003ccode class=\"literal\"\u003eauto\u003c/code\u003e and \u003ccode class=\"literal\"\u003enever\u003c/code\u003e.\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.8\"\u003e\n\u003ch2\u003eNotes\u003c/h2\u003e\n\u003cp\u003eWhen executing \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e using an online cluster as source, a role having sufficient permissions to execute the functions used by \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e on the source cluster can be used instead of a superuser. Here is how to create such a role, named \u003ccode class=\"literal\"\u003erewind_user\u003c/code\u003e here:\u003c/p\u003e\n\u003cpre class=\"programlisting\"\u003eCREATE USER rewind_user LOGIN;\nGRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;\n\u003c/pre\u003e\n\u003cdiv class=\"refsect2\" id=\"id-1.9.5.10.8.3\"\u003e\n\u003ch3\u003eHow It Works\u003c/h3\u003e\n\u003cp\u003eThe basic idea is to copy all file system-level changes from the source cluster to the target cluster:\u003c/p\u003e\n\u003cdiv class=\"procedure\"\u003e\n\u003col class=\"procedure\"\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eScan 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e with the \u003ccode class=\"option\"\u003e-c\u003c/code\u003e option to search for the missing files in the WAL archive.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eCopy all those changed blocks from the source cluster to the target cluster, either using direct file system access (\u003ccode class=\"option\"\u003e--source-pgdata\u003c/code\u003e) or SQL (\u003ccode class=\"option\"\u003e--source-server\u003c/code\u003e). 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.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eCopy all other files, including new relation files, WAL segments, \u003ccode class=\"filename\"\u003epg_xact\u003c/code\u003e, and configuration files from the source cluster to the target cluster. Similarly to base backups, the contents of the directories \u003ccode class=\"filename\"\u003epg_dynshmem/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_notify/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_replslot/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_serial/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_snapshots/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_stat_tmp/\u003c/code\u003e, and \u003ccode class=\"filename\"\u003epg_subtrans/\u003c/code\u003e are omitted from the data copied from the source cluster. The files \u003ccode class=\"filename\"\u003ebackup_label\u003c/code\u003e, \u003ccode class=\"filename\"\u003etablespace_map\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_internal.init\u003c/code\u003e, \u003ccode class=\"filename\"\u003epostmaster.opts\u003c/code\u003e, \u003ccode class=\"filename\"\u003epostmaster.pid\u003c/code\u003e and \u003ccode class=\"filename\"\u003e.DS_Store\u003c/code\u003e as well as any file or directory beginning with \u003ccode class=\"filename\"\u003epgsql_tmp\u003c/code\u003e, are omitted.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eCreate a \u003ccode class=\"filename\"\u003ebackup_label\u003c/code\u003e file to begin WAL replay at the checkpoint created at failover and configure the \u003ccode class=\"filename\"\u003epg_control\u003c/code\u003e file with a minimum consistency LSN defined as the result of \u003ccode class=\"literal\"\u003epg_current_wal_insert_lsn()\u003c/code\u003e when rewinding from a live source or the last checkpoint LSN when rewinding from a stopped source.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eWhen starting the target, \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e replays all the required WAL, resulting in a data directory in a consistent state.\u003c/p\u003e\n\u003c/li\u003e\n\u003c/ol\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\u003c/div\u003e","manual_path":"app-pgrewind.html","options":[{"description":"This option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running pg_rewind","names":["-D directory","--target-pgdata= directory"],"signature":"-D directory --target-pgdata= directory","source_url":"/docs/18/app-pgrewind.html","summary":"This option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running pg_rewind"},{"description":"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.","names":["--source-pgdata= directory"],"signature":"--source-pgdata= directory","source_url":"/docs/18/app-pgrewind.html","summary":"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."},{"description":"Specifies a libpq connection string to connect to the source PostgreSQL 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 pg_rewind 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.","names":["--source-server= connstr"],"signature":"--source-server= connstr","source_url":"/docs/18/app-pgrewind.html","summary":"Specifies a libpq connection string to connect to the source PostgreSQL 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 pg_rewind 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."},{"description":"Create standby.signal and append connection settings to postgresql.auto.conf in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or environment variable . --source-server is mandatory with this option.","names":["-R","--write-recovery-conf"],"signature":"-R --write-recovery-conf","source_url":"/docs/18/app-pgrewind.html","summary":"Create standby.signal and append connection settings to postgresql.auto.conf in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or environment variable . --source-server is mandatory with this option."},{"description":"Do everything except actually modifying the target directory.","names":["-n","--dry-run"],"signature":"-n --dry-run","source_url":"/docs/18/app-pgrewind.html","summary":"Do everything except actually modifying the target directory."},{"description":"By default, pg_rewind will wait for all files to be written safely to disk. This option causes pg_rewind 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.","names":["-N","--no-sync"],"signature":"-N --no-sync","source_url":"/docs/18/app-pgrewind.html","summary":"By default, pg_rewind will wait for all files to be written safely to disk. This option causes pg_rewind 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."},{"description":"Enables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster.","names":["-P","--progress"],"signature":"-P --progress","source_url":"/docs/18/app-pgrewind.html","summary":"Enables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster."},{"description":"Use restore_command defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the pg_wal directory.","names":["-c","--restore-target-wal"],"signature":"-c --restore-target-wal","source_url":"/docs/18/app-pgrewind.html","summary":"Use restore_command defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the pg_wal directory."},{"description":"Use the specified main server configuration file for the target cluster. This affects pg_rewind when it uses internally the postgres command for the rewind operation on this cluster (when retrieving restore_command with the option -c/--restore-target-wal and when forcing a completion of crash recovery).","names":["--config-file= filename"],"signature":"--config-file= filename","source_url":"/docs/18/app-pgrewind.html","summary":"Use the specified main server configuration file for the target cluster. This affects pg_rewind when it uses internally the postgres command for the rewind operation on this cluster (when retrieving restore_command with the option -c/--restore-target-wal and when forcing a completion of crash recovery)."},{"description":"Print verbose debugging output that is mostly useful for developers debugging pg_rewind .","names":["--debug"],"signature":"--debug","source_url":"/docs/18/app-pgrewind.html","summary":"Print verbose debugging output that is mostly useful for developers debugging pg_rewind ."},{"description":"pg_rewind requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, pg_rewind starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, pg_rewind 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.","names":["--no-ensure-shutdown"],"signature":"--no-ensure-shutdown","source_url":"/docs/18/app-pgrewind.html","summary":"pg_rewind requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, pg_rewind starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, pg_rewind 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."},{"description":"When set to fsync , which is the default, pg_rewind will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace. On Linux, syncfs may be used instead to ask the operating system to synchronize the whole file systems that contain the data directory, the WAL files, and each tablespace. See recovery_init_sync_method for information about the caveats to be aware of when using syncfs . This option has no effect when --no-sync is used.","names":["--sync-method= method"],"signature":"--sync-method= method","source_url":"/docs/18/app-pgrewind.html","summary":"When set to fsync , which is the default, pg_rewind will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace."},{"description":"Display version information, then exit.","names":["-V","--version"],"signature":"-V --version","source_url":"/docs/18/app-pgrewind.html","summary":"Display version information, then exit."},{"description":"Show help, then exit.","names":["-?","--help"],"signature":"-? --help","source_url":"/docs/18/app-pgrewind.html","summary":"Show help, then exit."}],"related":[],"release":{"channel":"stable","evidence_kind":"English manual and source declarations","label":"18.6","major":"18","manifest":{"index":"index.html","major":"18","pages":1148,"pdf":{"A4":{"built_at":"2026-09-26","bytes":15865106,"pages":3154,"sha256":"19512c405da53f9f7fcf0abba359223aa65f021be025bf3411381918f92e3190","url":"/files/documentation/pdf/18/postgresql-18-A4.pdf"},"US":{"built_at":"2026-09-26","bytes":15748059,"pages":3328,"sha256":"facbe6c229e598b872d3d98bef53308f46e06746006fa4590de9a7de9dd46319","url":"/files/documentation/pdf/18/postgresql-18-US.pdf"}},"release":"18.6","source_mode":"en SGML built with pinned official archive","source_sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","source_url":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2","svg_assets":3,"tree":"18"},"ref":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2","revision":"ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8","source_sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f"},"sections":[],"signature":"pg_rewind [ option ...] { -D | --target-pgdata } directory { --source-pgdata= directory | --source-server= connstr }","sources":[{"anchor":"","file":"app-pgrewind.html","label":"18.6 English manual · app-pgrewind.html","sha256":"2d8a13348838dfc44e3733f7e269f3fb35643d705686198ab09cc5bada9a1330","url":"/docs/18/app-pgrewind.html"},{"anchor":"","file":"reference-server.html","label":"Server applications inventory","sha256":"e9f8bbcc8e3641fadd1d20991e8aad6b532155b786ba5a1b7b364ec4f1a5bef3","url":"/docs/18/reference-server.html"}],"synopsis":["pg_rewind [ option ...] { -D | --target-pgdata } directory { --source-pgdata= directory | --source-server= connstr }"],"tables":[{"columns":[{"key":"signature","label":"Option and arguments"},{"key":"summary","label":"Description"}],"key":"options","rows":[{"signature":{"text":"-D directory --target-pgdata= directory","url":"/docs/18/app-pgrewind.html"},"summary":"This option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running pg_rewind"},{"signature":{"text":"--source-pgdata= directory","url":"/docs/18/app-pgrewind.html"},"summary":"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."},{"signature":{"text":"--source-server= connstr","url":"/docs/18/app-pgrewind.html"},"summary":"Specifies a libpq connection string to connect to the source PostgreSQL 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 pg_rewind 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."},{"signature":{"text":"-R --write-recovery-conf","url":"/docs/18/app-pgrewind.html"},"summary":"Create standby.signal and append connection settings to postgresql.auto.conf in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or environment variable . --source-server is mandatory with this option."},{"signature":{"text":"-n --dry-run","url":"/docs/18/app-pgrewind.html"},"summary":"Do everything except actually modifying the target directory."},{"signature":{"text":"-N --no-sync","url":"/docs/18/app-pgrewind.html"},"summary":"By default, pg_rewind will wait for all files to be written safely to disk. This option causes pg_rewind 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."},{"signature":{"text":"-P --progress","url":"/docs/18/app-pgrewind.html"},"summary":"Enables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster."},{"signature":{"text":"-c --restore-target-wal","url":"/docs/18/app-pgrewind.html"},"summary":"Use restore_command defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the pg_wal directory."},{"signature":{"text":"--config-file= filename","url":"/docs/18/app-pgrewind.html"},"summary":"Use the specified main server configuration file for the target cluster. This affects pg_rewind when it uses internally the postgres command for the rewind operation on this cluster (when retrieving restore_command with the option -c/--restore-target-wal and when forcing a completion of crash recovery)."},{"signature":{"text":"--debug","url":"/docs/18/app-pgrewind.html"},"summary":"Print verbose debugging output that is mostly useful for developers debugging pg_rewind ."},{"signature":{"text":"--no-ensure-shutdown","url":"/docs/18/app-pgrewind.html"},"summary":"pg_rewind requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, pg_rewind starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, pg_rewind 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."},{"signature":{"text":"--sync-method= method","url":"/docs/18/app-pgrewind.html"},"summary":"When set to fsync , which is the default, pg_rewind will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace."},{"signature":{"text":"-V --version","url":"/docs/18/app-pgrewind.html"},"summary":"Display version information, then exit."},{"signature":{"text":"-? --help","url":"/docs/18/app-pgrewind.html"},"summary":"Show help, then exit."}],"title":"Documented options"}]},"ManualEvidence":{"manual_path":"app-pgrewind.html","release":{"channel":"stable","evidence_kind":"English manual and source declarations","label":"18.6","major":"18","manifest":{"index":"index.html","major":"18","pages":1148,"pdf":{"A4":{"built_at":"2026-09-26","bytes":15865106,"pages":3154,"sha256":"19512c405da53f9f7fcf0abba359223aa65f021be025bf3411381918f92e3190","url":"/files/documentation/pdf/18/postgresql-18-A4.pdf"},"US":{"built_at":"2026-09-26","bytes":15748059,"pages":3328,"sha256":"facbe6c229e598b872d3d98bef53308f46e06746006fa4590de9a7de9dd46319","url":"/files/documentation/pdf/18/postgresql-18-US.pdf"}},"release":"18.6","source_mode":"en SGML built with pinned official archive","source_sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f","source_url":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2","svg_assets":3,"tree":"18"},"ref":"https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2","revision":"ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8","source_sha256":"555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f"},"sources":[{"anchor":"","file":"app-pgrewind.html","label":"18.6 English manual · app-pgrewind.html","sha256":"2d8a13348838dfc44e3733f7e269f3fb35643d705686198ab09cc5bada9a1330","url":"/docs/18/app-pgrewind.html"},{"anchor":"","file":"reference-server.html","label":"Server applications inventory","sha256":"e9f8bbcc8e3641fadd1d20991e8aad6b532155b786ba5a1b7b364ec4f1a5bef3","url":"/docs/18/reference-server.html"}]},"MeasuredEvidence":{}},"Text":{"Collection":"tool","Key":"pg-rewind","SourceDatabase":"center","Version":"18","Locale":"en","Title":"pg_rewind","Summary":"pg_rewind — synchronize a PostgreSQL data directory with another data directory that was forked from it","BodyHTML":"\u003cdiv\u003e\u003cdiv id=\"APP-PGREWIND\"\u003e\n\u003cdiv\u003e\u003c/div\u003e\n\u003cdiv\u003e\n\u003ch2\u003e\u003cspan\u003e\u003cspan\u003epg_rewind\u003c/span\u003e\u003c/span\u003e\u003c/h2\u003e\n\u003cp\u003epg_rewind — synchronize a \u003cspan\u003ePostgreSQL\u003c/span\u003e data directory with another data directory that was forked from it\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv\u003e\n\u003ch2\u003eSynopsis\u003c/h2\u003e\n\u003cdiv\u003e\n\u003cp id=\"id-1.9.5.10.4.1\"\u003e\u003ccode\u003epg_rewind\u003c/code\u003e [\u003cem\u003e\u003ccode\u003eoption\u003c/code\u003e\u003c/em\u003e...] { \u003ccode\u003e-D\u003c/code\u003e | \u003ccode\u003e--target-pgdata\u003c/code\u003e } \u003cem\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e { \u003ccode\u003e--source-pgdata=\u003cem\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e | \u003ccode\u003e--source-server=\u003cem\u003e\u003ccode\u003econnstr\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e }\u003c/p\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv id=\"id-1.9.5.10.5\"\u003e\n\u003ch2\u003eDescription\u003c/h2\u003e\n\u003cp\u003e\u003cspan\u003epg_rewind\u003c/span\u003e is a tool for synchronizing a PostgreSQL cluster with another copy of the same cluster, after the clusters\u0026#39; 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.\u003c/p\u003e\n\u003cp\u003eAfter 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 \u003cspan\u003ersync\u003c/span\u003e, \u003cspan\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003e\u003cspan\u003epg_rewind\u003c/span\u003e 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\u0026#39;s \u003ccode\u003epg_wal\u003c/code\u003e 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 \u003ccode\u003epg_wal\u003c/code\u003e directory, or run \u003cspan\u003epg_rewind\u003c/span\u003e with the \u003ccode\u003e-c\u003c/code\u003e option to automatically retrieve them from the WAL archive. The use of \u003cspan\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAfter running \u003cspan\u003epg_rewind\u003c/span\u003e, 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 \u003cspan\u003epg_rewind\u003c/span\u003e was run, and therefore could not be copied by the \u003cspan\u003epg_rewind\u003c/span\u003e session, it must be made available when the target server is started. This can be done by creating a \u003ccode\u003erecovery.signal\u003c/code\u003e file in the target data directory and by configuring a suitable \u003ca href=\"/docs/18/runtime-config-wal.html#GUC-RESTORE-COMMAND\" rel=\"nofollow\"\u003erestore_command\u003c/a\u003e in \u003ccode\u003epostgresql.conf\u003c/code\u003e.\u003c/p\u003e\n\u003cp\u003e\u003cspan\u003epg_rewind\u003c/span\u003e requires that the target server either has the \u003ca href=\"/docs/18/runtime-config-wal.html#GUC-WAL-LOG-HINTS\" rel=\"nofollow\"\u003ewal_log_hints\u003c/a\u003e option enabled in \u003ccode\u003epostgresql.conf\u003c/code\u003e or data checksums enabled when the cluster was initialized with \u003cspan\u003einitdb\u003c/span\u003e (the default). \u003ca href=\"/docs/18/runtime-config-wal.html#GUC-FULL-PAGE-WRITES\" rel=\"nofollow\"\u003efull_page_writes\u003c/a\u003e must also be set to \u003ccode\u003eon\u003c/code\u003e, but is enabled by default.\u003c/p\u003e\n\u003cdiv\u003e\n\u003ch3\u003eWarning: Failures While Rewinding\u003c/h3\u003e\n\u003cp\u003eIf \u003cspan\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAs \u003cspan\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003e\u003cspan\u003epg_rewind\u003c/span\u003e 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 \u003cspan\u003epg_rewind\u003c/span\u003e. 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.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv id=\"id-1.9.5.10.6\"\u003e\n\u003ch2\u003eOptions\u003c/h2\u003e\n\u003cp\u003e\u003cspan\u003epg_rewind\u003c/span\u003e accepts the following command-line arguments:\u003c/p\u003e\n\u003cdiv\u003e\n\u003cdl\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-D \u003cem\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--target-pgdata=\u003cem\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThis option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running \u003cspan\u003epg_rewind\u003c/span\u003e\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e--source-pgdata=\u003cem\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eSpecifies 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e--source-server=\u003cem\u003e\u003ccode\u003econnstr\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eSpecifies a libpq connection string to connect to the source \u003cspan\u003ePostgreSQL\u003c/span\u003e 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 \u003cspan\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-R\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--write-recovery-conf\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eCreate \u003ccode\u003estandby.signal\u003c/code\u003e and append connection settings to \u003ccode\u003epostgresql.auto.conf\u003c/code\u003e in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or \u003ca href=\"/docs/18/libpq-envars.html\" rel=\"nofollow\"\u003eenvironment variable\u003c/a\u003e. \u003ccode\u003e--source-server\u003c/code\u003e is mandatory with this option.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-n\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--dry-run\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eDo everything except actually modifying the target directory.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-N\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--no-sync\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eBy default, \u003ccode\u003epg_rewind\u003c/code\u003e will wait for all files to be written safely to disk. This option causes \u003ccode\u003epg_rewind\u003c/code\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-P\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--progress\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eEnables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-c\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--restore-target-wal\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eUse \u003ccode\u003erestore_command\u003c/code\u003e defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the \u003ccode\u003epg_wal\u003c/code\u003e directory.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e--config-file=\u003cem\u003e\u003ccode\u003efilename\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eUse the specified main server configuration file for the target cluster. This affects \u003cspan\u003epg_rewind\u003c/span\u003e when it uses internally the \u003cspan\u003epostgres\u003c/span\u003e command for the rewind operation on this cluster (when retrieving \u003ccode\u003erestore_command\u003c/code\u003e with the option \u003ccode\u003e-c/--restore-target-wal\u003c/code\u003e and when forcing a completion of crash recovery).\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e--debug\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003ePrint verbose debugging output that is mostly useful for developers debugging \u003cspan\u003epg_rewind\u003c/span\u003e.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e--no-ensure-shutdown\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003e\u003cspan\u003epg_rewind\u003c/span\u003e requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, \u003cspan\u003epg_rewind\u003c/span\u003e starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, \u003cspan\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e--sync-method=\u003cem\u003e\u003ccode\u003emethod\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eWhen set to \u003ccode\u003efsync\u003c/code\u003e, which is the default, \u003ccode\u003epg_rewind\u003c/code\u003e will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace.\u003c/p\u003e\n\u003cp\u003eOn Linux, \u003ccode\u003esyncfs\u003c/code\u003e may be used instead to ask the operating system to synchronize the whole file systems that contain the data directory, the WAL files, and each tablespace. See \u003ca href=\"/docs/18/runtime-config-error-handling.html#GUC-RECOVERY-INIT-SYNC-METHOD\" rel=\"nofollow\"\u003erecovery_init_sync_method\u003c/a\u003e for information about the caveats to be aware of when using \u003ccode\u003esyncfs\u003c/code\u003e.\u003c/p\u003e\n\u003cp\u003eThis option has no effect when \u003ccode\u003e--no-sync\u003c/code\u003e is used.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-V\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--version\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eDisplay version information, then exit.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan\u003e\u003ccode\u003e-?\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan\u003e\u003ccode\u003e--help\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eShow help, then exit.\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv id=\"id-1.9.5.10.7\"\u003e\n\u003ch2\u003eEnvironment\u003c/h2\u003e\n\u003cp\u003eWhen \u003ccode\u003e--source-server\u003c/code\u003e option is used, \u003cspan\u003epg_rewind\u003c/span\u003e also uses the environment variables supported by \u003cspan\u003elibpq\u003c/span\u003e (see \u003ca href=\"/docs/18/libpq-envars.html\" rel=\"nofollow\"\u003eSection 32.15\u003c/a\u003e).\u003c/p\u003e\n\u003cp\u003eThe environment variable \u003ccode\u003ePG_COLOR\u003c/code\u003e specifies whether to use color in diagnostic messages. Possible values are \u003ccode\u003ealways\u003c/code\u003e, \u003ccode\u003eauto\u003c/code\u003e and \u003ccode\u003enever\u003c/code\u003e.\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv id=\"id-1.9.5.10.8\"\u003e\n\u003ch2\u003eNotes\u003c/h2\u003e\n\u003cp\u003eWhen executing \u003cspan\u003epg_rewind\u003c/span\u003e using an online cluster as source, a role having sufficient permissions to execute the functions used by \u003cspan\u003epg_rewind\u003c/span\u003e on the source cluster can be used instead of a superuser. Here is how to create such a role, named \u003ccode\u003erewind_user\u003c/code\u003e here:\u003c/p\u003e\n\u003cpre\u003eCREATE USER rewind_user LOGIN;\nGRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;\n\u003c/pre\u003e\n\u003cdiv id=\"id-1.9.5.10.8.3\"\u003e\n\u003ch3\u003eHow It Works\u003c/h3\u003e\n\u003cp\u003eThe basic idea is to copy all file system-level changes from the source cluster to the target cluster:\u003c/p\u003e\n\u003cdiv\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cp\u003eScan the WAL log of the target cluster, starting from the last checkpoint before the point where the source cluster\u0026#39;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 \u003cspan\u003epg_rewind\u003c/span\u003e with the \u003ccode\u003e-c\u003c/code\u003e option to search for the missing files in the WAL archive.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli\u003e\n\u003cp\u003eCopy all those changed blocks from the source cluster to the target cluster, either using direct file system access (\u003ccode\u003e--source-pgdata\u003c/code\u003e) or SQL (\u003ccode\u003e--source-server\u003c/code\u003e). 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.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli\u003e\n\u003cp\u003eCopy all other files, including new relation files, WAL segments, \u003ccode\u003epg_xact\u003c/code\u003e, and configuration files from the source cluster to the target cluster. Similarly to base backups, the contents of the directories \u003ccode\u003epg_dynshmem/\u003c/code\u003e, \u003ccode\u003epg_notify/\u003c/code\u003e, \u003ccode\u003epg_replslot/\u003c/code\u003e, \u003ccode\u003epg_serial/\u003c/code\u003e, \u003ccode\u003epg_snapshots/\u003c/code\u003e, \u003ccode\u003epg_stat_tmp/\u003c/code\u003e, and \u003ccode\u003epg_subtrans/\u003c/code\u003e are omitted from the data copied from the source cluster. The files \u003ccode\u003ebackup_label\u003c/code\u003e, \u003ccode\u003etablespace_map\u003c/code\u003e, \u003ccode\u003epg_internal.init\u003c/code\u003e, \u003ccode\u003epostmaster.opts\u003c/code\u003e, \u003ccode\u003epostmaster.pid\u003c/code\u003e and \u003ccode\u003e.DS_Store\u003c/code\u003e as well as any file or directory beginning with \u003ccode\u003epgsql_tmp\u003c/code\u003e, are omitted.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli\u003e\n\u003cp\u003eCreate a \u003ccode\u003ebackup_label\u003c/code\u003e file to begin WAL replay at the checkpoint created at failover and configure the \u003ccode\u003epg_control\u003c/code\u003e file with a minimum consistency LSN defined as the result of \u003ccode\u003epg_current_wal_insert_lsn()\u003c/code\u003e when rewinding from a live source or the last checkpoint LSN when rewinding from a stopped source.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli\u003e\n\u003cp\u003eWhen starting the target, \u003cspan\u003ePostgreSQL\u003c/span\u003e replays all the required WAL, resulting in a data directory in a consistent state.\u003c/p\u003e\n\u003c/li\u003e\n\u003c/ol\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\u003c/div\u003e","SourceRevision":"ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8","ContentHash":"651750a2932f193f2ed5d74a7e847fe61fb06089baece6022a661d1de2e23e31","Payload":{"description":["pg_rewind — synchronize a PostgreSQL data directory with another data directory that was forked from it"],"manual_html":"\u003cdiv\u003e\u003cdiv class=\"refentry\" id=\"APP-PGREWIND\"\u003e\n\u003cdiv class=\"titlepage\"\u003e\u003c/div\u003e\n\u003cdiv class=\"refnamediv\"\u003e\n\u003ch2\u003e\u003cspan class=\"refentrytitle\"\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e\u003c/span\u003e\u003c/h2\u003e\n\u003cp\u003epg_rewind — synchronize a \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e data directory with another data directory that was forked from it\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsynopsisdiv\"\u003e\n\u003ch2\u003eSynopsis\u003c/h2\u003e\n\u003cdiv class=\"cmdsynopsis\"\u003e\n\u003cp id=\"id-1.9.5.10.4.1\"\u003e\u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e [\u003cem class=\"replaceable\"\u003e\u003ccode\u003eoption\u003c/code\u003e\u003c/em\u003e...] { \u003ccode class=\"option\"\u003e-D\u003c/code\u003e | \u003ccode class=\"option\"\u003e--target-pgdata\u003c/code\u003e } \u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e { \u003ccode class=\"option\"\u003e--source-pgdata=\u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e | \u003ccode class=\"option\"\u003e--source-server=\u003cem class=\"replaceable\"\u003e\u003ccode\u003econnstr\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e }\u003c/p\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.5\"\u003e\n\u003ch2\u003eDescription\u003c/h2\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAfter 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 \u003cspan class=\"application\"\u003ersync\u003c/span\u003e, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e 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 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e directory, or run \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e with the \u003ccode class=\"literal\"\u003e-c\u003c/code\u003e option to automatically retrieve them from the WAL archive. The use of \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAfter running \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e, 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e was run, and therefore could not be copied by the \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e session, it must be made available when the target server is started. This can be done by creating a \u003ccode class=\"filename\"\u003erecovery.signal\u003c/code\u003e file in the target data directory and by configuring a suitable \u003ca class=\"xref\" href=\"/docs/18/runtime-config-wal.html#GUC-RESTORE-COMMAND\"\u003erestore_command\u003c/a\u003e in \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e.\u003c/p\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e requires that the target server either has the \u003ca class=\"xref\" href=\"/docs/18/runtime-config-wal.html#GUC-WAL-LOG-HINTS\"\u003ewal_log_hints\u003c/a\u003e option enabled in \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e or data checksums enabled when the cluster was initialized with \u003cspan class=\"application\"\u003einitdb\u003c/span\u003e (the default). \u003ca class=\"xref\" href=\"/docs/18/runtime-config-wal.html#GUC-FULL-PAGE-WRITES\"\u003efull_page_writes\u003c/a\u003e must also be set to \u003ccode class=\"literal\"\u003eon\u003c/code\u003e, but is enabled by default.\u003c/p\u003e\n\u003cdiv class=\"warning\"\u003e\n\u003ch3 class=\"title\"\u003eWarning: Failures While Rewinding\u003c/h3\u003e\n\u003cp\u003eIf \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003eAs \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e. 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.\u003c/p\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.6\"\u003e\n\u003ch2\u003eOptions\u003c/h2\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e accepts the following command-line arguments:\u003c/p\u003e\n\u003cdiv class=\"variablelist\"\u003e\n\u003cdl class=\"variablelist\"\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-D \u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--target-pgdata=\u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eThis option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--source-pgdata=\u003cem class=\"replaceable\"\u003e\u003ccode\u003edirectory\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eSpecifies 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--source-server=\u003cem class=\"replaceable\"\u003e\u003ccode\u003econnstr\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eSpecifies a libpq connection string to connect to the source \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-R\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--write-recovery-conf\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eCreate \u003ccode class=\"filename\"\u003estandby.signal\u003c/code\u003e and append connection settings to \u003ccode class=\"filename\"\u003epostgresql.auto.conf\u003c/code\u003e in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or \u003ca class=\"link\" href=\"/docs/18/libpq-envars.html\" title=\"32.15. Environment Variables\"\u003eenvironment variable\u003c/a\u003e. \u003ccode class=\"literal\"\u003e--source-server\u003c/code\u003e is mandatory with this option.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-n\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--dry-run\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eDo everything except actually modifying the target directory.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-N\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--no-sync\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eBy default, \u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e will wait for all files to be written safely to disk. This option causes \u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-P\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--progress\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eEnables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-c\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--restore-target-wal\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eUse \u003ccode class=\"varname\"\u003erestore_command\u003c/code\u003e defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e directory.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--config-file=\u003cem class=\"replaceable\"\u003e\u003ccode\u003efilename\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eUse the specified main server configuration file for the target cluster. This affects \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e when it uses internally the \u003cspan class=\"application\"\u003epostgres\u003c/span\u003e command for the rewind operation on this cluster (when retrieving \u003ccode class=\"varname\"\u003erestore_command\u003c/code\u003e with the option \u003ccode class=\"option\"\u003e-c/--restore-target-wal\u003c/code\u003e and when forcing a completion of crash recovery).\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--debug\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003ePrint verbose debugging output that is mostly useful for developers debugging \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--no-ensure-shutdown\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003e\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 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.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--sync-method=\u003cem class=\"replaceable\"\u003e\u003ccode\u003emethod\u003c/code\u003e\u003c/em\u003e\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eWhen set to \u003ccode class=\"literal\"\u003efsync\u003c/code\u003e, which is the default, \u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace.\u003c/p\u003e\n\u003cp\u003eOn Linux, \u003ccode class=\"literal\"\u003esyncfs\u003c/code\u003e may be used instead to ask the operating system to synchronize the whole file systems that contain the data directory, the WAL files, and each tablespace. See \u003ca class=\"xref\" href=\"/docs/18/runtime-config-error-handling.html#GUC-RECOVERY-INIT-SYNC-METHOD\"\u003erecovery_init_sync_method\u003c/a\u003e for information about the caveats to be aware of when using \u003ccode class=\"literal\"\u003esyncfs\u003c/code\u003e.\u003c/p\u003e\n\u003cp\u003eThis option has no effect when \u003ccode class=\"option\"\u003e--no-sync\u003c/code\u003e is used.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-V\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--version\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eDisplay version information, then exit.\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e-?\u003c/code\u003e\u003cbr\u003e\u003c/span\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--help\u003c/code\u003e\u003c/span\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\u003cp\u003eShow help, then exit.\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.7\"\u003e\n\u003ch2\u003eEnvironment\u003c/h2\u003e\n\u003cp\u003eWhen \u003ccode class=\"option\"\u003e--source-server\u003c/code\u003e option is used, \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e also uses the environment variables supported by \u003cspan class=\"application\"\u003elibpq\u003c/span\u003e (see \u003ca class=\"xref\" href=\"/docs/18/libpq-envars.html\" title=\"32.15. Environment Variables\"\u003eSection 32.15\u003c/a\u003e).\u003c/p\u003e\n\u003cp\u003eThe environment variable \u003ccode class=\"envar\"\u003ePG_COLOR\u003c/code\u003e specifies whether to use color in diagnostic messages. Possible values are \u003ccode class=\"literal\"\u003ealways\u003c/code\u003e, \u003ccode class=\"literal\"\u003eauto\u003c/code\u003e and \u003ccode class=\"literal\"\u003enever\u003c/code\u003e.\u003c/p\u003e\n\u003c/div\u003e\n\u003cdiv class=\"refsect1\" id=\"id-1.9.5.10.8\"\u003e\n\u003ch2\u003eNotes\u003c/h2\u003e\n\u003cp\u003eWhen executing \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e using an online cluster as source, a role having sufficient permissions to execute the functions used by \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e on the source cluster can be used instead of a superuser. Here is how to create such a role, named \u003ccode class=\"literal\"\u003erewind_user\u003c/code\u003e here:\u003c/p\u003e\n\u003cpre class=\"programlisting\"\u003eCREATE USER rewind_user LOGIN;\nGRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;\nGRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;\n\u003c/pre\u003e\n\u003cdiv class=\"refsect2\" id=\"id-1.9.5.10.8.3\"\u003e\n\u003ch3\u003eHow It Works\u003c/h3\u003e\n\u003cp\u003eThe basic idea is to copy all file system-level changes from the source cluster to the target cluster:\u003c/p\u003e\n\u003cdiv class=\"procedure\"\u003e\n\u003col class=\"procedure\"\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eScan 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 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e with the \u003ccode class=\"option\"\u003e-c\u003c/code\u003e option to search for the missing files in the WAL archive.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eCopy all those changed blocks from the source cluster to the target cluster, either using direct file system access (\u003ccode class=\"option\"\u003e--source-pgdata\u003c/code\u003e) or SQL (\u003ccode class=\"option\"\u003e--source-server\u003c/code\u003e). 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.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eCopy all other files, including new relation files, WAL segments, \u003ccode class=\"filename\"\u003epg_xact\u003c/code\u003e, and configuration files from the source cluster to the target cluster. Similarly to base backups, the contents of the directories \u003ccode class=\"filename\"\u003epg_dynshmem/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_notify/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_replslot/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_serial/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_snapshots/\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_stat_tmp/\u003c/code\u003e, and \u003ccode class=\"filename\"\u003epg_subtrans/\u003c/code\u003e are omitted from the data copied from the source cluster. The files \u003ccode class=\"filename\"\u003ebackup_label\u003c/code\u003e, \u003ccode class=\"filename\"\u003etablespace_map\u003c/code\u003e, \u003ccode class=\"filename\"\u003epg_internal.init\u003c/code\u003e, \u003ccode class=\"filename\"\u003epostmaster.opts\u003c/code\u003e, \u003ccode class=\"filename\"\u003epostmaster.pid\u003c/code\u003e and \u003ccode class=\"filename\"\u003e.DS_Store\u003c/code\u003e as well as any file or directory beginning with \u003ccode class=\"filename\"\u003epgsql_tmp\u003c/code\u003e, are omitted.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eCreate a \u003ccode class=\"filename\"\u003ebackup_label\u003c/code\u003e file to begin WAL replay at the checkpoint created at failover and configure the \u003ccode class=\"filename\"\u003epg_control\u003c/code\u003e file with a minimum consistency LSN defined as the result of \u003ccode class=\"literal\"\u003epg_current_wal_insert_lsn()\u003c/code\u003e when rewinding from a live source or the last checkpoint LSN when rewinding from a stopped source.\u003c/p\u003e\n\u003c/li\u003e\n\u003cli class=\"step\"\u003e\n\u003cp\u003eWhen starting the target, \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e replays all the required WAL, resulting in a data directory in a consistent state.\u003c/p\u003e\n\u003c/li\u003e\n\u003c/ol\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/div\u003e\u003c/div\u003e","related":[],"sections":[],"tables":[{"columns":[{"key":"signature","label":"Option and arguments"},{"key":"summary","label":"Description"}],"key":"options","rows":[{"signature":{"text":"-D directory --target-pgdata= directory","url":"/docs/18/app-pgrewind.html"},"summary":"This option specifies the target data directory that is synchronized with the source. The target server must be shut down cleanly before running pg_rewind"},{"signature":{"text":"--source-pgdata= directory","url":"/docs/18/app-pgrewind.html"},"summary":"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."},{"signature":{"text":"--source-server= connstr","url":"/docs/18/app-pgrewind.html"},"summary":"Specifies a libpq connection string to connect to the source PostgreSQL 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 pg_rewind 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."},{"signature":{"text":"-R --write-recovery-conf","url":"/docs/18/app-pgrewind.html"},"summary":"Create standby.signal and append connection settings to postgresql.auto.conf in the output directory. The dbname will be recorded only if the dbname was specified explicitly in the connection string or environment variable . --source-server is mandatory with this option."},{"signature":{"text":"-n --dry-run","url":"/docs/18/app-pgrewind.html"},"summary":"Do everything except actually modifying the target directory."},{"signature":{"text":"-N --no-sync","url":"/docs/18/app-pgrewind.html"},"summary":"By default, pg_rewind will wait for all files to be written safely to disk. This option causes pg_rewind 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."},{"signature":{"text":"-P --progress","url":"/docs/18/app-pgrewind.html"},"summary":"Enables progress reporting. Turning this on will deliver an approximate progress report while copying data from the source cluster."},{"signature":{"text":"-c --restore-target-wal","url":"/docs/18/app-pgrewind.html"},"summary":"Use restore_command defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the pg_wal directory."},{"signature":{"text":"--config-file= filename","url":"/docs/18/app-pgrewind.html"},"summary":"Use the specified main server configuration file for the target cluster. This affects pg_rewind when it uses internally the postgres command for the rewind operation on this cluster (when retrieving restore_command with the option -c/--restore-target-wal and when forcing a completion of crash recovery)."},{"signature":{"text":"--debug","url":"/docs/18/app-pgrewind.html"},"summary":"Print verbose debugging output that is mostly useful for developers debugging pg_rewind ."},{"signature":{"text":"--no-ensure-shutdown","url":"/docs/18/app-pgrewind.html"},"summary":"pg_rewind requires that the target server is cleanly shut down before rewinding. By default, if the target server is not shut down cleanly, pg_rewind starts the target server in single-user mode to complete crash recovery first, and stops it. By passing this option, pg_rewind 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."},{"signature":{"text":"--sync-method= method","url":"/docs/18/app-pgrewind.html"},"summary":"When set to fsync , which is the default, pg_rewind will recursively open and synchronize all files in the data directory. The search for files will follow symbolic links for the WAL directory and each configured tablespace."},{"signature":{"text":"-V --version","url":"/docs/18/app-pgrewind.html"},"summary":"Display version information, then exit."},{"signature":{"text":"-? --help","url":"/docs/18/app-pgrewind.html"},"summary":"Show help, then exit."}],"title":"Documented options"}]}},"RequestedLocale":"zh-Hans","Fallback":true,"Versions":["10","11","12","13","14","15","16","17","18","19","20"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}