pg_recvlogical
pg_recvlogical — 控制 PostgreSQL 逻辑解码流
大纲
pg_recvlogical [option...]
描述
pg_recvlogical 用于控制逻辑解码复制槽,并从这类复制槽流式传输数据。
它会创建复制模式连接,因此除受到与 pg_receivewal 相同的约束外,还要满足逻辑复制的相关约束(见第 49 章)。
pg_recvlogical 没有与逻辑解码 SQL 接口中 peek 和 get 模式等价的功能。它会在接收数据期间惰性地为这些数据发送重放确认,并在正常退出时发送确认。若要在不消费数据的情况下检查某个槽上的待处理数据,请使用 pg_logical_slot_peek_changes。
在没有致命错误的情况下,pg_recvlogical 会一直运行,直到收到 SIGINT(Control+C)或 SIGTERM 信号。
当 pg_recvlogical 收到 SIGHUP 信号时,它会关闭当前输出文件,并使用 --file 选项指定的文件名打开一个新文件。这样就可以通过先重命名当前文件,再向 pg_recvlogical 发送
SIGHUP 信号来轮换输出文件。
选项
至少必须指定以下选项之一,以选择要执行的操作:
--create-slot#为由
--dbname指定的数据库,使用--plugin指定的输出插件,创建一个名称由--slot指定的新逻辑复制槽。可与
--create-slot一起指定--two-phase,以启用对预备事务的解码。--drop-slot#删除由
--slot指定名称的复制槽,然后退出。--start#开始从由
--slot指定的逻辑复制槽流式传输更改,并持续运行直到被信号终止。如果服务端的更改流因服务器关闭或断开连接而结束,则除非指定了--no-loop,否则会循环重试。流格式由创建该槽时指定的输出插件决定。
该连接必须连到创建该槽时所用的同一个数据库。
--create-slot 和 --start 可以一同指定。--drop-slot 不能与其他操作组合使用。
以下命令行选项控制输出的位置和格式以及其他复制行为:
-Elsn--endpos=#lsn在
--start模式下,当接收达到指定的 LSN 时,自动停止复制,并以正常退出状态 0 退出。如果在非--start模式下指定,则会报错。如果存在 LSN 恰好等于
lsn的记录,则该记录会被输出。--endpos选项不会感知事务边界,因此可能会在事务中途截断输出。任何只输出了一部分的事务都不会被消费,并会在下次从该槽读取时再次重放。单条消息永远不会被截断。-ffilename--file=#filename将接收到并解码后的事务数据写入该文件。指定
-表示写入 stdout。-Finterval_seconds--fsync-interval=#interval_seconds指定 pg_recvlogical 应当以多高的频率发起
fsync()调用,以确保输出文件安全刷盘。服务器会偶尔要求客户端执行刷盘,并将刷盘位置报告给服务器。除此之外,此设置还会更频繁地执行刷盘。
将间隔指定为
0会完全禁用fsync()调用,但仍会向服务器报告进度。在这种情况下,发生崩溃时可能会丢失数据。-Ilsn--startpos=#lsn在
--start模式下,从给定的 LSN 开始复制。关于其影响的详细信息,请参见第 49 章和第 55.4 节中的说明。在其他模式下会忽略此选项。--if-not-exists#当指定
--create-slot且指定名称的槽已存在时,不报错。-n--no-loop#当与服务器的连接丢失时,不要循环重试,直接退出。
-oname[=value]--option=#name[=value]将选项
name传递给输出插件;如果指定了value,则将其用作该选项的值。可用选项及其效果取决于所使用的输出插件。-Pplugin--plugin=#plugin创建该槽时,使用指定的逻辑解码输出插件。参见第 49 章。如果该槽已经存在,则此选项不起作用。
-sinterval_seconds--status-interval=#interval_seconds该选项与 pg_receivewal 中同名选项的效果相同。参见该处说明。
-Sslot_name--slot=#slot_name在
--start模式下,使用名为slot_name的现有逻辑复制槽。在--create-slot模式下,以此名称创建该槽。在--drop-slot模式下,删除此名称的槽。-t--two-phase#启用对预备事务的解码。此选项只能与
--create-slot一起指定。-v--verbose#启用详细模式。
下列命令行选项控制数据库连接参数。
-ddbname--dbname=#dbname要连接的数据库。有关其具体含义,请参阅各操作的说明。
dbname可以是一个连接字符串。如果如此,连接字符串参数会覆盖任何与之冲突的命令行选项。默认值为用户名。-hhostname-or-ip--host=#hostname-or-ip指定服务器运行所在机器的主机名。如果该值以斜杠开头,则它会被用作 Unix 域套接字的目录。默认值取自
PGHOST环境变量(如果已设置),否则将尝试 Unix 域套接字连接。-pport--port=#port指定服务器监听连接所用的 TCP 端口,或本地 Unix 域套接字文件扩展名。默认值取自
PGPORT环境变量(如果已设置),否则使用编译时的默认值。-Uuser--username=#user用于连接的用户名。默认为当前操作系统用户名。
-w--no-password#绝不提示输入密码。如果服务器要求密码认证,而密码又无法通过
.pgpass文件等其他方式获得,则连接尝试将失败。此选项适用于批处理作业和脚本,因为在这些场景中没有用户在场输入密码。-W--password#强制 pg_recvlogical 在连接数据库之前提示输入密码。
这个选项并非必不可少,因为如果服务器要求密码认证,pg_recvlogical 会自动提示输入密码。不过,pg_recvlogical 需要先浪费一次连接尝试,才能发现服务器需要密码。在某些情况下,使用
-W来避免这次额外的连接尝试是值得的。
还可以使用下列附加选项:
退出状态
当收到 SIGINT 或 SIGTERM 信号终止时,pg_recvlogical 会以状态 0 退出。(这是其正常结束方式,因此不视为错误。)遇到致命错误或其他信号时,退出状态为非零。
环境
与大多数其他 PostgreSQL 工具一样,此工具也使用 libpq 支持的环境变量(见第 34.15 节)。
环境变量 PG_COLOR 指定是否在诊断消息中使用颜色。可能的值为 always、auto 和 never。
注解
如果源集簇启用了组权限,pg_recvlogical 会在输出文件上保留这些组权限。
示例
示例请参见第 49.1 节。
报告文档问题
阅读 上游文档. 通过 PostgreSQL 文档反馈表单.