pg_receivewal — 从 PostgreSQL 服务器流式传输预写日志
pg_receivewal [选项...]
pg_receivewal 用于从运行中的 PostgreSQL 集群流式传输预写日志。预写日志使用流式复制协议进行流式传输，并写入本地文件目录。此目录可以用作执行时间点恢复的归档位置（请参见第 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 设置得足够高，以便为流保留至少一个会话。
预写日志流的起始点在 pg_receivewal 启动时计算
首先，扫描写入 WAL 段文件的目录，并找到最新的已完成段文件，使用下一个 WAL 段文件的开头作为起始点。
如果无法使用先前的方法计算起始点，并且使用了复制槽，则会发出额外的 READ_REPLICATION_SLOT 命令，以检索该槽的 restart_lsn 以用作起始点。仅当从 PostgreSQL 15 及更高版本流式传输预写日志时，此选项才可用。
如果无法使用先前的方法计算起始点，则使用服务器从 IDENTIFY_SYSTEM 命令报告的最新 WAL 刷新位置。
如果连接丢失，或者无法以非致命错误初始建立连接，则 pg_receivewal 将无限期地重试连接，并尽快重新建立流。要避免此行为，请使用 -n 参数。
在没有致命错误的情况下，pg_receivewal 将一直运行，直到被 SIGINT （Control+C）或 SIGTERM 信号终止。
-D 目录--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 间隔--status-interval=间隔指定发送回服务器的状态数据包之间的秒数。这使得更容易从服务器监控进度。值为零会完全禁用定期状态更新，但仍会在服务器请求时发送更新，以避免超时断开连接。默认值为 10 秒。
-S 槽名--slot=槽名要求 pg_receivewal 使用现有的复制槽（请参见第 26.2.6 节）。使用此选项时，pg_receivewal 会向服务器报告刷新位置，指示每个段何时已同步到磁盘，以便服务器可以在不需要时删除该段。
当服务器上将 pg_receivewal 的复制客户端配置为同步备用服务器时，使用复制槽会将刷新位置报告给服务器，但仅在关闭 WAL 文件时才报告。因此，该配置将导致主服务器上的事务等待很长时间并且实际上无法正常工作。除了使此工作正常运行之外，还必须指定选项 --synchronous（请参见下文）。
--synchronous在接收到 WAL 数据后立即将其刷新到磁盘。并且在刷新后立即向服务器发送状态数据包，而不管 --status-interval 如何。
如果服务器上将 pg_receivewal 的复制客户端配置为同步备用服务器，则应指定此选项，以确保将及时反馈发送到服务器。
-v--verbose启用详细模式。
-Z 级别-Z 方法[:详细信息]--compress=级别--compress=方法[:详细信息]启用预写日志的压缩。
可以将压缩方法设置为 gzip、lz4（如果 PostgreSQL 是使用 --with-lz4 编译的）或 none 表示不压缩。可以选择指定压缩详细信息字符串。如果详细信息字符串为整数，则指定压缩级别。否则，它应为以逗号分隔的项目列表，每个项目的形式为 关键字 或 关键字=值。目前，唯一支持的关键字是 level。
如果未指定压缩级别，则将使用默认压缩级别。如果仅指定一个级别而没有提及算法，则如果级别大于 0，将使用 gzip 压缩，如果级别为 0，则不使用压缩。
使用 gzip 时，后缀 .gz 将自动添加到所有文件名，使用 lz4 时，将添加后缀 .lz4。
以下命令行选项控制数据库连接参数。
-d connstr--dbname=connstr指定用于连接到服务器的参数，作为连接字符串；这些参数将覆盖任何冲突的命令行选项。
为了与其他客户端应用程序保持一致，此选项名为 --dbname，但由于 pg_receivewal 不会连接到集群中的任何特定数据库，因此连接字符串中包含的任何数据库名称都将被服务器忽略。但是，以这种方式提供的数据库名称将覆盖默认数据库名称 (replication)，以便在 ~/.pgpass 中查找复制连接的密码。类似地，用于连接到 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 备份方法时，强烈建议使用复制槽。否则，服务器可以自由地回收或删除预写式日志文件，然后再进行备份，因为它没有任何关于 WAL 流存档进度的信息，无论是来自 archive_command 还是 archive_library 或复制槽。但是请注意，如果接收器没有跟上获取 WAL 数据的速度，复制槽会填满服务器的磁盘空间。
如果源集群上启用了组权限，pg_receivewal 将保留接收到的 WAL 文件上的组权限。
要从 mydbserver 上的服务器流式传输预写式日志并将其存储在本地目录 /usr/local/pgsql/archive 中：
$pg_receivewal -h mydbserver -D /usr/local/pgsql/archive
如果您在文档中发现任何不正确、与您特定功能的使用体验不符或需要进一步澄清的地方，请使用此表格报告文档问题。