跳到主要内容

配置 PostgreSQL 数据源

最近更新 2026/11/03

PostgreSQL 数据源用于通过离线同步,将 PostgreSQL 表或查询结果读取到平台预置仓,也可将预置仓空间表写入 PostgreSQL。本文介绍连接配置、来源与去向设置、字段映射、支持的字段类型,以及同步验证和任务流调度。

使用限制与准备事项​

开始配置前,请确认以下事项:

  • 支持 PostgreSQL → 预置仓 和 预置仓 → PostgreSQL,不支持通过本方案在 PostgreSQL 与其他外部数据源之间直接同步。
  • 准备 PostgreSQL 的服务器地址、端口、数据库名称,以及用于接入的用户名和密码。平台运行环境需能访问该地址;数据库的连接访问控制和网络白名单需允许平台服务器连接。
  • 读取账号需有权连接数据库、访问对应 schema,并读取所选表、视图或查询涉及的数据。写入账号还需具备所选写入模式对应的目标表权限。请由数据库管理员按实际操作范围授权,参见 PostgreSQL 权限说明。
  • 提前准备目标表,核对字段类型、非空约束和主键。读取到预置仓时,创建方式参见 空间表的创建与管理;写入 PostgreSQL 时,还需确认目标数据库和 schema 已存在。
环境配置方式配置要求
不区分环境开发环境与生产环境共用一套数据库及凭据配置
独立环境配置分别配置开发环境与生产环境;两套配置均需能够访问方案所选的库、schema 和表

数据预览使用开发环境配置,手动执行使用生产环境配置。请分别核对两套配置的数据库、表权限和网络访问。

请通过安全方式交接密码,避免在截图、日志或公开文档中暴露凭据。更换凭据或调整权限后,应重新验证数据源连接及同步方案。

创建 PostgreSQL 数据源​

  1. 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
  2. 选择 PostgreSQL,点击 下一步,填写数据源名称和备注。
  3. 选择 不区分环境 或 独立环境配置。独立环境配置需分别填写开发环境和生产环境的信息。
  4. 填写以下连接参数。在 连通性测试 中点击 测试,确认测试通过后,点击 完成。
配置 PostgreSQL 连接字符串、数据库和访问凭据
配置项说明
连接字符串PostgreSQL JDBC 连接地址,格式示例为 jdbc:postgresql://<host>:<port>/<database>。将占位内容替换为实际地址、端口及数据库;连接参数说明参见 pgJDBC 连接配置
数据库用于连接测试的 PostgreSQL 数据库名称,需与连接地址及账号权限对应;这里填写数据库,不填写 schema
用户名有权限访问数据库及相关表的账号
密码与用户名对应的密码
高级配置按需填写 JSON 格式的扩展连接参数;没有额外配置要求时可留空

PostgreSQL 的数据库与 schema 是不同层级。配置同步方案时,先选择数据库,再核对数据表所属的 schema,避免选中其他 schema 下的同名表。

连通性测试通过后,还需在同步方案中加载表、预览数据并执行验证,确认表权限和实际读写结果。

配置 PostgreSQL 数据来源​

  1. 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
  2. 在 数据来源 中选择 PostgreSQL 和已创建的数据源。
  3. 选择 取数方式,按以下说明配置读取范围。
  4. 点击 数据预览,核对字段、实际值和读取范围。
  5. 如需调整每批处理的数据量,展开 高级配置,设置 批量条数。
已有方案配置中的 PostgreSQL 来源表、过滤和批次示例

图为已有方案的配置示例,不能替代当前连接和数据读取验证。完成配置后,请使用数据预览核对实际结果。

取数方式配置要求
整表选择数据库和数据表,核对表所属的 schema;可按需选择分片键,或开启 数据过滤,填写以 WHERE 开头的过滤条件
自定义查询选择数据库,填写用于读取数据的 SQL。需要处理字段表达或读取范围时,在查询中明确指定;核对 SQL 引用的 schema、表及结果字段名称,不执行修改数据的语句
配置项说明
数据源名称已在当前空间创建的 PostgreSQL 数据源
数据库及数据表整表方式选择要读取的库表;自定义查询方式选择数据库并填写 SQL
分片键整表方式的可选项,可选字段类型为 int2、int4、int8;视图不支持配置分片键
数据过滤整表方式按需开启,用 WHERE 条件限制读取范围;关闭时不应用此过滤条件
批量条数高级配置项,界面默认值为 1000,可设置范围为 1000–50000

切换数据源、数据库、来源表或查询后,请重新核对读取范围、分片键、预览结果和字段映射。来源表新增、删除或修改字段后,也需重新解析并检查映射。方案使用空间参数时,参见 参数管理,并核对执行时的实际参数值。

配置数据去向​

PostgreSQL 读取到预置仓​

在 数据去向 中选择平台 预置仓,再选择目标空间表。若目标表尚未创建,请先前往 库表 按所需字段和分区定义创建,参见 空间表的创建与管理。

配置项说明
目标空间表接收本次 PostgreSQL 数据的预置仓空间表
分区信息目标为分区表时,按目标表要求配置分区值
写入模式选择 插入新数据 或 覆盖写入;界面默认选择覆盖写入,请根据目标数据的保留要求调整

执行前,请再次确认目标表、目标分区和写入模式,避免覆盖需要保留的数据。

预置仓写入 PostgreSQL​

在 数据来源 中选择要读取的预置仓空间表,在 数据去向 中选择 PostgreSQL 和已创建的数据源,再选择目标数据库及数据表。请核对目标表所属的 schema;未指定 schema 时使用 public,不会自动创建缺失的 schema。

配置项说明
写入表接收数据的 PostgreSQL 数据库及数据表,需核对完整的 schema 和表名
写入模式支持下表中的三种模式,界面默认选择 覆盖写入
批量条数高级配置项,界面默认值为 1000,可设置范围为 1000–10000
写入模式行为与配置要求
插入新数据向目标表追加本次数据;请检查是否会与现有主键或唯一约束冲突
覆盖写入先清空目标表原有数据,再写入本次数据;执行前确认清空范围及备份要求,中途失败时不要假定原有数据会自动恢复
更新插入按目标表实际主键匹配,更新已有记录并插入新记录;目标表需有用于匹配的主键,并完整映射主键字段

来源表与目标表的字段名可以不同,但需通过字段映射明确对应关系。写入 PostgreSQL 前,还需核对目标字段的长度、精度、非空及其他表约束。

字段映射与支持的字段类型​

完成来源和去向配置后,在 字段映射 中建立源字段与目标字段的对应关系。可以逐项选择,也可以使用 同名映射 或 同行映射 后逐项核对;一个目标字段只能对应一个来源字段。

已有方案配置中的 PostgreSQL 字段映射示例

图中展示的是已有方案的字段对应关系,不能替代当前连接和实际同步结果的验证。

PostgreSQL 作为数据来源时,支持以下字段类型。表中使用字段解析结果中的类型名称。

类型类别支持的 PostgreSQL 字段类型
布尔bool
整数int2、smallserial、int4、serial、int8、bigserial
浮点与定点数float4、float8、numeric
字符串bpchar、character、varchar、text
JSON、UUID 与空间类型json、jsonb、uuid、geometry、geography
日期时间date、timestamp、timestamptz
数组_bool、_bytea、_int2、_int4、_int8、_float4、_float8、_bpchar、_character、_varchar、_text

不支持 bytea、time、timetz,以及其他未识别的类型。数组仅支持上表列出的类型,_numeric、_date、_timestamp、_jsonb 等不在支持范围内。

写入支持的字段类型​

PostgreSQL 作为数据去向时,支持的 PostgreSQL 字段类型与上表相同;不支持 bytea、time、timetz、未列出的数组类型及其他未识别的类型。

写入前,请核对已选 PostgreSQL 表的字段定义、主键、非空及其他约束。字段类型受支持,不表示可以向 JSON、UUID、空间类型或数组字段写入任意内容。

字段类型使用限制​

  • PostgreSQL 字段解析结果可能使用元数据名称,例如 int2、int4、int8 分别对应常见的 smallint、integer、bigint;float4、float8 分别对应 real、double precision。请以实际解析出的名称为准。
  • 带长度、精度或小数位数的字段需核对完整定义;时间字段还需核对时区和精度要求。
  • 数组需核对元素类型、维度和空元素要求。_bytea 列入支持范围不代表任意二进制元素或数组结构均已通过验证。
  • 来源或目标表结构变化后,请重新解析字段并检查字段对应关系。数据预览中能够显示字段,不等于该字段类型已支持同步。

保存、验证与任务流调度​

保存并验证同步结果​

  1. 检查来源表或 SQL、过滤条件、目标表和分区、写入模式及字段映射。写入 PostgreSQL 时,再次核对 schema、主键及表约束。
  2. 使用 数据预览 核对来源字段及样例值,再逐项检查字段映射、目标类型和目标表约束。
  3. 填写方案名称、负责人和备注,点击 保存。
  4. 点击 手动执行,按弹窗要求选择执行模式,并核对本次执行的参数值后开始执行。手动执行使用生产环境配置;执行模式不用于切换开发环境与生产环境。
  5. 在 手动执行记录 中查看执行状态和日志。任务成功后,到目标表核对数据量、字段对应关系,以及数值、时间、数组和空值等样例。

独立环境配置下,开发阶段可以正常加载或预览数据,不代表生产环境凭据和读写权限也已具备。首次执行前,请分别核对两套配置及目标环境中的库表、分区和参数。

挂载到任务流​

手动验证通过后,可将方案挂载到任务流,按调度周期执行。

  1. 打开已保存的方案,点击 挂载到任务流,选择目标任务流;尚未创建时,参见 创建任务流。
  2. 填写节点名、执行模式、负责人等信息,点击 创建节点并挂载。
  3. 点击 前往任务流,检查节点及上下游依赖,核对调度所用的库表、过滤条件和空间参数。
  4. 完成 任务流调度设置,保存并 发布任务流。挂载成功不等于节点已经发布上线。

方案挂载到任务流后,不再通过方案详情页手动执行,请从任务流中执行和验证该节点。

常见问题​

现象检查项
连通性测试失败核对连接字符串、数据库、用户名和密码,以及平台服务器的网络访问与数据库连接访问控制
连接通过,但找不到表或无法预览核对所选数据库、schema、表名和账号的读取权限;自定义查询需核对 SQL 及其引用对象
视图无法选择分片键视图不支持配置分片键;按实际视图或查询范围读取
预览正常,但执行失败核对生产环境凭据、读写权限、目标 schema、表约束、写入模式、分区和参数,并查看本次执行日志
这篇文档对你有帮助吗?