PostgreSQL 数据源为您提供读取和写入 PostgreSQL 的双向通道数据集成能力，实现不同数据源与 PostgreSQL 之间进行数据传输。本文为您介绍 DataSail 的 PostgreSQL 数据同步的能力支持情况。

1 支持的 PostgreSQL 版本 #

PostgreSQL 离线读写目前支持以下两种版本：

• 火山引擎云数据库 PostgreSQL 版；
• 自建 PostgreSQL 10、11、12、13、14。

您可以在数据库中执行以下语句，查看 PostgreSQL 数据库的版本：

show server_version

2 使用前提 #

2.1 账号与权限 #

子账号新建数据源时，需要有项目的管理员角色，方可以进行新建数据源操作。各角色对应权限说明，详见管理成员。对账号及其相关权限的要求如下：

• 建议创建专用同步账号
  为保障安全性和可追溯性，建议为数据集成任务创建一个专用的 PostgreSQL 账号，避免使用业务账号或高权限账号进行数据同步。创建用户 SQL 示例如下：

  -- 创建 DataSail 专用同步用户
  CREATE USER datasail_user PASSWORD 'your_password';
  

• 离线读 PostgreSQL 数据时，配置的账号需拥有同步表所在 Schema 的读权限。授权 SQL 示例如下：

  -- 授予指定 Schema 的使用权限
  GRANT USAGE ON SCHEMA "public" TO datasail_user;
  
  -- 授予指定 Schema 下所有表的读权限
  GRANT SELECT ON ALL TABLES IN SCHEMA "public" TO datasail_user;
  
  -- 【推荐】确保未来新建的表也自动授予读权限
  ALTER DEFAULT PRIVILEGES IN SCHEMA "public" GRANT SELECT ON TABLES TO datasail_user;
  

  说明

  如需授权其他 Schema（非 public），请将上述语句中的 "public" 替换为对应的 Schema 名称。如需授权多个 Schema，请对每个 Schema 分别执行上述命令。

• 离线写 PostgreSQL 数据时，配置的账号需拥有同步表的写（INSERT、DELETE、UPDATE）权限。

  • 授权 SQL 示例

    GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA "public" TO datasail_user;
    
    -- 【推荐】确保未来新建的表也自动授予写权限
    ALTER DEFAULT PRIVILEGES IN SCHEMA "public" GRANT INSERT, UPDATE, DELETE ON TABLES TO datasail_user;
    

  • 限制特定表的访问（可选）
    如果您希望仅同步部分表，可以精细化控制权限：

    -- 先撤销 Schema 级别的默认权限
    ALTER DEFAULT PRIVILEGES IN SCHEMA "your_schema" REVOKE SELECT ON TABLES FROM datasail_user;
    REVOKE SELECT ON ALL TABLES IN SCHEMA "your_schema" FROM datasail_user;
    
    -- 再单独授权指定表
    GRANT SELECT ON "your_schema"."your_table" TO datasail_user;
    

• 数据同步解决方案（实时 WAL 读取） 使用 PostgreSQL 数据源配置实时方案时，需要配置的账号具备 SuperUser 或 replication 角色权限，两者区别如下：

  • SuperUser 权限（推荐用于快速配置）
    PostgreSQL 实时整库解决方案执行时，需要拥有 SuperUser 权限的用户来创建 publication。

    -- 查看当前用户账号是否有 SuperUser 权限，返回 False 则表示无权限
    SELECT usesuper FROM pg_user WHERE usename = 'datasail_user';
    
    -- 若当前账号无高权限，则需请拥有高权限的账号授予 SuperUser
    ALTER USER datasail_user WITH SUPERUSER;
    

  • replication 权限（推荐用于最小权限原则）
    如果不希望授予 SuperUser 权限，可以使用 replication 权限配合手动创建 publication 的方式：

    -- 检查账号是否有 replication 权限，预期返回 True
    SELECT userepl FROM pg_user WHERE usename = 'datasail_user';
    
    -- 若无 replication 权限，执行以下语句授权
    ALTER USER datasail_user REPLICATION;
    

    如果使用 replication 权限（非 SuperUser），需要由具有高权限的账号手动创建 publication：

    -- 默认订阅全部表，支持新增表自动添加
    CREATE PUBLICATION dbz_publication FOR ALL TABLES;
    
    -- 或者仅指定部分表
    CREATE PUBLICATION dbz_publication FOR TABLE table1, table2, table3;
    

  说明

  • publication 名称需唯一，不能以数字开头。
  • 若使用 FOR ALL TABLES，后续无法通过 ALTER PUBLICATION ... DROP TABLE 移除单表。
  • 若使用 FOR TABLE ...，可以后续通过以下命令添加或移除表：

    ALTER PUBLICATION dbz_publication ADD TABLE new_table;
    ALTER PUBLICATION dbz_publication DROP TABLE old_table;
    

2.2 WAL 服务端配置（实时同步必读） #

1. 第一步：设置 wal_level 为 logical
   在 PostgreSQL 配置文件（postgresql.conf）中，设置以下参数：

   # 【必须】开启逻辑复制
   wal_level = logical
   
   # 【推荐】设置最大复制槽数量，需大于等于使用逻辑复制的连接器数量 + 其他复制槽数量
   max_replication_slots = 10
   
   # 【推荐】设置最大 WAL 发送进程数，建议至少为复制槽总数的 2 倍
   max_wal_senders = 20
   
   # 【推荐】禁用 WAL 发送超时，避免长时间同步时连接中断
   wal_sender_timeout = 0
   
   # 【推荐】确保 statement_timeout 为 0（默认值）或大于 5 分钟
   # statement_timeout = 0
   

   注意

   • 火山引擎云数据库 PostgreSQL 版可在控制台 > 参数配置中修改 wal_level 为 logical，修改后需重启集群生效。
   • 自建 PostgreSQL 数据库需手动修改 postgresql.conf 文件。

2. 第二步：配置 pg_hba.conf（自建数据库）
   对于自建 PostgreSQL，需要在 pg_hba.conf 文件中添加允许复制连接的记录：

   # 允许 DataSail 资源组 IP 段进行复制连接
   host    replication     datasail_user     0.0.0.0/0     md5
   

3. 第三步：重启 PostgreSQL 服务
   修改配置文件后，需要重启 PostgreSQL 服务使配置生效：

   sudo systemctl restart postgresql
   

4. 第四步：创建逻辑复制槽
   必须在完成 publication 创建之后再创建复制槽。请确保在创建复制槽时已连接到正确的目标数据库。

   -- 创建逻辑复制槽（必须使用 pgoutput 插件）
   SELECT pg_create_logical_replication_slot('datasail_pgoutput_slot', 'pgoutput');
   

   说明

   • 每个使用同一 PostgreSQL 集群的连接都需要创建唯一的复制槽，复制槽名称不能以数字开头。
   • 请确保服务器有足够的磁盘空间存储 WAL 日志。如果同步中断，WAL 日志会在服务器上累积。如需释放空间，可以删除复制槽（会同时删除其未消费的日志）。

5. 第五步：验证配置是否生效

   -- 检查 wal_level 是否为 logical
   SHOW wal_level;
   -- 期望结果：logical
   
   -- 检查 max_replication_slots
   SHOW max_replication_slots;
   -- 期望结果：大于等于当前复制槽数量
   
   -- 检查 max_wal_senders
   SHOW max_wal_senders;
   
   -- 检查可用的 WAL 发送进程数
   SELECT count(*) FROM pg_stat_replication;
   -- max_wal_senders 值应大于此查询结果
   
   -- 验证 publication 是否创建成功
   SELECT * FROM pg_publication;
   
   -- 验证 publication 中包含的表
   SELECT * FROM pg_publication_tables;
   
   -- 验证复制槽是否创建成功
   SELECT * FROM pg_replication_slots;
   

2.3 复制标识设置（实时同步必读） #

PostgreSQL 实时同步依赖复制标识（Replica Identity）来精准识别数据变更。必须将需要同步的表设置为 FULL 模式：

-- 检查表的复制标识设置
-- d=默认(主键)  n=无  f=全列  i=索引
SELECT relreplident FROM pg_class WHERE relname = 'your_table_name';

-- 设置为 FULL 模式（推荐）
ALTER TABLE your_table_name REPLICA IDENTITY FULL;

2.4 读副本建议 #

对于生产环境的大表全量同步，建议在 PostgreSQL 只读副本（Read Replica / Standby） 上进行数据采集，而非直接读取主库，以避免对线上业务造成性能影响。

• 火山引擎云数据库 PostgreSQL 版支持创建只读实例。
• 自建 PostgreSQL 可通过流复制搭建 Standby 节点。

2.5 网络连通 #

确保集成同步任务使用的独享数据集成资源组，具有 PostgreSQL 数据库节点的网络访问能力。网络互通方案详见网络连通解决方案。

• 数据源为 RDS 云数据库实例时，需要将集成资源组所在 VPC 中的 IPv4 CIDR 地址添加到 PostgreSQL 访问白名单中。

  注意

  • 如果 PostgreSQL 数据源实例所在的 VPC 和独享集成资源组所在的 VPC 相同时，您仅需将 VPC 中的 IPv4 CIDR 地址添加到 PostgreSQL 访问白名单中；
  • 如果 PostgreSQL 数据源实例所在的 VPC 和独享集成资源组所在的 VPC 不同时，您需要先通过 CEN 云企业网打通两个 VPC 网络，然后将集成资源组 VPC 和 PostgreSQL 所在 VPC 中的两个 IPv4 CIDR 地址，均添加到 PostgreSQL 访问白名单中。
  • 若考虑安全因素，为了减少 IP CIDR 的访问范围，您至少需要将集成资源组绑定的子网下的 IPv4 CIDR 地址加入到数据库白名单中。
  添加白名单的操作如下：
  1. 确认集成资源组所在的 VPC。
     
  2. 查看 VPC 的 IPv4 CIDR 地址。

     注意

     若考虑安全因素，减少 IP CIDR 的访问范围，您至少需要将集成资源组绑定的子网下的 IPv4 CIDR 地址加入到数据库白名单中。

     
  3. 将获取到的 IPv4 CIDR 地址添加进 PostgreSQL 数据库白名单中，添加操作详见创建白名单。
     
• 数据源为公网自建数据源，需通过公网形式访问：
  1. 集成资源组开通公网访问能力，操作详见开通公网。
  2. 并将公网 IP 地址，添加进 PostgreSQL 数据库白名单中。

  注意

  • DataSail 不支持通过负载均衡器（Load Balancer）连接 PostgreSQL 数据库，请使用数据库实例的直连地址。
  • 如需通过 SSH 隧道连接内网数据库，请先配置 SSH 数据源，并在 PostgreSQL 数据源中关联 SSH 连接信息。详见配置 SSH 数据源。

2.6 连接安全（SSL） #

DataSail 的 PostgreSQL 数据源支持以下四种 SSL 模式，具体说明请参见 PostgreSQL SSL 官方文档。

3 支持的字段类型 #

当前主要字段支持情况如下：

4 数据源注册 #

在多环境模式的项目下，数据源能够实现开发环境与生产环境的注册隔离。并且在进行离线集成任务配置时，多环境下的数据源信息均需要进行注册。

4.1 配置信息填写 #

新建数据源操作详见配置数据源，下面为您介绍用连接串方式配置 PostgreSQL 数据源信息：

4.2 连通性验证 #

数据源注册完成后，单击测试连通性按钮，系统将依次检查以下项目：

如果测试失败，请根据错误提示逐项排查。您也可以在 PostgreSQL 客户端（psql）执行以下命令自行验证：

-- 验证账号是否能连接
-- psql -h <host> -p <port> -U <user> -d <database>

-- 验证权限
SELECT * FROM information_schema.role_table_grants WHERE grantee = 'datasail_user';

-- 验证 WAL 配置（实时同步场景）
SHOW wal_level;
SELECT * FROM pg_replication_slots;
SELECT * FROM pg_publication;

5 同步方式选择指引 #

DataSail 提供以下多种 PostgreSQL 数据同步方式，请根据您的业务场景选择合适的方式：

下面列举解决方案和单表任务同步操作时，在不同维度的差异：