pg_receivewal

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

当前查看 PostgreSQL 18.6。

说明

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

手册中的可执行程序: pg_receivewal
程序版本: 18.6
参考清单: 客户端程序
选项定义组: 20

用法

pg_receivewal [ option ...]

手册中的选项

选项与参数	说明
-D directory --directory= directory	用于写入输出的目录。
-E lsn --endpos= lsn	当接收位置到达指定 LSN 时，自动停止复制并以正常退出状态 0 退出。
--if-not-exists	当指定 --create-slot 且同名槽已存在时，不报错。
-n --no-loop	遇到连接错误时不要循环重试，而是立即报错退出。
--no-sync	此选项会使 pg_receivewal 不强制将 WAL 数据刷写到磁盘。这样会更快，但也意味着如果随后发生操作系统崩溃，可能会留下损坏的 WAL 段。一般来说，此选项适合测试，但不应在生产环境中执行 WAL 归档时使用。
-s interval --status-interval= interval	指定向服务器回送状态包的时间间隔（秒）。这样更便于从服务器端监视进度。值为零将完全禁用周期性状态更新，不过在服务器请求时仍会发送更新，以避免因超时而断开连接。默认值是 10 秒。
-S slotname --slot= slotname	要求 pg_receivewal 使用一个现有复制槽（见第 26.2.6 节）。使用此选项时， pg_receivewal 会向服务器报告刷写位置，指示每个段何时已同步到磁盘，以便服务器在该段不再被需要时将其移除。
--synchronous	在收到 WAL 数据后立即将其刷写到磁盘。无论 --status-interval 如何，刷写后还会立即向服务器回送状态包。
-v --verbose	启用详细输出模式。
-Z level -Z method [: detail ] --compress= level --compress= method [: detail ]	启用预写式日志的压缩。
-d connstr --dbname= connstr	以连接字符串的形式指定用于连接到服务器的参数；这些参数会覆盖任何冲突的命令行选项。
-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 在建立连接前提示输入密码。
--create-slot	使用 --slot 中指定的名称创建一个新的物理复制槽，然后退出。
--drop-slot	删除 --slot 中指定名称的复制槽，然后退出。
-V --version	打印 pg_receivewal 的版本并退出。
-? --help	显示 pg_receivewal 命令行参数的帮助并退出。

手册定义

pg_receivewal

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

大纲

pg_receivewal [option...]

说明

pg_receivewal用于从正在运行的PostgreSQL数据库集簇流式接收预写式日志。预写式日志通过流复制协议传输，并写入本地目录中的文件。该目录可作为使用时间点恢复执行恢复时的归档位置（见第 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权限（见第 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使用一个现有复制槽（见第 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 可以执行下列两种操作之一：

--create-slot

使用--slot中指定的名称创建一个新的物理复制槽，然后退出。

--drop-slot

删除--slot中指定名称的复制槽，然后退出。

还可以使用下列其他选项：

-V --version

打印pg_receivewal的版本并退出。

-? --help

显示pg_receivewal命令行参数的帮助并退出。

退出状态

当因SIGINT或SIGTERM信号终止时，pg_receivewal将以状态 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

另见

pg_basebackup

文档与源码

来源构建

版本: 18.6
构建: https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹: ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 10 → 11: 属性变化。

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

--- PostgreSQL 10
+++ PostgreSQL 11
@@ -8,6 +8,14 @@
         "--directory= directory"
       ],
       "signature": "-D directory --directory= directory"
+    },
+    {
+      "description": "Automatically stop replication and exit with normal exit status 0 when receiving reaches the specified LSN. If there is a record with LSN exactly equal to lsn , the record will be processed.",
+      "names": [
+        "-E lsn",
+        "--endpos= lsn"
+      ],
+      "signature": "-E lsn --endpos= lsn"
     },
     {
       "description": "Do not error out when --create-slot is specified and a slot with the specified name already exists.",
@@ -23,6 +31,13 @@
         "--no-loop"
       ],
       "signature": "-n --no-loop"
+    },
+    {
+      "description": "This option causes pg_receivewal to not force WAL data to be flushed to disk. This is faster, but means that a subsequent operating system crash can leave the WAL segments corrupt. Generally, this option is useful for testing but should not be used when doing WAL archiving on a production deployment. This option is incompatible with --synchronous .",
+      "names": [
+        "--no-sync"
+      ],
+      "signature": "--no-sync"
     },
     {
       "description": "Specifies the number of seconds between status packets sent back to the server. This allows for easier monitoring of the progress from server. A value of zero disables the periodic status updates completely, although an update will still be sent when requested by the server, to avoid timeout disconnect. The default value is 10 seconds.",

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

快速链接

pg_receivewal

说明

用法

手册中的选项

手册定义

pg_receivewal

大纲

说明

选项

退出状态

环境

注解

示例

另见

相关条目

文档与源码

版本比较

相关条目