RisingWave 实时数据落库指南:基于 JDBC Connector 的 Postgres Sink 端到端实践
RisingWave 实时数据落库指南:基于 JDBC Connector 的 Postgres Sink 端到端实践
本篇技术指南围绕 RisingWave 仓库中 integration_tests/postgres-sink 集成测试示例展开,系统讲解如何将 RisingWave 中的流式数据(含物化视图与各类数据类型表)实时写入外部 PostgreSQL 数据库。你将掌握从 docker compose 一键拉起集群、datagen 模拟数据源接入、CREATE SINK 语法与 jdbc connector 参数(upsert / append-only、primary_key、force_append_only)配置,到目标端建表与行数校验的完整链路,可直接复制运行并复用于生产级 Postgres 落库场景。
演示场景:一条从生成到入库的完整数据链路
本示例的核心意图在 integration_tests/postgres-sink/README.md 中表述得非常清晰:演示如何将 RisingWave 的数据 Sink 到外部 Postgres。README 特别强调,docker compose 中已经内置了数据加载器,因此集群一启动,数据就会自动装载到 Postgres,无需额外手动灌数。
整个演示按以下三步执行:
docker compose up -d:启动集群;- 等待 20–30 秒后执行
create_source.sql、create_mv.sql、create_sink.sql三个 SQL 脚本; - 再等待约 30 秒,测试器通过
SELECT COUNT(*) FROM target_count;在 Postgres 中校验数据是否成功写入。
从本地机器连接 Postgres 的命令(README 原文):
psql postgresql://myuser:123456@127.0.0.1:5432/mydb
这条链路实际上是 RisingWave 流处理的标准三步范式:建 Source(数据入口)→ 建物化视图(流式计算)→ 建 Sink(数据出口)。其中 datagen 作为内置模拟数据源持续产生用户行为事件,target_count 物化视图按 target_id 实时聚合计数,最终由 JDBC Sink 写入 Postgres 表 target_count。
集群拓扑:docker-compose 一次拉起全部依赖
示例的编排文件 integration_tests/postgres-sink/docker-compose.yml 通过 extends 复用了仓库根目录 docker/docker-compose.yml 中定义的标准服务,保证与官方镜像环境一致:
| 服务 | 说明 |
|---|---|
risingwave-standalone |
RisingWave 单机版(standalone 模式),前端端口 4566,元数据存储于 postgres-0,状态存储在 MinIO(Hummock) |
postgres-0 |
RisingWave 的元数据库(metadata,postgres:15-alpine),与 Sink 目标库相互独立 |
minio-0 |
对象存储,存放 Hummock 状态数据(hummock001) |
grafana-0 / prometheus-0 |
监控与可视化组件 |
postgres |
Sink 目标库(本示例的核心服务) |
其中 postgres 目标库的配置值得逐项关注:
postgres:
image: postgres:latest
environment:
- POSTGRES_USER=myuser
- POSTGRES_PASSWORD=123456
- POSTGRES_DB=mydb
ports:
- 5432:5432
healthcheck:
test: [ "CMD-SHELL", "pg_isready --username=myuser --dbname=mydb" ]
interval: 5s
timeout: 5s
retries: 5
command: [ "postgres", "-c", "wal_level=logical" ]
volumes:
- "./postgres_prepare.sql:/postgres_prepare.sql"
restart: always
container_name: postgres
要点解读:
- 账号信息:用户
myuser、密码123456、默认库mydb,与 README 的psql连接串、以及后面create_sink.sql中的jdbc.url一一对应; wal_level=logical:开启逻辑复制所需 WAL 级别,这是 Postgres 作为 CDC 与高级写入场景的基础配置,此处为 Sink 写入提供正确的日志语义;healthcheck使用pg_isready探测就绪状态,docker compose up后可据此等待依赖就绪;- 挂载
postgres_prepare.sql:将目标表 DDL 脚本注入容器,配合 integration_tests/postgres-sink/prepare.sh 在容器内执行建表:
docker compose exec postgres bash -c "psql postgresql://myuser:123456@postgres:5432/mydb < postgres_prepare.sql"
数据入口:datagen 模拟源与两张类型测试表
源端脚本 integration_tests/postgres-sink/create_source.sql 定义了三个对象:
① user_behaviors 流式源(Source)——使用内置 datagen connector 模拟用户行为事件流:
CREATE SOURCE user_behaviors (
user_id VARCHAR,
target_id VARCHAR,
target_type VARCHAR,
event_timestamp TIMESTAMPTZ,
behavior_type VARCHAR,
parent_target_type VARCHAR,
parent_target_id VARCHAR
) WITH (
connector = 'datagen',
fields.user_id.kind = 'sequence',
fields.user_id.start = 1,
fields.user_id.end = 100,
datagen.rows.per.second = '100'
) FORMAT PLAIN ENCODE JSON;
参数含义:
connector = 'datagen':启用内置数据生成器,无需外部消息队列即可持续产生数据;fields.user_id.kind = 'sequence':user_id字段按序列生成;fields.user_id.start = 1/fields.user_id.end = 100:序列取值范围 1–100;datagen.rows.per.second = '100':每秒产生 100 行事件;FORMAT PLAIN ENCODE JSON:数据以 JSON 编码的普通格式(非 upsert)接入。
② data_types 表——一张覆盖 RisingWave 常见标量类型与数组类型的物化基础表,字段包含 VARCHAR、TEXT、INTEGER、SMALLINT、BIGINT、DECIMAL、REAL、DOUBLE PRECISION、BOOLEAN、DATE、TIME、TIMESTAMP、TIMESTAMPTZ、INTERVAL、JSONB、BYTEA、VARCHAR[],并预置了 5 行边界值数据,用于验证 Sink 过程中各类型在 RisingWave 与 Postgres 之间的映射正确性。
③ pg_all_data_types 表——针对 Postgres 原生类型体系的"全类型"测试表,包含 boolean、smallint、integer、bigint、decimal、real、double precision、varchar、bytea、date、time、timestamp、timestamptz、interval、jsonb 以及五种数组类型(smallint[]、integer[]、bigint[]、real[]、double precision[]、varchar[]),并写入三条极值数据(如最小的 smallint/bigint、0001-01-01 日期、9999-12-31 日期、长字符串等),用来压测 Postgres Sink 在边界值与最大精度上的表现。
流式计算:按 target_id 实时聚合
计算层脚本 integration_tests/postgres-sink/create_mv.sql 非常简洁,将 user_behaviors 流按 target_id 分组、实时统计行为次数:
CREATE MATERIALIZED VIEW target_count AS
SELECT
target_id,
COUNT(*) AS target_count
FROM
user_behaviors
GROUP BY
target_id;
物化视图一旦创建即持续增量更新,这正是 RisingWave 作为流引擎的核心价值:Sink 直接读取该视图的最新结果,从而让目标 Postgres 中的 target_count 始终与上游事件流保持同步。
Sink 落库:JDBC Connector 的参数全解
落库脚本 integration_tests/postgres-sink/create_sink.sql 创建了三个 Sink,覆盖了 JDBC Sink 的两种核心写入模式。
Sink ①:流式聚合结果以 upsert 写入
set sink_decouple = false;
CREATE SINK target_count_postgres_sink
FROM target_count
WITH (
connector = 'jdbc',
jdbc.url = 'jdbc:postgresql://postgres:5432/mydb',
user='myuser',
password='123456',
table.name = 'target_count',
type = 'upsert',
primary_key = 'target_id'
);
Sink ②:data_types 表以 upsert 写入
CREATE SINK data_types_postgres_sink
FROM data_types WITH (
connector = 'jdbc',
jdbc.url = 'jdbc:postgresql://postgres:5432/mydb',
user='myuser',
password='123456',
table.name = 'data_types',
type='upsert',
primary_key = 'id'
);
Sink ③:pg_all_data_types 以 append-only 强制追加写入
CREATE SINK pg_all_data_types_sink
FROM
pg_all_data_types WITH (
connector = 'jdbc',
jdbc.url = 'jdbc:postgresql://postgres:5432/mydb',
user='myuser',
password='123456',
table.name = 'pg_all_data_types',
type='append-only',
primary_key = 'id',
force_append_only = 'true',
);
逐项参数说明:
| 参数 | 取值示例 | 含义 |
|---|---|---|
connector |
'jdbc' |
使用 JDBC 通用连接器,可对接 PostgreSQL 等支持 JDBC 的关系库 |
jdbc.url |
jdbc:postgresql://postgres:5432/mydb |
目标库 JDBC 地址。注意容器网络内使用服务名 postgres,主机访问则用 127.0.0.1:5432(见 README 的 psql 命令) |
user / password |
myuser / 123456 |
目标库认证信息 |
table.name |
target_count |
写入的 Postgres 目标表名 |
type |
'upsert' / 'append-only' |
写入语义:upsert 按主键覆盖更新;append-only 仅追加新行 |
primary_key |
target_id |
与 upsert 配合指定主键字段(须与目标表主键对应) |
force_append_only |
'true' |
对原本带主键/可能产生更新语义的源,强制按追加模式写入,避免因变更流触发 upsert 路径 |
值得注意的细节:
- 首行
set sink_decouple = false;表示 Sink 与上游物化视图在事务上耦合(不脱钩),保证数据一致性与顺序;Sink 解耦(decouple)作为一项会话级开关,允许使用者按需调整故障恢复与吞吐语义。 - 示例同时演示了"同一连接串、不同
table.name、不同type"的三种组合,说明一个 JDBC 目标库可以承载多个 Sink,分别服务聚合结果、静态类型表、全类型边界测试等不同需求。
对应目标端,integration_tests/postgres-sink/postgres_prepare.sql 预先创建了三张结构完全对齐的表(target_count、data_types、pg_all_data_types),其中 target_count.target_id VARCHAR(128) 为主键、target_count BIGINT;其余两张表的字段与源端 create_source.sql 中同名表完全一致。源端表结构、Sink 列与 Postgres 目标表结构必须严格对齐,这是 JDBC Sink 写入成功的前提。
验证闭环:自动校验与手动查询
示例提供了两套验证手段:
自动校验脚本 integration_tests/postgres-sink/sink_check.py 复用 CI 脚本目录(integration_tests/scripts)中的通用工具:
def pg_count(rel):
sql = f'SELECT COUNT(*) FROM {rel};'
output = docker_compose_exec("postgres", f'psql -U $POSTGRES_USER $POSTGRES_DB --tuples-only -c "{sql}"')
return int(output.strip())
failed = check_row_counts(['target_count', 'data_types', 'pg_all_data_types'], pg_count, "PG")
report_failures(failed)
它逐一在 postgres 容器内对三张目标表执行 SELECT COUNT(*),与 RisingWave 侧对应关系表的行数比对,从而确认 Sink 写入完整无丢失。
手动查询则按 README 直接连接:
psql postgresql://myuser:123456@127.0.0.1:5432/mydb
然后执行 SELECT COUNT(*) FROM target_count;,若返回的行数持续增长,即说明 user_behaviors → target_count(物化视图)→ target_count_postgres_sink → Postgres 的全链路实时贯通。也可以进一步查询 data_types 与 pg_all_data_types,验证各类型字段(含 BYTEA、JSONB、数组)落库后是否与预期一致。
仓库侧印证:JDBC 参数解析与端到端测试
除了集成示例,仓库源码侧也提供了充分佐证:
- 参数解析与 Sink 骨架:JDBC 连接参数(
jdbc.url、user、password)以及force_append_only等 Sink 公共参数在 src/connector/src/sink 的配置解析中均有定义,例如allow_alter_on_fly_fields.rs涉及运行期可调整字段、mod.rs汇总各类 Sink 参数;force_append_only与type语义是 RisingWave Sink 通用选项,本文示例即为其典型组合用法。 - 端到端 SLT 测试:仓库还维护了一份独立的 PostgreSQL Sink 回归测试 e2e_test/sink/postgres_sink.slt,并由 CI 脚本 ci/scripts/e2e-postgres-sink-test.sh 驱动——脚本先通过
risedev配置ci-sink-postgres-testprofile 并拉起依赖,再用risedev slt './e2e_test/sink/postgres_sink.slt'执行断言。这说明 Postgres Sink 在 RisingWave 中既有开箱即用的集成示例(本文所述),也具备持续运行的自动化回归保障。
常见问题与排障要点
- 连不上目标库:确认容器网络内使用服务名
postgres:5432(Sink 内地址),宿主机访问使用127.0.0.1:5432;账号密码需与docker-compose.yml的POSTGRES_USER/POSTGRES_PASSWORD一致。 - 表结构不匹配:Sink 前务必先在 Postgres 执行
postgres_prepare.sql(或手动创建同名同构表),列名、类型需与源对象对齐,否则写入报错。 upsert无主键报错:type='upsert'时必须在WITH中声明primary_key,且该字段应能在目标表中唯一标识一行(如target_id、id)。- 主键冲突/更新语义不符预期:若源侧数据不需要更新语义,可改用
type='append-only'并配合force_append_only = 'true',如示例中pg_all_data_types_sink的做法。 - 等待时序:README 明确建议
docker compose up -d后等待 20–30 秒再执行三个 SQL 脚本,再等约 30 秒后校验,这是为了让 RisingWave 各组件就绪、Sink 完成首轮数据搬运;可结合postgres容器的pg_isreadyhealthcheck 判断就绪状态。 - 会话参数:
set sink_decouple = false;作用于当前会话,多 Sink 脚本中应确保该设置先于CREATE SINK生效。
小结
integration_tests/postgres-sink 用最少的代码完整展示了 RisingWave 的 Postgres 落库能力:datagen 源模拟流式输入、物化视图做实时聚合、JDBC Sink 按 upsert 或 append-only 语义写库、sink_check.py 完成行数校验。无论你是想快速验证 RisingWave 与 PostgreSQL 的互通性,还是准备把生产环境中的流计算结果同步到关系型数据仓库,都可以以此为模板:复用 docker-compose.yml 搭建环境,参考 create_source.sql、create_mv.sql、create_sink.sql 编写自己的管道,并用 postgres_prepare.sql 与 sink_check.py 完成目标端建表与持续校验,即可快速落地一套"流式入库 PostgreSQL"的可靠方案。