pg_rewind
描述 pg_rewind 是一个工具，用于在同一 PostgreSQL 集簇的两份副本时间线发生分叉后，将其中一份重新同步到另一份。典型场景是故障切换后，让旧主库重新上线，作为跟随新主库的备库。 成功完成回卷后，目标数据目录的状态相当于源数据目录的一份基础备份。与重新获取一份基础备份或使用 rsync 之类的工具不同， pg_rewind 不需要比较或复制集簇中未发生变化的关系块。它只复制现有关系文件中发生变化的块；其余所有文件，包括新的关系文件、配置文件以及 WAL 段，都会整体复制。因此，…
当前查看 PostgreSQL 18。
中文定义与说明
命令行工具 pg_rewind [ option ...] { -D | --target-pgdata } directory { --source-pgdata= directory | --source-server= connstr }。
同版本中文手册节选
描述
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 要求目标服务器满足以下条件之一：要么在 postgresql.conf 中启用了 wal_log_hints 选项，要么在用 initdb 初始化集簇时启用了数据校验和（默认即如此）。此外，full_page_writes 也必须设置为 on，不过它默认已启用。
警告：回卷过程中发生故障
如果 pg_rewind 在处理过程中失败，目标数据目录很可能已经处于无法恢复的状态。在这种情况下，建议重新获取一份全新的备份。
由于 pg_rewind 会把配置文件完整地从源复制过来，因此在重新启动目标服务器之前，可能需要修正恢复所用的配置，尤其是在将目标重新引入为源的备库时。如果回卷操作完成后重启服务器，却没有配置恢复，目标可能会再次与主库分叉。
如果 pg_rewind 发现某些文件无法直接写入，它就会立即失败。例如，当源服务器和目标服务器对只读 SSL 密钥和证书使用相同的文件映射时，就会发生这种情况。如果目标服务器上存在这类文件，建议在运行 pg_rewind 之前将其移除。回卷完成后，其中一些文件可能已经从源复制过来，这种情况下可能需要删除复制过来的数据，并恢复回卷前使用的那组链接。
选项
pg_rewind 接受以下命令行参数：
-Ddirectory--target-pgdata=directory此选项指定要与源同步的目标数据目录。在运行 pg_rewind 之前，目标服务器必须已正常关闭。
--source-pgdata=directory指定源服务器数据目录的文件系统路径，以便将目标与之同步。此选项要求源服务器已正常关闭。
--source-server=connstr指定一个 libpq 连接字符串，用于连接源 PostgreSQL 服务器，以便将目标与之同步。该连接必须是普通连接（非复制连接），所用角色要么拥有足够的权限以执行 pg_rewind 在源服务器上使用的函数（详见注解部分），要么是超级用户角色。此选项要求源服务器正在运行并接受连接。
-R--write-recovery-conf在输出目录中创建
standby.signal，并把连接设置追加到postgresql.auto.conf中。只有当连接字符串或环境变量中显式指定了 dbname 时，才会记录 dbname。使用此选项时，必须指定--source-server。-n--dry-run执行除实际修改目标目录之外的所有操作。
-N--no-sync默认情况下，
pg_rewind会等待所有文件都安全写入磁盘。此选项会使pg_rewind不等待就返回，这样虽然更快，但也意味着如果随后发生操作系统崩溃，数据目录可能会损坏。通常，这个选项适合测试，但不应在生产环境中使用。-P--progress启用进度报告。打开该选项后，在从源集簇复制数据时会给出大致的进度信息。
-c--restore-target-wal如果这些文件在
pg_wal目录中已不可用，则使用目标集簇配置中定义的restore_command从 WAL 归档中取回 WAL 文件。--config-file=filename为目标集簇使用指定的主配置文件。当 pg_rewind 在该集簇上内部使用 postgres 命令执行回卷操作时，这一选项会对其产生影响（包括使用
-c/--restore-target-wal获取restore_command以及强制完成崩溃恢复时）。--debug打印详细的调试输出，这些输出主要对调试 pg_rewind 的开发人员有用。
--no-ensure-shutdownpg_rewind 要求在回卷前目标服务器已正常关闭。默认情况下，如果目标服务器未正常关闭，pg_rewind 会先以单用户模式启动目标服务器以完成崩溃恢复，然后再将其停止。指定此选项后，pg_rewind 会跳过这一步；如果服务器未正常关闭，它会立即报错。在这种情况下，用户应自行处理。
--sync-method=method设为
fsync（默认值）时，pg_rewind会递归打开并同步数据目录中的所有文件。搜索文件时会跟随 WAL 目录及每个已配置表空间的符号链接。在 Linux 上，也可以改用
syncfs，请求操作系统同步包含数据目录、WAL 文件以及各个表空间的整个文件系统。关于使用syncfs时需要注意的限制，请参见 recovery_init_sync_method。使用
--no-sync时，此选项无效。-V--version显示版本信息，然后退出。
-?--help显示帮助，然后退出。
说明
描述 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 要求目标服务器满足以下条件之一：要么在
- 手册中的可执行程序
- pg_rewind
- 程序版本
- 18.6
- 参考清单
- 服务端程序
- 选项定义组
- 14
用法
pg_rewind [ option ...] { -D | --target-pgdata } directory { --source-pgdata= directory | --source-server= connstr }手册中的选项
| 选项与参数 | 说明 |
|---|---|
| -D directory --target-pgdata= directory | 此选项指定要与源同步的目标数据目录。在运行 pg_rewind 之前，目标服务器必须已正常关闭。 |
| --source-pgdata= directory | 指定源服务器数据目录的文件系统路径，以便将目标与之同步。此选项要求源服务器已正常关闭。 |
| --source-server= connstr | 指定一个 libpq 连接字符串，用于连接源 PostgreSQL 服务器，以便将目标与之同步。该连接必须是普通连接（非复制连接），所用角色要么拥有足够的权限以执行 pg_rewind 在源服务器上使用的函数（详见注解部分），要么是超级用户角色。此选项要求源服务器正在运行并接受连接。 |
| -R --write-recovery-conf | 在输出目录中创建 standby.signal ，并把连接设置追加到 postgresql.auto.conf 中。只有当连接字符串或 环境变量 中显式指定了 dbname 时，才会记录 dbname。使用此选项时，必须指定 --source-server 。 |
| -n --dry-run | 执行除实际修改目标目录之外的所有操作。 |
| -N --no-sync | 默认情况下， pg_rewind 会等待所有文件都安全写入磁盘。此选项会使 pg_rewind 不等待就返回，这样虽然更快，但也意味着如果随后发生操作系统崩溃，数据目录可能会损坏。通常，这个选项适合测试，但不应在生产环境中使用。 |
| -P --progress | 启用进度报告。打开该选项后，在从源集簇复制数据时会给出大致的进度信息。 |
| -c --restore-target-wal | 如果 WAL 文件在 pg_wal 目录中已不可用，则使用目标集群配置中定义的 restore_command 从 WAL 归档中获取这些文件。 |
| --config-file= filename | 为目标集群使用指定的服务器主配置文件。当 pg_rewind 为回退操作在内部调用 postgres 命令处理此集群时（包括使用 -c/--restore-target-wal 选项获取 restore_command，以及强制完成崩溃恢复），此设置会影响这些调用。 |
| --debug | 打印详细的调试输出，这些输出主要对调试 pg_rewind 的开发人员有用。 |
| --no-ensure-shutdown | pg_rewind 要求在回卷前目标服务器已正常关闭。默认情况下，如果目标服务器未正常关闭， pg_rewind 会先以单用户模式启动目标服务器以完成崩溃恢复，然后再将其停止。指定此选项后， pg_rewind 会跳过这一步；如果服务器未正常关闭，它会立即报错。在这种情况下，用户应自行处理。 |
| --sync-method= method | 设为 fsync （默认值）时， pg_rewind 会递归打开并同步数据目录中的所有文件。搜索文件时会跟随 WAL 目录及每个已配置表空间的符号链接。 |
| -V --version | 显示版本信息，然后退出。 |
| -? --help | 显示帮助，然后退出。 |
文档与源码
来源构建
- 版本
- 18.6
- 构建
- https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
- 来源指纹
ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8
版本比较
PostgreSQL 11 → 12: 属性变化。
以下差异保留原始字段名与英文源描述。
--- PostgreSQL 11
+++ PostgreSQL 12
@@ -30,6 +30,14 @@
"--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 when creating 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.",比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。
相关条目
导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。