要发起流复制,前端会在启动消息中发送
replication 参数。布尔值
true(或 on、
yes、1)
会告诉后端进入物理复制的 walsender 模式,
在这种模式下可以发出下文展示的少量复制命令来代替 SQL 语句。
把 database 作为
replication 参数的值传入,
会指示后端进入逻辑复制的 walsender 模式,
并连接到 dbname 参数中指定的数据库。
在逻辑复制的 walsender 模式中,既可以发出下文展示的复制命令,
也可以发出普通的 SQL 命令。
在物理复制或逻辑复制的 walsender 模式中, 都只能使用简单查询协议。
为了测试复制命令,你可以通过 psql
或任何其他使用 libpq 的工具
发起一条复制连接,连接串中包含
replication 选项,例如:
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
不过,使用 pg_receivewal(用于物理复制)或 pg_recvlogical(用于逻辑复制) 通常更为实用。
当启用了 log_replication_commands 时, 复制命令会被记录到服务器日志中。
复制模式下接受的命令有:
IDENTIFY_SYSTEM
#请求服务器标识自己。服务器以一个单行结果集响应, 其中包含四个字段:
systemid (text)标识该集群的唯一系统标识符。它可以用来检查用于初始化 后备服务器的基础备份是否来自同一个集群。
timeline (int8)当前时间线 ID。对于检查后备服务器与主服务器是否一致也有用。
xlogpos (text)当前的 WAL 刷新位置。可用于得到写前日志中一个 可以开始流式传输的已知位置。
dbname (text)连接到的数据库;如果没有则为空。
SHOW name
#请求服务器发送一个运行时参数的当前设置。 这类似于 SQL 命令 SHOW。
name一个运行时参数的名称。可用参数记录在 Chapter 19 中。
TIMELINE_HISTORY tli
#
请求服务器发送时间线
tli 的时间线历史文件。
服务器以一个单行结果集响应,其中包含两个字段。
虽然这些字段被标为 text 类型,
但它们实际上返回的是原始字节,没有做任何编码转换:
filename (text)
时间线历史文件的文件名,例如
00000002.history。
content (text)时间线历史文件的内容。
CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL | LOGICAL output_plugin } [ ( option [, ...] ) ]
#创建一个物理或逻辑复制槽。关于复制槽的更多信息见 Section 26.2.6。
slot_name要创建的槽的名字。必须是一个有效的复制槽名称 (见 Section 26.2.6.1)。
output_plugin用于逻辑解码的输出插件的名称 (见 Section 47.6)。
TEMPORARY指明该复制槽是一个临时槽。临时槽不会保存到磁盘, 在出错或会话结束时会自动被删除。
支持以下选项:
TWO_PHASE [ boolean ]
如果为真,此逻辑复制槽支持两阶段提交的解码。
使用此选项时,与两阶段提交相关的命令
(如 PREPARE TRANSACTION、
COMMIT PREPARED
和 ROLLBACK PREPARED)
会被解码并传输。事务将在
PREPARE TRANSACTION 时刻被解码并传输。
默认值为假。
RESERVE_WAL [ boolean ]如果为真,该物理复制槽会立即保留 WAL。 否则,只有在来自流复制客户端的连接建立时才会保留 WAL。 默认值为假。
SNAPSHOT { 'export' | 'use' | 'nothing' }
决定如何处理逻辑槽初始化期间创建的快照。
'export' 是默认值,
会导出该快照以供其他会话使用。此选项不能在事务内使用。
'use' 会把该快照用于执行该命令的
当前事务。此选项必须在事务内使用,并且
CREATE_REPLICATION_SLOT 必须是
该事务中运行的第一条命令。最后,'nothing'
只会把该快照照常用于逻辑解码,不会用它做任何其他事情。
FAILOVER [ boolean ]如果为真,该槽会被启用以同步到后备服务器, 这样在故障转移之后逻辑复制就可以继续进行。 默认值为假。
作为对该命令的响应,服务器将发送一个包含以下字段的 单行结果集:
slot_name (text)新创建的复制槽的名字。
consistent_point (text)该槽达到一致性的 WAL 位置。这是在此复制槽上 可以开始流式传输的最早位置。
snapshot_name (text)该命令导出的快照的标识符。该快照在此连接上执行新命令之前 或复制连接关闭之前一直有效。如果创建的是物理槽则为空。
output_plugin (text)新创建的复制槽所使用的输出插件的名称。 如果创建的是物理槽则为空。
CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] }
#
为了与更早的版本兼容,
仍然支持 CREATE_REPLICATION_SLOT 命令的
这种替代语法。
ALTER_REPLICATION_SLOT slot_name ( option [, ...] )
#更改复制槽的定义。 关于复制槽的更多信息见 Section 26.2.6。此命令目前 只支持逻辑复制槽。
slot_name要更改的槽的名字。必须是一个有效的复制槽名称 (见 Section 26.2.6.1)。
支持以下选项:
TWO_PHASE [ boolean ]
如果为真,此逻辑复制槽支持两阶段提交的解码。
使用此选项时,与两阶段提交相关的命令
(如 PREPARE TRANSACTION、
COMMIT PREPARED
和 ROLLBACK PREPARED)
会被解码并传输。事务将在
PREPARE TRANSACTION 时刻被解码并传输。
FAILOVER [ boolean ]如果为真,该槽会被启用以同步到后备服务器, 这样在故障转移之后逻辑复制就可以继续进行。
READ_REPLICATION_SLOT slot_name
#
读取与复制槽关联的一些信息。如果该复制槽不存在,
则返回一个带 NULL 值的元组。
此命令目前只支持物理复制槽。
作为对该命令的响应,服务器将返回一个单行结果集, 其中包含以下字段:
slot_type (text)
该复制槽的类型,是 physical 还是
NULL。
restart_lsn (text)
The replication slot's restart_lsn.
restart_tli (int8)
与 restart_lsn 关联的时间线 ID,
沿当前时间线历史。
START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ]
#
指示服务器开始流式传输 WAL,起点为 WAL 位置
XXX/XXX。
如果指定了 TIMELINE 选项,
流式传输将从时间线 tli
开始;否则会选择服务器的当前时间线。
服务器可以以一个错误来回应,例如所请求的 WAL 区段
已经被回收。成功时,服务器会以一条 CopyBothResponse 消息响应,
然后开始把 WAL 流式传输给前端。
如果通过 slot_name
提供了槽的名字,它会随着复制的进行被更新,
这样服务器就能知道后备服务器还需要哪些 WAL 段,
以及在 hot_standby_feedback 打开时
还需要哪些事务。
如果客户端请求的时间线不是最新的、但属于服务器历史的一部分, 服务器将流式传输该时间线上从请求的起点开始、 直到服务器切换到另一条时间线之处为止的所有 WAL。 如果客户端请求在旧时间线的结尾处开始流式传输, 服务器会完全跳过 COPY 模式。
在流式传输完一条非最新时间线上的所有 WAL 之后,
服务器会通过退出 COPY 模式来结束流式传输。
当客户端也退出 COPY 模式以示确认时,
服务器会发送一个带有一行两列的结果集,
指示该服务器历史中的下一条时间线。
第一列是下一条时间线的 ID(类型 int8),
第二列是发生切换时的 WAL 位置(类型 text)。
通常切换位置就是已被流式传输的 WAL 的末尾,
但也存在一些边界情况,服务器可能会发送一些来自旧时间线、
而它在提升之前自身还没有重放过的 WAL。
最后,服务器会发送两条 CommandComplete 消息
(一条结束 CopyData,另一条结束
START_REPLICATION 本身),
并准备好接受一条新命令。
WAL 数据以一系列 CopyData 消息的形式发送; 详情见 Section 54.6 和 Section 54.7。 (这允许把其他信息混入其中;特别是, 服务器在开始流式传输之后遇到失败时可以发送一条 ErrorResponse 消息。)从服务器发送到客户端的每条 CopyData 消息的载荷中包含以下格式之一的消息:
把该消息标识为 WAL 数据。
该消息中 WAL 数据的起始位置。
服务器上 WAL 的当前末尾。
发送时服务器的系统时钟,以自 2000-01-01 午夜以来的 微秒数表示。
nWAL 数据流的一个区段。
一条 WAL 记录绝不会跨越两条 XLogData 消息。 当一条 WAL 记录跨过 WAL 页边界(因此已经用延续记录拆分)时, 它可以在页边界处被拆分。换句话说, WAL 主记录及其延续记录可以用不同的 XLogData 消息发送。
把该消息标识为发送方保活(keepalive)消息。
服务器上 WAL 的当前末尾。
发送时服务器的系统时钟,以自 2000-01-01 午夜以来的 微秒数表示。
1 表示客户端应当尽快回复这条消息,以避免因超时而断开连接。 否则为 0。
接收方进程可以在任何时候使用以下消息格式之一 向发送方回送应答(同样在 CopyData 消息的载荷中):
把该消息标识为接收方状态更新。
后备服务器上已收到并写入磁盘的最后一个 WAL 字节 的位置 + 1。
后备服务器上已刷写到磁盘的最后一个 WAL 字节 的位置 + 1。
后备服务器上已应用的最后一个 WAL 字节的位置 + 1。
发送时客户端的系统时钟,以自 2000-01-01 午夜以来的 微秒数表示。
如果为 1,客户端请求服务器立即回复这条消息。 这可以用于 ping 服务器,测试连接是否仍然健康。
把该消息标识为一条热后备反馈消息。
发送时客户端的系统时钟,以自 2000-01-01 午夜以来的 微秒数表示。
后备服务器当前的全局 xmin,
不包括任何复制槽的 catalog_xmin。
如果该值和后面的 catalog_xmin
都为 0,这将被视为一个通知,表示此连接上
将不再发送热后备反馈。之后的非零消息
可以重新发起反馈机制。
后备服务器上全局 xmin xid 的纪元。
后备服务器上任何复制槽的最低
catalog_xmin。
如果后备服务器上不存在 catalog_xmin
或者热后备反馈正被禁用,则设为 0。
后备服务器上 catalog_xmin xid 的纪元。
START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ] #
指示服务器开始为逻辑复制流式传输 WAL,起点是 WAL 位置
XXX/XXX 或该槽的
confirmed_flush_lsn(见 Section 53.20)中较大的那一个。
这种行为使客户端在没有数据要处理时可以更方便地避免
更新其本地的 LSN 状态。但是,
从一个不同于请求的 LSN 开始可能无法捕获某些类型的客户端错误;
因此在发出 START_REPLICATION 之前,
客户端可能希望检查 confirmed_flush_lsn
是否符合其预期。
服务器可以以一个错误来回应,例如该槽不存在。 成功时,服务器会以一条 CopyBothResponse 消息响应, 然后开始把 WAL 流式传输给前端。
CopyBothResponse 消息中的消息具有与为
START_REPLICATION ... PHYSICAL 所记载的相同的格式,
包括两条 CommandComplete 消息。
与所选槽关联的输出插件用于处理流式传输的输出。
SLOT slot_name
要从中流式传输更改的槽的名字。此参数是必需的,
并且必须对应于以 LOGICAL 模式通过
CREATE_REPLICATION_SLOT
创建的一个现有逻辑复制槽。
XXX/XXX开始流式传输的 WAL 位置。
option_name
传给该槽的逻辑解码输出插件的一个选项的名称。
关于标准(pgoutput)插件
接受的选项,见
Section 54.5。
option_value与指定选项关联的可选值,形式为一个字符串常量。
DROP_REPLICATION_SLOT slot_name [ WAIT ]
#删除一个复制槽,并释放所有被保留的服务器端资源。
slot_name要删除的槽的名字。
WAIT如果该槽是活动的,此选项会使命令等待它变为非活动状态, 而不是默认的报错行为。
UPLOAD_MANIFEST
#上传一个备份清单,为执行一次增量备份做准备。
BASE_BACKUP [ ( option [, ...] ) ]
#指示服务器开始流式传输一个基础备份。 系统会在备份开始之前自动进入备份模式, 并在备份完成时退出备份模式。接受以下选项:
LABEL 'label'
设置备份的标签。如果未指定,将使用
base backup 作为备份标签。
标签的引用规则与开启了
standard_conforming_strings
的标准 SQL 字符串相同。
TARGET 'target'
告诉服务器把备份发送到哪里。如果目标是
client(这是默认值),
备份数据将被发送到客户端。如果目标是
server,备份数据会被写到服务器上
TARGET_DETAIL 选项指定的路径。
如果目标是 blackhole,
备份数据不会被发送到任何地方;它只会被丢弃。
server 目标需要超级用户特权,
或者被授予 pg_write_server_files 角色。
TARGET_DETAIL 'detail'提供关于备份目标的额外信息。
目前,此选项只能在备份目标为
server 时使用。
它指定备份应当被写入的服务器目录。
PROGRESS [ boolean ]如果设为 true,请求生成进度报告所需的信息。 这会在每个表空间的头部回送一个近似大小, 可用于计算流的进行程度。它是通过在传输尚未开始之前 枚举所有文件的大小一次而计算的,因此可能对性能 造成负面影响。特别地,首批数据被流式传输之前 可能要等更长时间。由于数据库文件在备份期间可能变化, 该大小只是近似的,在估算时刻与实际发送文件的时刻之间 既可能变大也可能变小。 默认值为假。
CHECKPOINT { 'fast' | 'spread' }
设置在基础备份开始时执行的检查点类型。
默认值为 spread。
WAL [ boolean ]
如果设为 true,则在备份中包含必要的 WAL 段。
这会把基础目录 tar 文件中 pg_wal 目录里
备份起点与终点之间的所有文件都包含进来。
默认值为假。
WAIT [ boolean ]如果设为 true,备份将等待最后一个所需的 WAL 段被归档, 或者在 WAL 归档未启用时发出一条警告。 如果为假,备份既不等待也不警告, 把确保所需日志可用的责任留给客户端。 默认值为真。
COMPRESSION 'method'
指示服务器使用指定的方法压缩备份。
目前支持的方法有 gzip、
lz4 和 zstd。
COMPRESSION_DETAIL detail
指定所选压缩方法的细节。它只应与
COMPRESSION 选项配合使用。
如果该值是一个整数,它指定压缩级别。
否则,它应当是一个以逗号分隔的条目列表,
每个条目的形式为
keyword 或
keyword=value。目前支持的
关键字有 level、long
和 workers。
level 关键字设置压缩级别。
对于 gzip,压缩级别应当是
1 到 9 之间的整数
(默认 Z_DEFAULT_COMPRESSION 或
-1);
对于 lz4,是 1 到 12 之间的整数
(快速压缩模式默认为 0);
对于 zstd,是
ZSTD_minCLevel()(通常为 -131072)
到 ZSTD_maxCLevel()(通常为 22)
之间的整数
(默认 ZSTD_CLEVEL_DEFAULT 或
3)。
long 关键字启用长距离匹配模式,
以更高的内存占用为代价获得更高的压缩比。
长距离模式只为 zstd 支持。
workers 关键字设置应当用于并行压缩的
线程数。只有 zstd 支持并行压缩。
MAX_RATE rate限制(节流)单位时间内从服务器传输到客户端的 最大数据量。期望的单位是每秒千字节。 如果指定了此选项,该值必须等于零, 或落在 32 kB 到 1 GB(含)的范围内。 如果传入了零或未指定该选项,则对传输不做任何限制。
TABLESPACE_MAP [ boolean ]
如果为真,则把目录 pg_tblspc 中
存在的符号链接的信息包含进一个名为
tablespace_map 的文件中。
表空间映射文件包含
pg_tblspc/ 目录中存在的每个符号链接名,
以及该符号链接的完整路径。
默认值为假。
VERIFY_CHECKSUMS [ boolean ]如果为真,则在基础备份期间(如果启用了)会校验校验和。 如果为假,则跳过校验。默认值为真。
MANIFEST manifest_option
当此选项被指定为 yes
或 force-encode 时,
会创建一个备份清单并随备份一起发送。
该清单是备份中存在的每个文件的列表,
但可能包含的任何 WAL 文件除外。
它还存储每个文件的大小、最后修改时间,
以及可选的校验和。
值为 force-encode 会强制所有文件名
都进行十六进制编码;否则,仅对名称为非 UTF8 八位组序列的
文件执行这种编码。
force-encode 主要用于测试目的,
以确保读取备份清单的客户端能够处理这种情况。
为了与以前的版本兼容,默认值为
MANIFEST 'no'。
MANIFEST_CHECKSUMS checksum_algorithm
指定应当对备份清单中包含的每个文件应用的
校验和算法。目前可用的算法有
NONE、CRC32C、
SHA224、SHA256、
SHA384 和 SHA512。
默认值为 CRC32C。
INCREMENTAL
请求一次增量备份。
在使用此选项运行基础备份之前,
必须先执行 UPLOAD_MANIFEST 命令。
备份开始时,服务器会首先发送两个普通结果集, 后跟一个或多个 CopyOutResponse 结果。
第一个普通结果集包含备份的起始位置, 在带两列的单行中给出。第一列包含以 XLogRecPtr 格式 给出的起始位置,第二列包含对应的时间线 ID。
第二个普通结果集为每个表空间有一行。 该行中的字段有:
spcoid (oid)该表空间的 OID;如果它是基础目录则为空。
spclocation (text)该表空间目录的完整路径;如果它是基础目录则为空。
size (int8)该表空间的近似大小,以千字节(1024 字节)为单位; 如果已请求进度报告则有值,否则为空。
在第二个普通结果集之后,会发送一个 CopyOutResponse。 每条 CopyData 消息的载荷将包含以下格式之一的消息:
把该消息标识为新归档的开始标志。 主数据目录会有一个归档,每个额外的表空间也各有一个归档; 每个归档都使用 tar 格式 (遵循 POSIX 1003.1-2008 标准中规定的 “ustar 交换格式”)。
该归档的文件名。
对于主数据目录是一个空字符串。对于其他表空间, 则是创建该归档所用目录的完整路径。
把该消息标识为备份清单的开始标志。
把该消息标识为包含归档或清单数据。
nData bytes.
把该消息标识为一份进度报告。
当前表空间中已完成处理的字节数。
在 CopyOutResponse(或所有这些响应)被发送之后, 会发送一个最终的普通结果集,其中包含备份的 WAL 结束位置, 其格式与起始位置相同。
数据目录和每个表空间的 tar 归档将包含这些目录中的所有文件, 无论它们是 PostgreSQL 的文件 还是添加到同一目录中的其他文件。 唯一被排除的文件有:
postmaster.pid
postmaster.opts
pg_internal.init(在多个目录中都有发现)
PostgreSQL 服务器运行期间创建的各种临时文件和目录,
例如任何以 pgsql_tmp 开头的文件或目录,
以及临时关系。
非日志记录(unlogged)关系, 但恢复时重建(空的)非日志关系所需的 init fork 除外。
pg_wal,包括其子目录。如果备份运行时
包含了 WAL 文件,则会包含一个合成版本的
pg_wal,
但它只包含备份工作所必需的文件,不包含其余内容。
pg_dynshmem、pg_notify、
pg_replslot、pg_serial、
pg_snapshots、pg_stat_tmp
和
pg_subtrans 会被复制为空目录
(即使它们是符号链接)。
普通文件和目录之外的文件(例如符号链接
(上面列出的目录除外)以及特殊的设备和操作系统文件)
会被跳过。
(pg_tblspc 中的符号链接会被保留。)
如果服务器上的底层文件系统支持, 则会设置所有者、组和文件模式。
在上述所有命令中,
当指定 boolean 类型的参数时,
value 部分可以省略,
这等价于指定 TRUE。