pg_receivewal — 从PostgreSQL服务器流式接收预写式日志
pg_receivewal [option...]
pg_receivewal用于从正在运行的PostgreSQL数据库集簇流式接收预写式日志。预写式日志通过流复制协议传输，并写入本地目录中的文件。该目录可作为使用时间点恢复执行恢复时的归档位置（见Section 25.3）。
pg_receivewal会在服务器生成预写式日志的同时实时流式接收，而不像archive_command和archive_library那样等待 WAL 段完成。 因此，使用pg_receivewal时无需设置archive_timeout。
与 PostgreSQL 备库的 WAL 接收器不同，pg_receivewal默认只会在一个 WAL 文件关闭时才将 WAL 数据刷写到磁盘。要实时刷写 WAL 数据，必须指定--synchronous选项。 由于pg_receivewal不会应用 WAL，因此当synchronous_commit等于remote_apply时，不应让它成为同步备库。 如果这样做，它看起来会像一台永远追不上的备库，并导致事务提交阻塞。 为避免这种情况，应当为synchronous_standby_names配置合适的值，或者为pg_receivewal指定一个与之不匹配的application_name，或者将synchronous_commit改成remote_apply以外的值。
预写式日志通过普通的PostgreSQL连接进行流式传输，并使用复制协议。建立该连接时，必须使用具有REPLICATION权限（见Section 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--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使用一个现有复制槽（见Section 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并不连接到集簇中的任何特定数据库，连接字符串中包含的数据库名会被服务器忽略。不过，以这种方式提供的数据库名会覆盖默认数据库名（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 可以执行下列两种操作之一：
还可以使用下列其他选项：
当因SIGINT或SIGTERM信号终止时，pg_receivewal将以状态 0 退出。（这是其正常结束方式，因此不算错误。）对于致命错误或其他信号，退出状态将为非零值。
与大多数其他PostgreSQL工具一样，此工具也使用libpq支持的环境变量（见Section 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
如果您发现文档中有不正确的内容、与您使用特定功能的经验不符或需要进一步说明，请使用此表单来报告文档问题。