52.4. 流复制协议 #
要启动流复制，前端在启动消息中发送 replication 参数。布尔值 true（或 on、yes、1）告诉后端进入物理复制
WAL 发送进程模式，在此模式下，可以发出下面列出的一小组复制命令，而不是 SQL 语句。
将 database 作为 replication 参数的值传递给后端，指示其进入逻辑复制 WAL 发送进程模式，并连接到 dbname 参数中指定的数据库。在逻辑复制 WAL 发送进程模式下，可以发出下文所示的复制命令以及普通 SQL 命令。
无论是物理复制还是逻辑复制的 WAL 发送进程模式，都只能使用简单查询协议。
为了测试复制命令，可以通过 psql 或其他使用 libpq 的工具建立复制连接，连接字符串中应包含 replication 选项，例如：
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
不过，通常更有用的做法是使用 pg_receivewal（用于物理复制）或 pg_recvlogical（用于逻辑复制）。
启用 log_replication_commands 后，复制命令会记录到服务器日志中。
复制模式接受以下命令：
IDENTIFY_SYSTEM请求服务器标识自身。服务器会返回一个包含四个字段的单行结果集：
-
systemid(text) 用于标识该集簇的唯一系统标识符。它可用于检查初始化备库所用的基础备份是否来自同一个集簇。
timeline(int4)当前时间线 ID。也可用于检查备库是否与主库一致。
-
xlogpos(text) 当前 WAL 刷盘位置。可用于获取预写式日志中一个已知的位置，以便从该处开始流式传输。
-
dbname(text) 当前连接到的数据库，或为 null。
-
SHOWname请求服务器发送运行时参数的当前设置。这类似于 SQL 命令 SHOW。
name一个运行时参数的名称。可用参数在第 19 章中有文档记录。
-
TIMELINE_HISTORYtli 请求服务器发送时间线
tli的时间线历史文件。服务器返回一个只有一行的结果集，包含两个字段。虽然这些字段被标记为text和bytea，它们实际返回的是原始字节，不进行转义或编码转换：filename(text)时间线历史文件的文件名，例如，
00000002.history。-
content(bytea) 时间线历史文件的内容。
CREATE_REPLICATION_SLOTslot_name[TEMPORARY] {PHYSICAL[RESERVE_WAL] |LOGICALoutput_plugin[EXPORT_SNAPSHOT|NOEXPORT_SNAPSHOT|USE_SNAPSHOT] } #创建一个物理或逻辑复制槽。查看第 26.2.6 节了解更多关于复制槽的信息。
slot_name要创建的复制槽名称。必须是合法的复制槽名称（参见第 26.2.6.1 节）。
output_plugin用于逻辑解码的输出插件的名称（参见第 48.6 节）。
TEMPORARY指定此复制槽为临时槽。临时槽不会保存到磁盘，并且在错误或会话结束时会自动删除。
RESERVE_WAL指定此物理复制槽立即保留 WAL。否则，只有在流复制客户端连接时才会保留 WAL。
EXPORT_SNAPSHOTNOEXPORT_SNAPSHOTUSE_SNAPSHOT决定如何处理初始化逻辑复制槽时创建的快照。默认选项
EXPORT_SNAPSHOT会导出快照供其他会话使用，此选项不能在事务内使用。USE_SNAPSHOT会将快照用于执行该命令的当前事务；此选项必须在事务内使用，且CREATE_REPLICATION_SLOT必须是该事务中执行的第一条命令。最后，NOEXPORT_SNAPSHOT只会像平常一样将快照用于逻辑解码，不会对其执行其他操作。
在响应此命令时，服务器将发送一个包含以下字段的单行结果集：
slot_name(text)新创建的复制槽的名称。
consistent_point(text)复制槽达到一致状态时的 WAL 位置。这是可从该复制槽开始流式传输的最早位置。
snapshot_name(text)该命令导出的快照标识符。该快照在此连接上执行下一条命令之前，或复制连接关闭之前有效。如果所创建的是物理复制槽，则为空值。
output_plugin(text)新建复制槽所使用的输出插件名称。如果所创建的是物理复制槽，则为空值。
-
START_REPLICATION[SLOTslot_name] [PHYSICAL]XXX/XXX[TIMELINEtli] 指示服务器从 WAL 位置
XXX/XXX开始流式传输 WAL。如果指定了TIMELINE选项，则从时间线tli开始传输；否则选择服务器当前的时间线。服务器可以返回错误，例如请求的 WAL 部分已被回收时。成功时，服务器返回 CopyBothResponse 消息，然后开始向前端流式传输 WAL。如果通过
slot_name提供了复制槽名称，该复制槽会随着复制的进行而更新，使服务器知道备库仍需要哪些 WAL 段，以及在启用hot_standby_feedback时仍需要哪些事务。如果客户端请求的时间线不是最新时间线，但属于服务器的历史，服务器会从请求的起点开始，流式传输该时间线上的所有 WAL，直到服务器切换到另一条时间线的位置。如果客户端请求的流式传输起点恰好位于旧时间线的末尾，服务器会立即返回 CommandComplete，而不进入 COPY 模式。
在非最新时间线上流式传输完全部 WAL 后，服务器会通过退出 COPY 模式来结束流式传输。当客户端也通过退出 COPY 模式来确认时，服务器会发送一个包含一行两列的结果集，指示该服务器历史中的下一条时间线。第一列是下一条时间线的 ID（类型为
int8），第二列是发生切换的 WAL 位置（类型为text）。通常，切换位置就是所流式传输 WAL 的末尾，但也存在一些边界情况，服务器可能会先发送一些自己在提升前尚未重放的旧时间线 WAL。最后，服务器会发送两个 CommandComplete 消息（一个结束 CopyData，另一个结束START_REPLICATION本身），然后准备接受新的命令。WAL 数据通过一系列 CopyData 消息发送。（这样可以混合发送其他信息；尤其是服务器在开始流式传输后遇到故障时，可以发送 ErrorResponse 消息。）服务器发给客户端的每条 CopyData 消息，其有效载荷都包含一条具有下列格式之一的消息：
- XLogData (B)
- Byte1('w')
将该消息标识为 WAL 数据。
- Int64
本消息中 WAL 数据的起始位置。
- Int64
服务器上当前的 WAL 末尾位置。
- Int64
发送消息时服务器的系统时钟，以自 2000-01-01 午夜以来的微秒数表示。
- Byte
n WAL 数据流的一个片段。
单条 WAL 记录绝不会被拆分到两条 XLogData 消息中。当 WAL 记录跨越 WAL 页边界，因而已经通过续接记录拆分时，可以在页边界处分开发送。换句话说，最初的主 WAL 记录及其续接记录可以在不同的 XLogData 消息中发送。
- 主库保活消息 (B)
- Byte1('k')
将该消息标识为发送端保活消息。
- Int64
服务器上当前的 WAL 末尾位置。
- Int64
发送消息时服务器的系统时钟，以自 2000-01-01 午夜以来的微秒数表示。
- Byte1
1 表示客户端应尽快回复此消息，以避免超时断开连接；否则为 0。
接收进程可以随时使用以下消息格式之一回复发送端（同样放在 CopyData 消息的有效载荷中）：
- 备库状态更新 (F)
- Byte1('r')
将该消息标识为接收端状态更新。
- Int64
备库已接收并写入磁盘的最后一个 WAL 字节的位置加 1。
- Int64
备库已刷盘的最后一个 WAL 字节的位置加 1。
- Int64
备库已应用的最后一个 WAL 字节的位置加 1。
- Int64
发送消息时客户端的系统时钟，以自 2000-01-01 午夜以来的微秒数表示。
- Byte1
如果为 1，表示客户端请求服务器立即回复此消息。可用它向服务器发送探测请求，以测试连接是否仍然正常。
- 热备反馈消息 (F)
- Byte1('h')
将该消息标识为热备反馈消息。
- Int64
发送消息时客户端的系统时钟，以自 2000-01-01 午夜以来的微秒数表示。
- Int32
备库当前的全局 xmin，不包括任何复制槽的 catalog_xmin。如果此值及后面的 catalog_xmin 都为 0，则视为通知服务器：此连接将不再发送热备反馈。之后的非零消息可以重新启动反馈机制。
- Int32
备库全局 xmin 事务 ID 的纪元。
- Int32
备库上所有复制槽中最小的 catalog_xmin。如果备库上不存在 catalog_xmin，或者正在禁用热备反馈，则设为 0。
- Int32
备库 catalog_xmin 事务 ID 的纪元。
-
START_REPLICATIONSLOTslot_nameLOGICALXXX/XXX[ (option_name[option_value] [, ...] ) ] 指示服务器开始为逻辑复制流式传输 WAL，起始 WAL 位置为
XXX/XXX。服务器可以返回错误，例如请求的 WAL 段已被回收。成功时，服务器会响应一条 CopyBothResponse 消息，然后开始向前端流式传输 WAL。CopyBothResponse 中承载的消息采用与
START_REPLICATION ... PHYSICAL文档中记载的相同格式，包括两个 CommandComplete 消息。与所选复制槽关联的输出插件将用于处理流式输出。
SLOTslot_name要从中流式传输更改的复制槽名称。该参数是必需的，并且必须对应于使用
CREATE_REPLICATION_SLOT在LOGICAL模式下创建的现有逻辑复制槽。XXX/XXX开始流式传输的 WAL 位置。
option_name传递给复制槽逻辑解码输出插件的选项名称。请参阅第 52.5 节，了解标准（
pgoutput）插件接受的选项。option_value指定选项相关的可选值，以字符串常量的形式表示。
-
DROP_REPLICATION_SLOTslot_name[WAIT] 删除复制槽，释放任何保留的服务器端资源。
slot_name要删除的复制槽名称。
WAIT该选项会让命令在复制槽处于活跃状态时等待，直到其变为非活跃，而不是按默认行为报错。
BASE_BACKUP[LABEL'label'] [PROGRESS] [FAST] [WAL] [NOWAIT] [MAX_RATErate] [TABLESPACE_MAP] [NOVERIFY_CHECKSUMS] [MANIFESTmanifest_option] [MANIFEST_CHECKSUMSchecksum_algorithm] #指示服务器开始流式传输基础备份。在备份开始之前，系统将自动进入备份模式，并在备份完成后退出备份模式。接受以下选项：
LABEL'label'设置备份标签。如果未指定，则使用
base backup作为备份标签。标签的引号规则与启用 standard_conforming_strings 时的标准 SQL 字符串相同。PROGRESS请求生成进度报告所需的信息。这将在每个表空间的首部发送一个近似大小，可用于计算流式传输的进度。这是通过在传输开始之前先枚举所有文件大小来计算的，可能会对性能产生负面影响。特别是，在流式传输数据之前可能需要更长的时间。由于备份期间数据库文件可能会发生变化，因此大小仅为近似值，在估算与实际发送文件之间的这段时间里可能会增长或缩小。
FAST请求快速检查点。
WAL在备份中包含必要的 WAL 段。这会把开始备份到停止备份之间的所有文件放入基础目录 tar 文件内的
pg_wal目录中。NOWAIT默认情况下，备份会等待最后一个必需的 WAL 段完成归档；如果未启用日志归档，则发出警告。指定
NOWAIT会同时禁用等待和警告，由客户端负责确保所需日志可用。MAX_RATErate限制（节流）每单位时间从服务器传输到客户端的最大数据量。预期的单位是每秒千字节。如果指定了此选项，则该值必须等于零，或者必须在 32 kB 到 1 GB（含）的范围内。如果传递零或未指定该选项，则不对传输施加任何限制。
TABLESPACE_MAP在名为
tablespace_map的文件中包含目录pg_tblspc中存在的符号链接的信息。表空间映射文件包括目录pg_tblspc/中每个符号链接的名称及该符号链接的完整路径。NOVERIFY_CHECKSUMS默认情况下，如果启用了校验和，基础备份期间就会验证校验和。指定
NOVERIFY_CHECKSUMS会禁用此项验证。MANIFESTmanifest_option当指定此选项的值为
yes或force-encode时，将创建一个备份清单并随备份一起发送。该清单是备份中每个文件的列表，除了可能包含的任何 WAL 文件。它还存储每个文件的大小、最后修改时间，以及可选的校验和。值为force-encode时会强制对所有文件名进行十六进制编码；否则，仅对文件名为非 UTF8 字节序列的文件执行此类型的编码。force-encode主要用于测试目的，以确保读取备份清单的客户端能够处理这种情况。为了与之前的版本兼容，默认值为MANIFEST 'no'。MANIFEST_CHECKSUMSchecksum_algorithm指定应用于备份清单中包含的每个文件的校验和算法。目前，可用的算法有
NONE、CRC32C、SHA224、SHA256、SHA384和SHA512。默认值为CRC32C。
备份开始时，服务器首先发送两个普通结果集，然后发送一个或多个 CopyResponse 结果。
第一个普通结果集包含备份的起始位置，在一个包含两列的单行中。第一列包含以 XLogRecPtr 格式给出的起始位置，第二列包含相应的时间线 ID。
第二个普通结果集中的每个表空间都有一行。这一行中的字段是：
spcoid(oid)表空间的 OID，如果是基础目录则为 null。
spclocation(text)表空间目录的完整路径，如果是基础目录则为 null。
size(int8)如果请求了进度报告，则为表空间的大致大小，以千字节（1024 字节）为单位；否则为 null。
第二个普通结果集之后，会发送一个或多个 CopyResponse 结果：主数据目录对应一个，除
pg_default和pg_global之外的每个附加表空间各对应一个。CopyResponse 结果中的数据是表空间内容的 tar 格式转储（遵循 POSIX 1003.1-2008 标准规定的“ustar interchange format”），但省略了标准要求的末尾两个全零块。tar 数据传输完成后，如果请求了备份清单，还会再发送一个 CopyResponse 结果，其中包含当前基础备份的清单数据。无论如何，最后都会发送一个普通结果集，包含备份的 WAL 结束位置，格式与起始位置相同。数据目录和每个表空间的 tar 归档将包含目录中的所有文件，无论它们是 PostgreSQL 文件还是添加到同一目录的其他文件。唯一排除的文件是：
postmaster.pidpostmaster.optspg_internal.init（在多个目录中找到）PostgreSQL 服务器运行期间创建的各种临时文件和目录，例如以
pgsql_tmp开头的任何文件或目录以及临时关系。不记录 WAL 的关系，但不包括恢复时重新创建（空的）不记录 WAL 的关系所需的初始化分支。
pg_wal，包括子目录。如果备份包含 WAL 文件，则将包含pg_wal的合成版本，但它只包含使备份可用所需的文件，而不包含其余内容。pg_dynshmem，pg_notify，pg_replslot，pg_serial，pg_snapshots，pg_stat_tmp和pg_subtrans将作为空目录复制（即使它们是符号链接）。除了普通文件和目录之外的文件，如符号链接（除了上述列出的目录之外的符号链接）以及特殊设备文件，将被跳过。（
pg_tblspc中的符号链接将被保留。）
如果服务器上的底层文件系统支持，将设置所有者、组和文件模式。