pg_rewind

当前查看 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 接受以下命令行参数：

-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

如果这些文件在 pg_wal 目录中已不可用，则使用目标集簇配置中定义的 restore_command 从 WAL 归档中取回 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 目录及每个已配置表空间的符号链接。

在 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 16 → 17: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 16
+++ PostgreSQL 17
@@ -85,6 +85,13 @@
       "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",

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

快速链接