要启动流复制,前端在启动消息中发送replication参数。布尔值true (或on、yes、1)告诉后端进入物理复制 walsender 模式,在此模式下,可以发出下面列出的一小组复制命令,而不是 SQL 语句。
将database作为replication参数的值传递给后端, 指示其进入逻辑复制 walsender 模式,并连接到dbname参数中指定的数据库。 在逻辑复制 walsender 模式下,可以发出下文所示的复制命令以及普通 SQL 命令。
无论是物理复制还是逻辑复制的 walsender 模式,都只能使用简单查询协议。
为了测试复制命令,可以通过psql或任何其他使用连接字符串且包含replication选项的libpq工具建立复制连接, 例如:
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
然而,更常用的是使用pg_receivewal(用于物理复制)或pg_recvlogical(用于逻辑复制)。
复制命令在服务器日志中记录,当启用log_replication_commands时。
复制模式中接受的命令包括:
IDENTIFY_SYSTEM #请求服务器标识自身。服务器会返回一个包含四个字段的单行结果集:
SHOW name #请求服务器发送运行时参数的当前设置。这类似于SQL命令SHOW。
name #一个运行时参数的名称。可用参数在Chapter 19中有文档记录。
TIMELINE_HISTORY tli #请求服务器发送时间线历史文件以获取时间线tli。 服务器回复一行结果集,包含两个字段。虽然这些字段被标记为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 ] #如果为 true,则该逻辑复制槽支持两阶段提交的解码。使用此选项后,与两阶段提交相关的命令,如 PREPARE TRANSACTION,COMMIT PREPARED 和ROLLBACK PREPARED将被解码和传输。 事务将在PREPARE TRANSACTION时解码和传输。 默认值为false。
FAILOVER [ boolean ] #若为 true,则该复制槽会同步到备用库,从而在故障切换后恢复逻辑复制。默认值为 false。
RESERVE_WAL [ boolean ] #如果为 true,则该物理复制槽会立即保留WAL。 否则,WAL仅在从流复制客户端连接时保留。 默认值为false。
SNAPSHOT { 'export' | 'use' | 'nothing' } #决定在逻辑复制槽初始化期间如何处理所创建的快照。'export' 这是默认选项,将导出快照供其他会话使用。此选项不能在事务内使用。 'use'将为执行命令的当前事务使用快照。此选项必须在事务中使用, 并且CREATE_REPLICATION_SLOT必须是在该事务中运行的第一个命令。 最后,'nothing'将像往常一样仅用于逻辑解码使用快照,但不会执行其他操作。
在响应此命令时,服务器将发送一个包含以下字段的单行结果集:
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 ] #若为 true,则该逻辑复制槽支持两阶段提交解码。与两阶段提交相关的命令(如 PREPARE TRANSACTION、COMMIT PREPARED、ROLLBACK PREPARED)会被解码并发送;事务在 PREPARE TRANSACTION 时解码并发送。
FAILOVER [ boolean ] #若为 true,则该复制槽会同步到备用库,从而在故障切换后恢复逻辑复制。
READ_REPLICATION_SLOT slot_name #读取与复制槽相关的一些信息。如果复制槽不存在,则返回一个包含NULL值的元组。 当前仅支持物理复制槽的此命令。
在响应此命令时,服务器将返回一个包含以下字段的单行结果集:
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 时,哪些事务 仍然被备库所需要。
如果客户端请求的 timeline 不是最新的,但属于服务器历史的一部分,服务器会从请求的起点开始流传输该 timeline 上的全部 WAL,直到服务器切换到另一个 timeline 的位置为止。如果客户端请求的位置正好是旧 timeline 的末尾,服务器将完全跳过 COPY 模式。
在非最新时间线上流传输完全部 WAL 后,服务器会通过退出 COPY 模式来结束流传输。当客户端也通过退出 COPY 模式来确认时,服务器会发送一个包含一行两列的结果集,指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID(类型为 int8),第二列是发生切换的 WAL 位置(类型为 text)。通常,切换位置就是所流传输 WAL 的末尾,但也存在一些边界情况,服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后,服务器会发送两个 CommandComplete 消息(一个结束 CopyData,另一个结束 START_REPLICATION 本身),然后准备接受新的命令。
WAL 数据会作为一系列 CopyData 消息发送;详见 Section 54.6 与 Section 54.7。(这使其他信息可与之交错发送;特别是服务器在开始流传输后若遇到失败,仍可发送 ErrorResponse。)从服务器到客户端的每个 CopyData 消息负载都属于以下格式之一:
接收进程可以随时使用以下某种消息格式向发送方回传响应(同样放在 CopyData 消息的负载中):
将该消息标识为热备反馈消息。
客户端在传输时的系统时钟,以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 #要从中流传输更改的复制槽名称。该参数是必需的,并且必须对应于使用 CREATE_REPLICATION_SLOT 在 LOGICAL 模式下创建的现有逻辑复制槽。
XXX/XXX #开始流式传输的WAL位置。
option_name #传递给复制槽逻辑解码输出插件的选项名称。请参阅Section 54.5, 了解标准(pgoutput)插件接受的选项。
option_value #指定选项相关的可选值,以字符串常量的形式表示。
DROP_REPLICATION_SLOT slot_name [ WAIT ] #删除复制槽,释放任何保留的服务器端资源。
UPLOAD_MANIFEST #上传备份清单(backup 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,则请求生成进度报告所需的信息。这将在每个表空间的头部发送一个近似大小, 可用于计算流的进度。这是通过在传输开始之前先枚举所有文件大小来计算的, 可能会对性能产生负面影响。特别是,在流式传输数据之前可能需要更长的时间。 由于备份期间数据库文件可能会发生变化,因此大小仅为近似值, 在近似值和实际文件发送之间可能会增长或缩小。默认值为false。
CHECKPOINT { 'fast' | 'spread' } #设置在基本备份开始时执行的检查点类型。默认值为spread。
WAL [ boolean ] #如果设置为true,则在备份中包含必要的WAL段。这将包括在开始和停止备份之间的所有文件在基本目录tar文件的pg_wal目录中。默认值为false。
WAIT [ boolean ] #如果设置为 true,备份会等待直到最后一个所需 WAL 段已归档;若未启用 WAL 归档则发出警告。 如果设置为 false,备份既不等待也不警告,而由客户端负责确保所需 WAL 可用。 默认值为true。
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 ] #如果为true,则在名为tablespace_map的文件中包含目录pg_tblspc中存在的符号链接的信息。 表空间映射文件包括目录pg_tblspc/中每个符号链接的名称及该符号链接的完整路径。默认值为false。
VERIFY_CHECKSUMS [ boolean ] #如果为true,则在进行基本备份时验证校验和(如果已启用)。如果为false,则跳过此步骤。默认值为true。
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。
第二个普通结果集中的每个表空间都有一行。 这一行中的字段是:
在第二个常规结果集之后,将发送一个CopyOutResponse。 每个CopyData消息的有效负载将包含以下格式之一的消息:
在发送了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中的符号链接将被保留。)
如果服务器上的底层文件系统支持,将设置所有者、组和文件模式。
如果您发现文档中有不正确的内容、与您使用特定功能的经验不符或需要进一步说明,请使用此表单来报告文档问题。