文档下载建议反馈入口

  • 单机主备复制语句
    • REPLICATE SET PRIMARY
    • REPLICATE SET ROLE
    • REPLICATE SET SERVICE
  • 集群复制语句
    • REPLICATE FROM
    • REPLICATE STOP

复制

复制语句用于在单机和集群部署场景下实现高可用能力：

  • 单机部署时，用户可通过配置主备角色，灵活管理主备复制服务的生命周期，包括启动、暂停、恢复和删除等操作。有关单机主备复制功能的更多信息，参见单机主备复制。
  • 集群部署时，用户可通过启动/停止复制任务来管理数据同步，并基于复制状态监控实现主备切换和灾备恢复。有关集群复制功能的更多信息，参见集群复制。

注意

当前版本暂不支持在三权分立模式下使用复制功能

单机主备复制语句

REPLICATE SET PRIMARY

REPLICATE SET PRIMARY 语句用于为当前节点添加目标主库地址，或变更现有主库的 IP 地址。

执行语句的节点必须为普通节点或备库节点。如果节点为普通节点，添加主库地址后，系统将自动将其角色切换为备库。

所需权限

用户是 admin 角色的成员。默认情况下，root 用户属于 admin 角色。

语法格式

参数说明

参数说明
primary_url主库 URL，格式为符合 JDBC 连接协议方式的字符串。支持安全和非安全模式。安全模式下需采用证书认证方式，证书对应地址应为备库证书地址并且要保证主备证书配置一致。

语法示例

REPLICATE SET PRIMARY 'postgresql://root@localhost:26267/defaultdb?sslmode=verify-ca&sslcert=./certs/client.root.crt&sslkey=./certs/client.root.key&sslrootcert=./certs/ca.crt';

REPLICATE SET ROLE

REPLICATE SET ROLE 语句用于切换节点角色，适用于主备切换、主库非计划性宕机等场景。

所需权限

用户是 admin 角色的成员。默认情况下，root 用户属于 admin 角色。

语法格式

语法示例

  • 将当前节点角色切换为普通节点，支持读写操作。

    REPLICATE SET ROLE DEFAULT;

  • 将当前节点角色切换为主库，支持读写操作。

    REPLICATE SET ROLE PRIMARY;

  • 将当前节点角色切换为备库，仅支持读操作。

    REPLICATE SET ROLE SECONDARY;

REPLICATE SET SERVICE

REPLICATE SET SERVICE 语句用于创建、启动、停止和删除主备复制服务：

  • CREATE：创建主备复制服务，建立主备高可用关系。
  • START：启动主备复制服务，适用于主备初始化或计划性停机后的恢复场景。
  • STOP：停止主备复制服务，适用于计划性停机、主备切换等场景。停止复制后，主库会先进行历史数据复制，待主备数据达到一致后，返回操作成功提示。
  • DROP：删除主备复制服务，停止数据同步并清除主备关系。

执行 CREATE、START 和 STOP 操作的节点必须为备库。 执行 DROP 操作的节点必须为普通节点。

所需权限

用户是 admin 角色的成员。默认情况下，root 用户属于 admin 角色。

语法格式

语法示例

  • 创建主备复制服务。

    REPLICATE SET SERVICE CREATE;

  • 启动主备复制。

    REPLICATE SET SERVICE START;

  • 停止主备复制。

    REPLICATE SET SERVICE STOP;

  • 删除主备复制。

    REPLICATE SET SERVICE DROP;

集群复制语句

REPLICATE FROM

REPLICATE FROM 语句用于在集群间启动数据复制任务，支持表级别和库级别的数据复制。

所需权限

用户是 admin 角色的成员。默认情况下，root 用户属于 admin 角色。

语法格式

参数说明

参数说明
database_name要复制的库名。注意：库内无表的情况下，不支持开启库级复制，需要先进行库内表创建后才能开启库级复制。
table_name要复制的表名，格式为 database_name.schema_name.table_name。未指定数据库和模式时，表示复制当前数据库默认模式下的表
source_url主库集群地址，格式为 PostgreSQL 连接字符串。建议配置为 HAProxy 地址而非直连节点 IP，以便在主库节点故障时自动切换
支持安全和非安全两种模式：
- 非安全模式：postgresql://user@host:port?sslmode=disable
- 安全模式（用户名密码认证）：postgresql://user:password@host:port，需要在主库和备库创建同名用户及密码
- 安全模式（证书认证）：postgresql://user@host:port/database?sslmode=verify-ca&sslcert=<cert_path>&sslkey=<key_path>&sslrootcert=<ca_path>，需要主备库共享证书
options复制选项，支持以下参数组合：
- init：仅复制表结构和未来新增数据
- data：备库已有表结构，仅复制数据（包括历史数据和未来新增数据）
- init, data：备库为空，需要完整复制表结构和数据
- data, lastTime(<timestamp>)：备库已有表结构，仅复制指定时间点后的历史数据和未来新增数据
- init, data, lastTime(<timestamp>)：复制表结构以及指定时间点后的历史数据和未来新增数据

返回字段说明

字段说明
replication_producer_id主库复制任务 ID，用于在主库管理复制任务
replication_consumer_id备库复制任务 ID，用于在备库管理复制任务
start_time用户指定的数据复制起始时间点，未指定时返回 0

语法示例

  • 非安全模式下，复制库结构和未来增量数据

    REPLICATE DATABASE e1primary 
FROM 'postgresql://root@192.168.111.128:26260?sslmode=disable' 
WITH init;

  • 证书认证安全模式下，复制库结构和所有数据

    REPLICATE DATABASE e1primary 
FROM 'postgresql://root@localhost:26267/defaultdb?sslmode=verify-ca&sslcert=./certs/client.root.crt&sslkey=./certs/client.root.key&sslrootcert=./certs/ca.crt' 
WITH init, data;

  • 非安全模式下，备库表已存在，仅复制数据

    REPLICATE TABLE defaultdb.public.t1 
FROM 'postgresql://root@192.168.111.128:26257?sslmode=disable' 
WITH data;

  • 非安全模式下，复制表结构和指定时间点后的数据

    REPLICATE TABLE defaultdb.public.t3
FROM 'postgresql://root@192.168.111.128:26257?sslmode=disable' 
WITH init, data, lastTime('2025-09-18 03:36:19.665970998+00:00');

REPLICATE STOP

REPLICATE STOP 语句用于优雅地停止集群间的数据复制任务。在指定的超时时间内，如果主库无新数据写入，系统将停止复制并返回最后一次检查点时间。

提示

如需强制终止复制任务，可使用 CANCEL JOB 语句，但强制终止不保证主库和备库数据一致性，建议仅在紧急情况下使用。

所需权限

用户是 admin 角色的成员。默认情况下，root 用户属于 admin 角色。

语法格式

参数说明

参数说明
replication_consumer_id启动复制时返回的备库任务 ID
duration超时时间，在指定时间内无新数据写入后停止复制

返回字段说明

字段说明
replication_consumer_id备库任务 ID
last_checkpoint最后一次检查点时间，该时间点之前的数据已全部复制完成。注意：因数据入库存在延迟，备库中可能存在入库时间晚于该时间点的数据，因此在备库执行时间点早于 last_checkpoint 的操作时可能因冲突而失败
status复制状态

语法示例

REPLICATE STOP 845690899499384833 WITH TIMEOUT 100ms;