配置 PostgreSQL 数据源
PostgreSQL 数据源用于通过离线同步,将 PostgreSQL 表或查询结果读取到平台预置仓,也可将预置仓空间表写入 PostgreSQL。本文介绍连接配置、来源与去向设置、字段映射、支持的字段类型,以及同步验证和任务流调度。
使用限制与准备事项
开始配置前,请确认以下事项:
- 支持 PostgreSQL → 预置仓 和 预置仓 → PostgreSQL,不支持通过本方案在 PostgreSQL 与其他外部数据源之间直接同步。
- 准备 PostgreSQL 的服务器地址、端口、数据库名称,以及用于接入的用户名和密码。平台运行环境需能访问该地址;数据库的连接访问控制和网络白名单需允许平台服务器连接。
- 读取账号需有权连接数据库、访问对应 schema,并读取所选表、视图或查询涉及的数据。写入账号还需具备所选写入模式对应的目标表权限。请由数据库管理员按实际操作范围授权,参见 PostgreSQL 权限说明。
- 提前准备目标表,核对字段类型、非空约束和主键。读取到预置仓时,创建方式参见 空间表的创建与管理;写入 PostgreSQL 时,还需确认目标数据库和 schema 已存在。
| 环境配置方式 | 配置要求 |
|---|---|
| 不区分环境 | 开发环境与生产环境共用一套数据库及凭据配置 |
| 独立环境配置 | 分别配置开发环境与生产环境;两套配置均需能够访问方案所选的库、schema 和表 |
数据预览使用开发环境配置,手动执行使用生产环境配置。请分别核对两套配置的数据库、表权限和网络访问。
请通过安全方式交接密码,避免在截图、日志或公开文档中暴露凭据。更换凭据或调整权限后,应重新验证数据源连接及同步方案。
创建 PostgreSQL 数据源
- 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
- 选择 PostgreSQL,点击 下一步,填写数据源名称和备注。
- 选择 不区分环境 或 独立环境配置。独立环境配置需分别填写开发环境和生产环境的信息。
- 填写以下连接参数。在 连通性测试 中点击 测试,确认测试通过后,点击 完成。
| 配置项 | 说明 |
|---|---|
| 连接字符串 | PostgreSQL JDBC 连接地址,格式示例为 jdbc:postgresql://<host>:<port>/<database>。将占位内容替换为实际地址、端口及数据库;连接参数说明参见 pgJDBC 连接配置 |
| 数据库 | 用于连接测试的 PostgreSQL 数据库名称,需与连接地址及账号权限对应;这里填写数据库,不填写 schema |
| 用户名 | 有权限访问数据库及相关表的账号 |
| 密码 | 与用户名对应的密码 |
| 高级配置 | 按需填写 JSON 格式的扩展连接参数;没有额外配置要求时可留空 |
PostgreSQL 的数据库与 schema 是不同层级。配置同步方案时,先选择数据库,再核对数据表所属的 schema,避免选中其他 schema 下的同名表。
连通性测试通过后,还需在同步方案中加载表、预览数据并执行验证,确认表权限和实际读写结果。
配置 PostgreSQL 数据来源
- 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
- 在 数据来源 中选择 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 字段类型 |
|---|---|
| 布尔 | 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列入支持范围不代表任意二进制元素或数组结构均已通过验证。 - 来源或目标表结构变化后,请重新解析字段并检查字段对应关系。数据预览中能够显示字段,不等于该字段类型已支持同步。
保存、验证与任务流调度
保存并验证同步结果
- 检查来源表或 SQL、过滤条件、目标表和分区、写入模式及字段映射。写入 PostgreSQL 时,再次核对 schema、主键及表约束。
- 使用 数据预览 核对来源字段及样例值,再逐项检查字段映射、目标类型和目标表约束。
- 填写方案名称、负责人和备注,点击 保存。
- 点击 手动执行,按弹窗要求选择执行模式,并核对本次执行的参数值后开始执行。手动执行使用生产环境配置;执行模式不用于切换开发环境与生产环境。
- 在 手动执行记录 中查看执行状态和日志。任务成功后,到目标表核对数据量、字段对应关系,以及数值、时间、数组和空值等样例。
独立环境配置下,开发阶段可以正常加载或预览数据,不代表生产环境凭据和读写权限也已具备。首次执行前,请分别核对两套配置及目标环境中的库表、分区和参数。
挂载到任务流
手动验证通过后,可将方案挂载到任务流,按调度周期执行。
- 打开已保存的方案,点击 挂载到任务流,选择目标任务流;尚未创建时,参见 创建任务流。
- 填写节点名、执行模式、负责人等信息,点击 创建节点并挂载。
- 点击 前往任务流,检查节点及上下游依赖,核对调度所用的库表、过滤条件和空间参数。
- 完成 任务流调度设置,保存并 发布任务流。挂载成功不等于节点已经发布上线。
方案挂载到任务流后,不再通过方案详情页手动执行,请从任务流中执行和验证该节点。
常见问题
| 现象 | 检查项 |
|---|---|
| 连通性测试失败 | 核对连接字符串、数据库、用户名和密码,以及平台服务器的网络访问与数据库连接访问控制 |
| 连接通过,但找不到表或无法预览 | 核对所选数据库、schema、表名和账号的读取权限;自定义查询需核对 SQL 及其引用对象 |
| 视图无法选择分片键 | 视图不支持配置分片键;按实际视图或查询范围读取 |
| 预览正常,但执行失败 | 核对生产环境凭据、读写权限、目标 schema、表约束、写入模式、分区和参数,并查看本次执行日志 |

