{"Entry":{"collection":"tool","key":"pg-rewind","name":"pg_rewind","aliases":["pg_rewind"],"metadata":{"aliases":["pg_rewind"],"category":"Server applications","content_hash":"972142a26f177cc984d85aa8249d432ea7952b400317e35aa322a96423eb951e","derived_content_hash":"2e7fec0096abe8fe61ae733608ce05715f08669c7897278f9f0df75e211e2573","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"],"description_zh":"描述 pg_rewind 是一个工具，用于在同一 PostgreSQL 集簇的两份副本时间线发生分叉后，将其中一份重新同步到另一份。典型场景是故障切换后，让旧主库重新上线，作为跟随新主库的备库。 成功完成回卷后，目标数据目录的状态相当于源数据目录的一份基础备份。与重新获取一份基础备份或使用 rsync 之类的工具不同， pg_rewind 不需要比较或复制集簇中未发生变化的关系块。它只复制现有关系文件中发生变化的块；其余所有文件，包括新的关系文件、配置文件以及 WAL 段，都会整体复制。因此，当数据库规模很大而两个集簇之间只有少量块不同时，回卷操作会比其他方法快得多。 pg_rewind 会检查源集簇和目标集簇的时间线历史，以确定它们发生分叉的位置，并且要求在目标集簇的 pg_wal 目录中能够找到一直追溯到该分叉点的 WAL。分叉点可能位于目标时间线、源时间线，或者二者共同的祖先时间线上。在典型的故障切换场景中，目标集簇会在分叉后不久关闭，因此这通常不是问题；但如果目标集簇在分叉后又运行了很长时间，旧的 WAL 文件可能已经不存在。在这种情况下，你可以手动把它们从 WAL 归档复制到 pg_wal 目录，也可以使用 -c 选项运行 pg_rewind ，让它自动从 WAL 归档中取回这些文件。 pg_rewind 的用途并不限于故障切换，例如，备库可以被提升，运行一些写事务，然后再回卷，重新成为备库。 运行 pg_rewind 之后，还需要完成 WAL 重放，数据目录才能处于一致状态。当再次启动目标服务器时，它会进入归档恢复，并重放源服务器上自分叉点之前最后一个检查点以来生成的全部 WAL。如果运行 pg_rewind 时，源服务器上的某些 WAL 已经不可用，因此无法由 pg_rewind 会话复制，那么在启动目标服务器时必须能够获取这些 WAL。这可以通过在目标数据目录中创建 recovery.signal 文件，并在 postgresql.conf 中配置合适的 restore_command 来实现。 pg_rewind 要求目标服务器满足以下条件之一：要么在","description_zh_html":"\u003cp\u003e命令行工具 pg_rewind [ option ...] { -D | --target-pgdata } directory { --source-pgdata= directory | --source-server= connstr }。\u003c/p\u003e\u003ch3\u003e同版本中文手册节选\u003c/h3\u003e\u003cdiv class=\"refsect1\"\u003e\u003ch2\u003e描述\u003c/h2\u003e\u003cp\u003e\n\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 是一个工具，用于在同一 \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e 集簇的两份副本时间线发生分叉后，将其中一份重新同步到另一份。典型场景是故障切换后，让旧主库重新上线，作为跟随新主库的备库。\n  \u003c/p\u003e\u003cp\u003e\n   成功完成回卷后，目标数据目录的状态相当于源数据目录的一份基础备份。与重新获取一份基础备份或使用 \u003cspan class=\"application\"\u003ersync\u003c/span\u003e 之类的工具不同，\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 不需要比较或复制集簇中未发生变化的关系块。它只复制现有关系文件中发生变化的块；其余所有文件，包括新的关系文件、配置文件以及 WAL 段，都会整体复制。因此，当数据库规模很大而两个集簇之间只有少量块不同时，回卷操作会比其他方法快得多。\n  \u003c/p\u003e\u003cp\u003e\n\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 会检查源集簇和目标集簇的时间线历史，以确定它们发生分叉的位置，并且要求在目标集簇的 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e 目录中能够找到一直追溯到该分叉点的 WAL。分叉点可能位于目标时间线、源时间线，或者二者共同的祖先时间线上。在典型的故障切换场景中，目标集簇会在分叉后不久关闭，因此这通常不是问题；但如果目标集簇在分叉后又运行了很长时间，旧的 WAL 文件可能已经不存在。在这种情况下，你可以手动把它们从 WAL 归档复制到 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e 目录，也可以使用 \u003ccode class=\"literal\"\u003e-c\u003c/code\u003e 选项运行 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e，让它自动从 WAL 归档中取回这些文件。\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 的用途并不限于故障切换，例如，备库可以被提升，运行一些写事务，然后再回卷，重新成为备库。\n  \u003c/p\u003e\u003cp\u003e\n   运行 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 之后，还需要完成 WAL 重放，数据目录才能处于一致状态。当再次启动目标服务器时，它会进入归档恢复，并重放源服务器上自分叉点之前最后一个检查点以来生成的全部 WAL。如果运行 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 时，源服务器上的某些 WAL 已经不可用，因此无法由 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 会话复制，那么在启动目标服务器时必须能够获取这些 WAL。这可以通过在目标数据目录中创建 \u003ccode class=\"filename\"\u003erecovery.signal\u003c/code\u003e 文件，并在 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e 中配置合适的 \u003ca class=\"xref\" href=\"/zh/docs/18/runtime-config-wal.html#GUC-RESTORE-COMMAND\"\u003erestore_command\u003c/a\u003e 来实现。\n  \u003c/p\u003e\u003cp\u003e\n\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 要求目标服务器满足以下条件之一：要么在 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e 中启用了 \u003ca class=\"xref\" href=\"/zh/docs/18/runtime-config-wal.html#GUC-WAL-LOG-HINTS\"\u003ewal_log_hints\u003c/a\u003e 选项，要么在用 \u003cspan class=\"application\"\u003einitdb\u003c/span\u003e 初始化集簇时启用了数据校验和（默认即如此）。此外，\u003ca class=\"xref\" href=\"/zh/docs/18/runtime-config-wal.html#GUC-FULL-PAGE-WRITES\"\u003efull_page_writes\u003c/a\u003e 也必须设置为 \u003ccode class=\"literal\"\u003eon\u003c/code\u003e，不过它默认已启用。\n  \u003c/p\u003e\u003cdiv class=\"warning\"\u003e\u003ch3 class=\"title\"\u003e警告：回卷过程中发生故障\u003c/h3\u003e\u003cp\u003e\n    如果 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 在处理过程中失败，目标数据目录很可能已经处于无法恢复的状态。在这种情况下，建议重新获取一份全新的备份。\n   \u003c/p\u003e\u003cp\u003e\n    由于 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 会把配置文件完整地从源复制过来，因此在重新启动目标服务器之前，可能需要修正恢复所用的配置，尤其是在将目标重新引入为源的备库时。如果回卷操作完成后重启服务器，却没有配置恢复，目标可能会再次与主库分叉。\n   \u003c/p\u003e\u003cp\u003e\n    如果 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 发现某些文件无法直接写入，它就会立即失败。例如，当源服务器和目标服务器对只读 SSL 密钥和证书使用相同的文件映射时，就会发生这种情况。如果目标服务器上存在这类文件，建议在运行 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 之前将其移除。回卷完成后，其中一些文件可能已经从源复制过来，这种情况下可能需要删除复制过来的数据，并恢复回卷前使用的那组链接。\n   \u003c/p\u003e\u003c/div\u003e\u003c/div\u003e\u003cdiv class=\"refsect1\"\u003e\u003ch2\u003e选项\u003c/h2\u003e\u003cp\u003e\n\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 接受以下命令行参数：\n\n    \u003c/p\u003e\u003cdiv class=\"variablelist\"\u003e\u003cdl class=\"variablelist\"\u003e\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\u003cdd\u003e\u003cp\u003e\n        此选项指定要与源同步的目标数据目录。在运行 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 之前，目标服务器必须已正常关闭。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        指定源服务器数据目录的文件系统路径，以便将目标与之同步。此选项要求源服务器已正常关闭。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        指定一个 libpq 连接字符串，用于连接源 \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e 服务器，以便将目标与之同步。该连接必须是普通连接（非复制连接），所用角色要么拥有足够的权限以执行 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 在源服务器上使用的函数（详见注解部分），要么是超级用户角色。此选项要求源服务器正在运行并接受连接。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        在输出目录中创建 \u003ccode class=\"filename\"\u003estandby.signal\u003c/code\u003e，并把连接设置追加到 \u003ccode class=\"filename\"\u003epostgresql.auto.conf\u003c/code\u003e 中。只有当连接字符串或\u003ca class=\"link\" href=\"/zh/docs/18/libpq-envars.html\"\u003e环境变量\u003c/a\u003e中显式指定了 dbname 时，才会记录 dbname。使用此选项时，必须指定 \u003ccode class=\"literal\"\u003e--source-server\u003c/code\u003e。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        执行除实际修改目标目录之外的所有操作。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        默认情况下，\u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e 会等待所有文件都安全写入磁盘。此选项会使 \u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e 不等待就返回，这样虽然更快，但也意味着如果随后发生操作系统崩溃，数据目录可能会损坏。通常，这个选项适合测试，但不应在生产环境中使用。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        启用进度报告。打开该选项后，在从源集簇复制数据时会给出大致的进度信息。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        如果这些文件在 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e 目录中已不可用，则使用目标集簇配置中定义的 \u003ccode class=\"varname\"\u003erestore_command\u003c/code\u003e 从 WAL 归档中取回 WAL 文件。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        为目标集簇使用指定的主配置文件。当 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 在该集簇上内部使用 \u003cspan class=\"application\"\u003epostgres\u003c/span\u003e 命令执行回卷操作时，这一选项会对其产生影响（包括使用 \u003ccode class=\"option\"\u003e-c/--restore-target-wal\u003c/code\u003e 获取 \u003ccode class=\"varname\"\u003erestore_command\u003c/code\u003e 以及强制完成崩溃恢复时）。\n       \u003c/p\u003e\u003c/dd\u003e\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--debug\u003c/code\u003e\u003c/span\u003e \u003c/dt\u003e\u003cdd\u003e\u003cp\u003e\n        打印详细的调试输出，这些输出主要对调试 \u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 的开发人员有用。\n       \u003c/p\u003e\u003c/dd\u003e\u003cdt\u003e\u003cspan class=\"term\"\u003e\u003ccode class=\"option\"\u003e--no-ensure-shutdown\u003c/code\u003e\u003c/span\u003e \u003c/dt\u003e\u003cdd\u003e\u003cp\u003e\n\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 要求在回卷前目标服务器已正常关闭。默认情况下，如果目标服务器未正常关闭，\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 会先以单用户模式启动目标服务器以完成崩溃恢复，然后再将其停止。指定此选项后，\u003cspan class=\"application\"\u003epg_rewind\u003c/span\u003e 会跳过这一步；如果服务器未正常关闭，它会立即报错。在这种情况下，用户应自行处理。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e\n        设为 \u003ccode class=\"literal\"\u003efsync\u003c/code\u003e（默认值）时，\u003ccode class=\"command\"\u003epg_rewind\u003c/code\u003e 会递归打开并同步数据目录中的所有文件。搜索文件时会跟随 WAL 目录及每个已配置表空间的符号链接。\n       \u003c/p\u003e\u003cp\u003e\n        在 Linux 上，也可以改用 \u003ccode class=\"literal\"\u003esyncfs\u003c/code\u003e，请求操作系统同步包含数据目录、WAL 文件以及各个表空间的整个文件系统。关于使用 \u003ccode class=\"literal\"\u003esyncfs\u003c/code\u003e 时需要注意的限制，请参见 \u003ca class=\"xref\" href=\"/zh/docs/18/runtime-config-error-handling.html#GUC-RECOVERY-INIT-SYNC-METHOD\"\u003erecovery_init_sync_method\u003c/a\u003e。\n       \u003c/p\u003e\u003cp\u003e\n        使用 \u003ccode class=\"option\"\u003e--no-sync\u003c/code\u003e 时，此选项无效。\n       \u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e显示版本信息，然后退出。\u003c/p\u003e\u003c/dd\u003e\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\u003cdd\u003e\u003cp\u003e显示帮助，然后退出。\u003c/p\u003e\u003c/dd\u003e\u003c/dl\u003e\u003c/div\u003e\u003cp\u003e\n\u003c/p\u003e\u003c/div\u003e\u003cp\u003e\u003ca href=\"/zh/docs/18/app-pgrewind.html\"\u003e查看完整中文手册与上下文\u003c/a\u003e。\u003c/p\u003e","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"}],"facts_zh":[{"label":"手册中的可执行程序","value":"pg_rewind"},{"label":"程序版本","value":"18.6"},{"label":"参考清单","value":"服务端程序"},{"label":"选项定义组","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":[],"sections_zh":[],"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"}],"tables_zh":[{"columns":[{"key":"signature","label":"选项与参数"},{"key":"summary","label":"说明"}],"key":"options","rows":[{"signature":{"text":"-D directory --target-pgdata= directory","url":"/docs/18/app-pgrewind.html"},"summary":"此选项指定要与源同步的目标数据目录。在运行 pg_rewind 之前，目标服务器必须已正常关闭。"},{"signature":{"text":"--source-pgdata= directory","url":"/docs/18/app-pgrewind.html"},"summary":"指定源服务器数据目录的文件系统路径，以便将目标与之同步。此选项要求源服务器已正常关闭。"},{"signature":{"text":"--source-server= connstr","url":"/docs/18/app-pgrewind.html"},"summary":"指定一个 libpq 连接字符串，用于连接源 PostgreSQL 服务器，以便将目标与之同步。该连接必须是普通连接（非复制连接），所用角色要么拥有足够的权限以执行 pg_rewind 在源服务器上使用的函数（详见注解部分），要么是超级用户角色。此选项要求源服务器正在运行并接受连接。"},{"signature":{"text":"-R --write-recovery-conf","url":"/docs/18/app-pgrewind.html"},"summary":"在输出目录中创建 standby.signal ，并把连接设置追加到 postgresql.auto.conf 中。只有当连接字符串或 环境变量 中显式指定了 dbname 时，才会记录 dbname。使用此选项时，必须指定 --source-server 。"},{"signature":{"text":"-n --dry-run","url":"/docs/18/app-pgrewind.html"},"summary":"执行除实际修改目标目录之外的所有操作。"},{"signature":{"text":"-N --no-sync","url":"/docs/18/app-pgrewind.html"},"summary":"默认情况下， pg_rewind 会等待所有文件都安全写入磁盘。此选项会使 pg_rewind 不等待就返回，这样虽然更快，但也意味着如果随后发生操作系统崩溃，数据目录可能会损坏。通常，这个选项适合测试，但不应在生产环境中使用。"},{"signature":{"text":"-P --progress","url":"/docs/18/app-pgrewind.html"},"summary":"启用进度报告。打开该选项后，在从源集簇复制数据时会给出大致的进度信息。"},{"signature":{"text":"-c --restore-target-wal","url":"/docs/18/app-pgrewind.html"},"summary":"如果 WAL 文件在 pg_wal 目录中已不可用，则使用目标集群配置中定义的 restore_command 从 WAL 归档中获取这些文件。"},{"signature":{"text":"--config-file= filename","url":"/docs/18/app-pgrewind.html"},"summary":"为目标集群使用指定的服务器主配置文件。当 pg_rewind 为回退操作在内部调用 postgres 命令处理此集群时（包括使用 -c/--restore-target-wal 选项获取 restore_command，以及强制完成崩溃恢复），此设置会影响这些调用。"},{"signature":{"text":"--debug","url":"/docs/18/app-pgrewind.html"},"summary":"打印详细的调试输出，这些输出主要对调试 pg_rewind 的开发人员有用。"},{"signature":{"text":"--no-ensure-shutdown","url":"/docs/18/app-pgrewind.html"},"summary":"pg_rewind 要求在回卷前目标服务器已正常关闭。默认情况下，如果目标服务器未正常关闭， pg_rewind 会先以单用户模式启动目标服务器以完成崩溃恢复，然后再将其停止。指定此选项后， pg_rewind 会跳过这一步；如果服务器未正常关闭，它会立即报错。在这种情况下，用户应自行处理。"},{"signature":{"text":"--sync-method= method","url":"/docs/18/app-pgrewind.html"},"summary":"设为 fsync （默认值）时， pg_rewind 会递归打开并同步数据目录中的所有文件。搜索文件时会跟随 WAL 目录及每个已配置表空间的符号链接。"},{"signature":{"text":"-V --version","url":"/docs/18/app-pgrewind.html"},"summary":"显示版本信息，然后退出。"},{"signature":{"text":"-? --help","url":"/docs/18/app-pgrewind.html"},"summary":"显示帮助，然后退出。"}],"title":"手册中的选项"}],"zh_from":{"authored_translation":"source-derived-identity","body_sha256":"1e127cea56ecf75988cff3034040de3f78d10025691eb6fe45be940b99736679","kind":"same-version-chinese-manual-with-source-derived-identity","manual":{"anchor":"","build_id":107,"extraction":"command-description-and-options","fragment_sha256":"c86e366667480ddad966c6cd4ca22e136328b2791ff435ba18eef799171a79c3","locale":"zh-Hans","page_key":"app-pgrewind.html","source_hash":"e288a54ad498f84bbe1f99eb62471662046113c78137cae1b61a420dd01270d2","source_revision":"unknown:rendered-translation-baseline","translated_from_revision":null,"translation_revision":"git:b1b500221dbe5437cfca004d6b04d3f6e422765d;html-sha256:08e987a66af27b98444a8057c256314eafa13611a3fb9e888214fc436824244b","url":"/zh/docs/18/app-pgrewind.html","version":"18"},"runtime_rerun":false,"source_facts_revision":"ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8"}},"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":"en","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}