Redrock Postgres 搜索 英文
版本: 9.3 / 9.4 / 9.5 / 9.6 / 10 / 11 / 12 / 13 / 14 / 15 / 16 / 17

53.4. 流复制协议 #

要启动流复制,前端在启动消息中发送 replication 参数。值为 true(或 onyes1)的布尔值指示后端进入物理复制 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)

连接至的数据库,或 null。

SHOW name #

要求服务器发送运行时参数的当前设置。它与 SQL 命令 SHOW 类似。

name

运行时参数的名称。可用参数在 第 19 章 中有说明。

TIMELINE_HISTORY tli #

要求服务器发送时间线 tli 的时间线历史文件。服务器使用包含两个字段的单行结果集进行回复。尽管字段标记为 text,但它们实际上返回原始字节,不进行任何编码转换

filename (文本)

时间线历史文件的文件名,例如 00000002.history

content (文本)

时间线历史文件的内容。

CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL | LOGICAL output_plugin } [ ( option [, ...] ) ] #

创建物理或逻辑复制槽。有关复制槽的更多信息,请参阅 第 26.2.6 节

slot_name

要创建的槽的名称。必须是有效复制槽名称(请参阅 第 26.2.6.1 节)。

output_plugin

用于逻辑解码的输出插件的名称(请参阅 第 47.6 节)。

TEMPORARY

指定此复制槽为临时槽。临时槽不会保存到磁盘中,在出现错误时或会话结束时将自动删除。

支持下列选项

TWO_PHASE [ boolean ]

如果为 true,此逻辑复制槽支持解码两阶段提交。通过此选项,会解码和传输有关两阶段提交的命令,如 PREPARE TRANSACTIONCOMMIT PREPAREDROLLBACK PREPARED。将在 PREPARE TRANSACTION 时解码和传输事务。默认值为 false。

RESERVE_WAL [ boolean ]

如果为 true,此物理复制槽立即保留WAL。否则,仅在流复制客户端连接时保留。WAL默认值为 false。

SNAPSHOT { 'export' | 'use' | 'nothing' }

决定在逻辑槽初始化期间创建的快照所执行的操作。默认为 'export',这会导出快照以供其他会话使用。无法在事务中使用此选项。 'use' 将使用快照供执行该命令的当前事务所用。此选项必须在事务中使用,并且 CREATE_REPLICATION_SLOT 必须是该事务中运行的第一个命令。最后,'nothing' 只会将快照用于逻辑解码,而不会执行其他操作。

FAILOVER [ boolean ]

如果为 true,则该槽位已启用,可以与备用服务器同步,以便在故障转移后恢复逻辑复制。默认设置为 false。

服务器响应此命令后,会发送包含以下字段的一行结果集

slot_name (text)

新创建的复制槽位名称。

consistent_point (text)

槽位变得一致的 WAL 位置。这是可以在此复制槽位上启动流的 earliest 位置。

snapshot_name (text)

命令导出的快照的标识符。快照在对该连接执行新的命令或者复制连接关闭之前有效。如果创建的槽位为物理槽位,则为 Null。

output_plugin (text)

新创建的复制槽位使用的输出插件的名称。如果创建的槽位为物理槽位,则为 Null。

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 [, ...] ) #

更改复制槽位的定义。有关复制槽位的更多信息,请参见 第 26.2.6 节。此命令当前仅支持逻辑复制槽位。

slot_name

要修改的槽位名称。必须是有效的复制槽位名称(请参见 第 26.2.6.1 节)。

支持以下选项

FAILOVER [ boolean ]

如果为 true,则该槽位已启用,可以与备用服务器同步,以便在故障转移后恢复逻辑复制。

READ_REPLICATION_SLOT slot_name #

读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含 NULL 值的元组。目前,此命令仅支持物理复制槽。

为了响应此命令,服务器将返回一个包含以下字段的一行结果集

slot_type (text)

复制槽的类型,可能是 physicalNULL

restart_lsn (text)

复制槽的 restart_lsn

restart_tli (int8)

根据当前时间线历史记录,与 restart_lsn 关联的时间线 ID。

START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] #

指示服务器从 WAL 位置 XXX/XXX 开始流式传输 WAL。如果指定 TIMELINE 选项,则从时间线 tli 开始流式传输;否则,选择服务器的当前时间线。服务器可能会回复一个错误,例如,如果 WAL 的请求部分已回收利用。成功后,服务器使用一个 CopyBothResponse 消息进行响应,然后开始将 WAL 流式传输到前端。

如果 slots 名称是通过 slot_name 提供的,则它会在复制过程进行时进行更新,以便服务器知道备用仍然需要哪些 WAL 段,并且如果 hot_standby_feedback 打开,还需知道哪些事务。

如果客户端请求的时间线不是最新的时间线,但它属于服务器历史的一部分,那么服务器会从请求的起始点开始流式传输该时间线上的所有 WAL,直到服务器切换到另一时间线。如果客户端请求完全在旧时间线的末尾进行流式传输,那么服务器会完全跳过复制模式。

在对非最新时间轴上的所有 WAL 进行流式处理后,服务器将退出 COPY 模式来结束流式处理。当客户端也通过退出 COPY 模式来确认此操作时,服务器会发送一个只有一行和两列的结果集,指示此服务器历史记录中的下一个时间轴。第一列是下一个时间轴的 ID(类型 int8),第二列是发生切换的 WAL 位置(类型 text)。通常,切换位置是进行流式处理的 WAL 的结尾,但有时当服务器对自己提升之前尚未回放过的旧时间轴上的某些 WAL 发送流时,会发生特殊情况。最后,服务器会发送两条 CommandComplete 消息(一条结束 CopyData,另一条结束 START_REPLICATION 命令),此时服务器已准备好接收一条新命令。

WAL 数据作为一系列 CopyData 消息发送;有关详细信息,请参见 第 53.6 节第 53.7 节。(这允许混合其他信息;特别是当服务器在开始流式处理后遇到故障时,服务器可以发送 ErrorResponse 消息。)从服务器到客户端的每个 CopyData 消息的有效负载包含使用以下格式之一编写的消息

XLogData (B) #
Byte1('w')

将消息标识为 WAL 数据。

Int64

此消息中 WAL 数据的起点。

Int64

服务器上当前的 WAL 结束。

Int64

服务器在传输时的系统时钟,以 2000-01-01 上午 12 点后的微秒为单位。

Byten

WAL 数据流的一个部分。

单个 WAL 记录永远不会拆分到两条 XLogData 消息中。当 WAL 记录跨 WAL 页面边界时,并且已经使用延续记录拆分时,可以将其拆分成页面边界。换言之,第一个主 WAL 记录及其延续记录可以在不同的 XLogData 消息中发送。

主服务器保持活动消息 (B) #
Byte1('k')

将消息标识为发件方保持活动。

Int64

服务器上当前的 WAL 结束。

Int64

服务器在传输时的系统时钟,以 2000-01-01 上午 12 点后的微秒为单位。

Byte1

1 表示客户端应尽快回复此消息,以避免超时断开连接。否则为 0。

接收进程可以使用以下一种消息格式(也是 CopyData 消息的有效负载中)随时向发件方发送回复

备用状态更新 (F) #
Byte1('r')

将消息识别为接收器状态更新。

Int64

备用数据库中接收并写入磁盘的最后一个 WAL 字节 + 1 的位置。

Int64

备用数据库中刷新到磁盘的最后一个 WAL 字节 + 1 的位置。

Int64

备用数据库中应用的最后一个 WAL 字节 + 1 的位置。

Int64

传输时客户端系统时钟,以自 2000-01-01 午夜起经过的微秒数表示。

Byte1

如果为 1,客户端请求服务器立即回复此消息。这可用于 ping 服务器,以测试连接是否仍然正常。

热备用反馈消息 (F) #
Byte1('h')

将消息识别为热备用反馈消息。

Int64

传输时客户端系统时钟,以自 2000-01-01 午夜起经过的微秒数表示。

Int32

备用数据库的当前全局 xmin,不包括来自任何复制槽中的 catalog_xmin。如果此值和下面的 catalog_xmin 同时为 0,这将被视为通知,表示在此连接中将不再发送热备用反馈。后面的非零消息可能重新启动反馈机制。

Int32

备用数据库上的全局 xmin xid 的历元。

Int32

备用数据库上任何复制槽的最低 catalog_xmin。如果没有 catalog_xmin 存在于备用数据库中,或如果热备用反馈处于禁用状态,则设为 0。

Int32

备用数据库上的 catalog_xmin xid 的历元。

START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ] #

指示服务器开始为逻辑复制流式传输 WAL,从 WAL 位置 XXX/XXX 或槽的 confirmed_flush_lsn 开始(请参见 第 52.19 节),以较大者为准。这种行为可以让客户端更轻松地避免在没有数据要处理时更新其本地 LSN 状态。但是,从请求的 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

传递给槽逻辑解码输出插件的选项的名称。请参阅 第 53.5 节,了解标准 (pgoutput) 插件接受的选项。

option_value

以字符串常量的形式表示与指定选项关联的可选值。

DROP_REPLICATION_SLOT slot_name [ WAIT ] #

删除复制槽,释放任何保留的服务器端资源。如果该槽是创建于 walsender 所连接的数据库之外的逻辑槽,则此命令将失败。

slot_name

要删除的槽的名称。

WAIT

此选项将导致该命令在槽处于活动状态时一直等待,直到该槽变为非活动状态,而不是引发错误的默认行为。

UPLOAD_MANIFEST #

上传备份清单,以为进行增量备份做准备。

BASE_BACKUP [ ( option [, ...] ) ] #

指示服务器开始传输基本备份。在备份开始之前,系统将自动进入备份模式,并在备份完成时退出该模式。接受以下选项

LABEL 'label'

设置备份的标签。如果未指定,则将使用 基本备份 的备份标签。该标签的引用规则与已启用 standard_conforming_strings 的标准 SQL 字符串相同。

TARGET 'target'

指示服务器将备份发送到何处。如果目标是 client(这是默认设置),则备份数据将发送到客户端。如果目标是 server,则备份数据将写入服务器中由 TARGET_DETAIL 选项指定的路径名。如果目标是 blackhole,则备份数据不会发送到任何地方;它会被简单丢弃。

server 目标需要超级用户权限,或授予 pg_write_server_files 角色。

TARGET_DETAIL 'detail'

提供有关备份目标的其他信息。

目前,只有当备份目标是 server 时,才能使用此选项。它指定应将备份写入到的服务器目录。

PROGRESS [ boolean ]

如果设为 true,则请求生成进度报告所需的信息。这将在每个表空间的标头中回发一个近似大小,可用于计算流已完成的进度。这是通过在传输甚至尚未开始之前先枚举所有文件大小一次来计算的,因此可能会对性能产生负面影响。尤其是,在流化第一个数据之前可能需要更长的时间。由于数据库文件可以在备份期间更改,因此大小仅是近似的,并且可能会在估计时间和发送实际文件之间增长和缩小。默认情况下为 false。

CHECKPOINT { 'fast' | 'spread' }

设置在基本备份开始时执行的检查点类型。默认值为 spread

WAL [ boolean ]

如果设为 true,则在备份中包含必要的 WAL 段。这将包括基本目录 tar 文件的 pg_wal 目录中备份开始和结束之间的所有文件。默认情况下为 false。

WAIT [ boolean ]

如果设为 true,则备份将等到最后一个所需的 WAL 段被存档,或在未启用 WAL 存档时发出警告。如果为 false,则备份既不会等待也不会发出警告,让客户端负责确保所需的日志可用。默认情况下为 true。

COMPRESSION 'method'

指示服务器使用指定的方法压缩备份。当前,支持的方法为 gziplz4zstd

COMPRESSION_DETAIL detail

指定所选压缩方法的详细信息。这应该只与 COMPRESSION 选项结合使用。如果该值为整数,则指定压缩级别。否则,它应该是一个用逗号分隔的项列表,每一个项都采用形式 keywordkeyword=value。当前,支持的关键字有 levellongworkers

level 关键字设置压缩级别。对于 gzip,压缩级别应为 19 之间的整数(默认 Z_DEFAULT_COMPRESSION-1),对于 lz4,压缩级别应为 1 到 12 之间的整数(默认 0,指快速压缩模式),而对于 zstd,压缩级别应为 ZSTD_minCLevel()(通常为 -131072)到 ZSTD_maxCLevel()(通常为 22)之间的整数(默认 ZSTD_CLEVEL_DEFAULT3)。

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

当此选项指定值为 yesforce-encode 时,将创建备份清单并随备份一起发送。清单是不包括任何可能包含的 WAL 文件在内的备份中存在的每个文件的列表。它还存储每个文件的大小、上次修改时间和一个校验和(可选)。force-encode 值强制对所有文件名进行十六进制编码;否则,仅对名称为非 UTF8 八位字节序列的文件执行此类型编码。force-encode 主要用于测试目的,以确保读取备份清单的客户端能够处理此情况。为了与以前的版本兼容,默认值为 MANIFEST 'no'

MANIFEST_CHECKSUMS checksum_algorithm

指定将应用到备份清单中每个文件中的校验和算法。当前可用的算法有 NONECRC32CSHA224SHA256SHA384SHA512。默认值为 CRC32C

INCREMENTAL

请求增量备份。在使用此选项运行基本备份之前,必须执行 UPLOAD_MANIFEST 命令。

开始备份时,服务器会先发送两个普通结果集,然后再发送一个或多个 CopyOutResponse 结果。

第一个普通结果集包含备份的起始位置,共一行两列。第一列包含以 XLogRecPtr 格式给出的起始位置,第二列包含相应的 timeline ID。

第二个普通结果集为每个表空间分别有一行。此行中的字段为

spcoid (oid)

表空间的 OID,或 null(如果是基本目录)。

spclocation (text)

表空间目录的完整路径,或 null(如果是基本目录)。

size (int8)

表空间的近似大小,单位为 KB(1024 字节),如果请求了进度报告;否则为 null。

在第二个普通结果集之后,将发送一个 CopyOutResponse。每个 CopyData 消息的负载都将包含以下某种格式的消息

新归档文件 (B)
Byte1('n')

标识消息表示新归档文件的开头。将对主数据目录创建一个归档文件,对每个其他表空间创建一个归档文件;每个文件都将使用 tar 格式(遵循 POSIX 1003.1-2008 标准中指定的“ustar 交换格式”)。

String

此归档文件的文件名。

String

对于主数据目录,则为空字符串。对于其他表空间,则为创建此归档文件的目录的完整路径。

清单 (B)
Byte1('m')

标识消息表示备份清单的开头。

归档文件或清单数据 (B)
Byte1('d')

标识此消息包含归档文件或清单数据。

Byten

数据字节。

进度报告 (B)
Byte1('p')

标识消息为进度报告。

Int64

已处理完的当前表空间的字节数。

在发送完 CopyOutResponse 或所有此类响应之后,将发送一个最终的普通结果集,其中包含备份的 WAL 结束位置,其格式与起始位置相同。

数据目录和各个表空间的 tar 存档将包含目录中的所有文件,无论它们是 PostgreSQL 文件还是添加到相同目录的其他文件。唯一排除的文件是

  • postmaster.pid

  • postmaster.opts

  • pg_internal.init(位于多个目录中)

  • PostgreSQL 服务器操作期间创建的各种临时文件和目录,例如以 pgsql_tmp 和临时关系开头的任何文件或目录。

  • 未记录的关系,但 recovery 中重新创建(空)未记录的关系需要的 init 分支除外。

  • pg_wal,包括子目录。如果包含 WAL 文件运行备份,将包括 pg_wal 的综合版本,但它只包含备份正常工作所需的文件,而不包含其余内容。

  • pg_dynshmempg_notifypg_replslotpg_serialpg_snapshotspg_stat_tmppg_subtrans 作为空目录复制(即使它们是符号链接)。

  • 常规文件和目录之外的文件,例如符号链接(上面列出的目录除外)和特殊设备和操作系统文件将跳过。(pg_tblspc 中的符号链接将保留。)

如果服务器上的底层文件系统支持,将设置所有者、组和文件模式。

在上述所有命令中,指定类型为 boolean 的参数时,可以省略 value 部分,这等效于指定 TRUE