PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

pg_recvlogical

pg_recvlogical — 控制 PostgreSQL 逻辑解码流

Synopsis

pg_recvlogical [option...]

描述

pg_recvlogical 控制逻辑解码复制槽,并从这类复制槽流式地传输数据。

它会创建一个复制模式的连接,因此它受到与 pg_receivewal 相同的约束,外加逻辑复制的约束(参见 Chapter 47)。

pg_recvlogical 没有与逻辑解码 SQL 接口的 peek 和 get 模式等价的功能。它在接收数据时会延迟发送重放确认,并在干净退出时发送。要检查槽上待处理的数据而不消费它们,请使用 pg_logical_slot_peek_changes。

在没有致命错误的情况下,pg_recvlogical 将一直运行,直到被 SIGINT(Control+C)或 SIGTERM 信号终止。

当 pg_recvlogical 接收到 SIGHUP 信号时,它会关闭当前的输出文件,并使用 --file 选项指定的文件名打开一个新文件。这使得我们可以轮转输出文件:先重命名当前文件,然后发送一个 SIGHUP 信号给 pg_recvlogical。

选项

必须至少指定下列选项之一来选择一个操作:

--create-slot

以 --slot 指定的名称、使用 --plugin 指定的输出插件,为 --dbname 指定的数据库创建一个新的逻辑复制槽。

此操作需要 --slot 和 --dbname。

--enable-two-phase 和 --enable-failover 选项可以与 --create-slot 一起指定。

--drop-slot

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

此操作需要 --slot。

--start

开始从由 --slot 指定的逻辑复制槽流式接收变更,一直持续到被信号终止。如果服务器端的变更流因服务器关闭或断开连接而结束,则会循环重试,除非指定了 --no-loop。

此操作需要 --slot 和 --dbname、--file。

流的格式由创建槽时指定的输出插件决定。

连接必须指向创建该槽时所用的同一个数据库。

--create-slot 和 --start 可以一起指定。--drop-slot 不能与其他操作组合使用。

下列命令行选项控制输出的位置和格式以及其他复制行为:

-E lsn
--endpos=lsn

在 --start 模式下,当接收到达指定的 LSN 时,自动停止复制并以正常退出状态 0 退出。如果在 --start 模式之外指定该选项,则会引发错误。

如果存在一条 LSN 恰好等于 lsn 的记录,该记录将被输出。

--endpos 选项不感知事务边界,可能会在一个事务的中途截断输出。任何被部分输出的事务都不会被消费,并且在下一次读取该槽时会再次重放。单条消息绝不会被截断。

--enable-failover

允许将该槽同步到后备服务器上。此选项只能与 --create-slot 一起指定。

-f filename
--file=filename

将接收并解码的事务数据写入此文件。使用 - 表示 stdout。

--start 需要此参数。

-F interval_seconds
--fsync-interval=interval_seconds

指定 pg_recvlogical 应当每隔多久发出一次 fsync() 调用,以确保输出文件被安全地刷写到磁盘上。

服务器会偶尔请求客户端执行一次刷写并向服务器报告刷写位置。此设置是在此基础上的补充,用于更频繁地执行刷写。

将间隔指定为 0 会完全禁用发出 fsync() 调用,但仍会向服务器报告进度。在这种情况下,一旦发生崩溃,数据可能会丢失。

-I lsn
--startpos=lsn

在 --start 模式下,从给定的 LSN 开始复制。关于其效果的详细信息,请参见 Chapter 47 和 Section 54.4 中的文档。在其他模式中会被忽略。

--if-not-exists

当指定了 --create-slot 且具有指定名称的槽已经存在时,不报错退出。

-n
--no-loop

当与服务器之间的连接丢失时,不进行循环重试,直接退出。

-o name[=value]
--option=name[=value]

将选项 name 传递给输出插件,如果指定了的话,还带上选项值 value。存在哪些选项以及它们的效果取决于所使用的输出插件。

-P plugin
--plugin=plugin

创建槽时,使用指定的逻辑解码输出插件。参见 Chapter 47。如果槽已经存在,此选项没有效果。

-s interval_seconds
--status-interval=interval_seconds

此选项与 pg_receivewal 中同名选项具有相同的效果。请参见那里的描述。

-S slot_name
--slot=slot_name

在 --start 模式下,使用名为 slot_name 的现有逻辑复制槽。在 --create-slot 模式下,用此名称创建槽。在 --drop-slot 模式下,删除具有此名称的槽。

所有操作都需要此参数。

-t
--enable-two-phase
--two-phase (deprecated)

启用对已预备事务的解码。此选项只能与 --create-slot 一起指定。

-v
--verbose

启用详细模式。

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

-d dbname
--dbname=dbname

要连接到的数据库。关于它的详细含义,请参见对各个操作的描述。dbname 可以是一个 connection string。如果是这样,连接字符串参数将覆盖任何与之冲突的命令行选项。

--create-slot 和 --start 需要此参数。

-h hostname-or-ip
--host=hostname-or-ip

指定服务器所在机器的主机名。如果值以斜杠开头,则它被用作 Unix 域套接字的目录。默认值取自 PGHOST 环境变量(如果设置了),否则会尝试进行 Unix 域套接字连接。

-p port
--port=port

指定服务器监听连接所用的 TCP 端口或本地 Unix 域套接字文件扩展名。默认为 PGPORT 环境变量(如果设置了),或者为编译进程序的默认值。

-U user
--username=user

用于连接的用户名。默认为当前的操作系统用户名。

-w
--no-password

从不发出输入密码的提示。如果服务器要求密码认证,而密码无法通过其他方式(例如 .pgpass 文件)获得,则连接尝试将失败。此选项在没有用户在场输入密码的批处理作业和脚本中很有用。

-W
--password

强制 pg_recvlogical 在连接数据库之前提示输入密码。

此选项从来都不是必需的,因为如果服务器要求密码认证,pg_recvlogical 会自动提示输入密码。不过,pg_recvlogical 会浪费一次连接尝试来发现服务器需要密码。在某些情况下,键入 -W 可以避免这次额外的连接尝试,这样做是值得的。

还可以使用下列附加选项:

-V
--version

打印 pg_recvlogical 的版本并退出。

-?
--help

显示关于 pg_recvlogical 命令行参数的帮助,然后退出。

退出状态

pg_recvlogical 在被 SIGINT 或 SIGTERM 信号终止时将以状态 0 退出。(这是结束它的正常方式,因此这不是错误。)对于致命错误或其他信号,退出状态将为非零。

环境

与大多数其他 PostgreSQL 工具一样,此工具也使用 libpq 支持的环境变量(参见 Section 32.15)。

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

注记

如果源集簇上启用了组权限,pg_recvlogical 将在输出文件上保留组权限。

示例

示例请参见 Section 47.1。

另请参阅

pg_receivewal