pg_receivewal

pg_receivewal — 从 PostgreSQL 服务器流式接收预写式日志

语法

pg_receivewal [选项...]

描述

pg_receivewal 用于从正在运行的 PostgreSQL 集群流式接收预写式日志。预写式日志通过流复制协议传输，并写入本地的文件目录中。该目录可用作归档位置，以便使用时间点恢复（PITR）进行恢复（参见第 25.3 节）。

pg_receivewal 实时流式接收服务器上生成的预写式日志，不会像 archive_command 和 archive_library 那样等待段文件完成。因此，使用 pg_receivewal 时无需设置 archive_timeout。

与 PostgreSQL 备库的 WAL 接收进程不同，pg_receivewal 默认仅在 WAL 文件关闭时刷新 WAL 数据。必须指定 --synchronous 选项才能实时刷新 WAL 数据。由于 pg_receivewal 不应用 WAL，当 synchronous_commit 设置为 remote_apply 时，不应将其配置为同步备库。如果这样做，它将显示为一个永远无法追赶上主库的备库，并导致事务提交阻塞。为避免这种情况，您应该为 synchronous_standby_names 配置适当的值，或者为 pg_receivewal 指定与之不匹配的 application_name，或者将 synchronous_commit 的值更改为 remote_apply 以外的值。

预写式日志通过常规的 PostgreSQL 连接进行流式传输，并使用复制协议。连接必须使用具有 REPLICATION 权限（参见第 21.2 节）的用户或超级用户建立，并且 pg_hba.conf 必须允许复制连接。服务器还必须将 max_wal_senders 配置为足够高的值，以至少留出一个会话用于流式传输。

WAL 流式传输的起始点在 pg_receivewal 启动时计算：

1. 首先，扫描写入 WAL 段文件的目录，找到最新的已完成的段文件，并使用下一个 WAL 段文件的起始点作为起点。
2. 如果无法通过上述方法计算起点，并且使用了复制槽，则会发出一个额外的 READ_REPLICATION_SLOT 命令来检索槽的 restart_lsn 作为起点。此选项仅在从 PostgreSQL 15 及更高版本流式接收预写式日志时可用。
3. 如果无法通过上述方法计算起点，则使用服务器通过 IDENTIFY_SYSTEM 命令报告的最新 WAL 刷新位置。

如果连接丢失，或者初始建立连接时遇到非致命错误，pg_receivewal 将无限期重试连接，并尽快重新建立流式传输。要避免此行为，请使用 -n 参数。

如果没有发生致命错误，pg_receivewal 将一直运行，直到被 SIGINT（Control+C）或 SIGTERM 信号终止。

选项

• -D directory
  **--directory=**directory
  写入输出文件的目录。
  此参数是必需的。

• -E lsn
  **--endpos=**lsn
  当接收达到指定的 LSN 时，自动停止复制并以正常退出状态 0 退出。
  如果存在 LSN 恰好等于 lsn 的记录，该记录将被处理。

• --if-not-exists
  当指定了 --create-slot 且具有指定名称的槽已存在时，不要报错。

• -n
--no-loop
  不要循环处理连接错误。出现错误时立即退出。

• --no-sync
  此选项使 pg_receivewal 不强制将 WAL 数据刷新到磁盘。这样更快，但意味着后续操作系统崩溃可能导致 WAL 段文件损坏。通常，此选项用于测试，但在生产部署中进行 WAL 归档时不应使用。
  此选项与 --synchronous 不兼容。

• -s interval
  **--status-interval=**interval
  指定发送回服务器的状态包之间的时间间隔（秒）。这样可以更轻松地从服务器监控进度。值为零将完全禁用定期状态更新，但当服务器请求时仍会发送更新以避免超时断开连接。默认值为 10 秒。

• -S slotname
  **--slot=**slotname
  要求 pg_receivewal 使用现有的复制槽（参见第 26.2.6 节）。使用此选项时，pg_receivewal 将向服务器报告刷新位置，指示每个段何时已同步到磁盘，以便服务器可以在不需要时删除该段。
  当 pg_receivewal 的复制客户端在服务器上被配置为同步备库时，使用复制槽会将刷新位置报告给服务器，但仅在 WAL 文件关闭时进行。因此，该配置将导致主库上的事务等待很长时间，实际上无法令人满意地工作。必须另外指定 --synchronous 选项（见下文）才能使其正常工作。

• --synchronous
  接收到 WAL 数据后立即将其刷新到磁盘。此外，刷新后立即将状态包发送回服务器，无论 --status-interval 设置如何。
  如果 pg_receivewal 的复制客户端在服务器上被配置为同步备库，则应指定此选项，以确保及时向服务器发送反馈。

• -v
--verbose
  启用详细模式。

• -Z level
  -Z method[:detail]
  **--compress=**level
  **--compress=**method[:detail]
  启用对预写式日志的压缩。
  压缩方法可以设置为 gzip、lz4（如果 PostgreSQL 编译时使用了 --with-lz4）或 none（不压缩）。可以选择指定一个压缩详情字符串。如果详情字符串是整数，则指定压缩级别。否则，它应该是一个逗号分隔的项列表，每一项的形式为 keyword 或 keyword=value。目前，唯一支持的关键字是 level。
  如果未指定压缩级别，将使用默认压缩级别。如果仅指定了级别而未提及算法，则当级别大于 0 时使用 gzip 压缩，当级别为 0 时则不使用压缩。
  使用 gzip 时，后缀 .gz 将自动添加到所有文件名；使用 lz4 时，将添加后缀 .lz4。

以下命令行选项控制数据库连接参数。

• -d connstr
  **--dbname=**connstr
  指定用于连接到服务器的参数，格式为连接字符串；这将覆盖任何冲突的命令行选项。
  此选项为与其他客户端应用程序保持一致而称为 --dbname，但由于 pg_receivewal 不连接到集群中的任何特定数据库，因此连接字符串中包含的任何数据库名称都将被服务器忽略。但是，在 ~/.pgpass 中查找复制连接的密码时，以这种方式提供的数据库名称会覆盖默认数据库名称（replication）。类似地，用于连接到 PostgreSQL 的中间件或代理可能会出于连接路由等目的使用该名称。

• -h host
  **--host=**host
  指定服务器运行所在机器的主机名。如果值以斜杠开头，则将其用作 Unix 域套接字的目录。默认取自 PGHOST 环境变量（如果已设置），否则尝试 Unix 域套接字连接。

• -p port
  **--port=**port
  指定服务器监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认为 PGPORT 环境变量（如果已设置）或编译时的默认值。

• -U username
  **--username=**username
  连接时使用的用户名。

• -w
--no-password
  从不提示输入密码。如果服务器要求密码认证且无法通过其他方式（如 .pgpass 文件）获得密码，则连接尝试将失败。此选项在批处理作业和脚本中很有用，因为没有用户在场输入密码。

• -W
--password
  强制 pg_receivewal 在连接到数据库之前提示输入密码。
  此选项并非必需，因为如果服务器要求密码认证，pg_receivewal 会自动提示输入密码。但是，pg_receivewal 会浪费一次连接尝试来发现服务器需要密码。在某些情况下，值得输入 -W 以避免额外的连接尝试。

pg_receivewal 可以执行以下两个操作之一来控制物理复制槽：

• --create-slot
  创建一个名为 --slot 指定的新物理复制槽，然后退出。

• --drop-slot
  删除名为 --slot 指定的复制槽，然后退出。

其他可用选项：

• -V
--version
  打印 pg_receivewal 版本并退出。

• -?
--help
  显示有关 pg_receivewal 命令行参数的帮助信息，然后退出。

退出状态

当 pg_receivewal 被 SIGINT 或 SIGTERM 信号终止时，将以状态 0 退出。（这是正常结束方式，因此不算错误。）对于致命错误或其他信号，退出状态将为非零。

环境

此实用程序与大多数其他 PostgreSQL 实用程序一样，使用 libpq 支持的环境变量（参见第 32.15 节）。

环境变量 PG_COLOR 指定是否在诊断消息中使用颜色。可能的值有 always、auto 和 never。

注意事项

当使用 pg_receivewal 替代 archive_command 或 archive_library 作为主要的 WAL 备份方法时，强烈建议使用复制槽。否则，服务器可能会在预写式日志文件被备份之前就回收或删除它们，因为它没有任何信息（无论是来自 archive_command、archive_library 还是复制槽）来了解 WAL 流已被归档到哪个位置。但请注意，如果接收方跟不上获取 WAL 数据的速度，复制槽会填满服务器的磁盘空间。

如果在源集群上启用了组权限，pg_receivewal 将保留接收到的 WAL 文件的组权限。

示例

要从服务器 mydbserver 流式接收预写式日志并将其存储在本地目录 /usr/local/pgsql/archive 中：

$ pg_receivewal -h mydbserver -D /usr/local/pgsql/archive