RisingWave 实时数据落库指南:基于 JDBC Connector 的 Postgres Sink 端到端实践

原创2026-09-24 20:16:171,868 阅读
文章标签:数据库流处理后端数据工程

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,无需额外手动灌数。

整个演示按以下三步执行:

  1. docker compose up -d:启动集群;
  2. 等待 20–30 秒后执行 create_source.sql、create_mv.sql、create_sink.sql 三个 SQL 脚本;
  3. 再等待约 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-test profile 并拉起依赖,再用 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_isready healthcheck 判断就绪状态。
  • 会话参数: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"的可靠方案。

登录后查看全文
risingwave