Apache seatunel常用配置参数解析说明

下面我按你目前使用的 SeaTunnel 2.3.12 + Zeta Engine + Oracle-CDC → MySQL JDBC Sink 场景整理一份，重点放在实际配置文件里最常用、最容易混淆的参数。

官方 2.3.12 JDBC 文档中，generate_sink_sql、primary_keys、enable_upsert、schema_save_mode、data_save_mode 等都属于 JDBC Sink 的核心参数。

一、SeaTunnel 配置整体结构

一个典型 SeaTunnel 任务：

复制代码

env {
    execution.parallelism = 2
    job.mode = "STREAMING"
    checkpoint.interval = 10000
}

source {
    Oracle-CDC {
        ...
    }
}

sink {
    Jdbc {
        ...
    }
}

可以简单理解成：

复制代码

                    SeaTunnel
                        │
             ┌──────────┴──────────┐
             │                     │
          SOURCE                 SINK
             │                     │
        Oracle-CDC              JDBC
             │                     │
             └────── CDC ──────────┘
                        │
                      MySQL

二、ENV 常用参数

参数	示例	作用	常用值/说明
`execution.parallelism`	`2`	SeaTunnel 作业并行度	1、2、4、8...
`job.mode`	`"STREAMING"`	作业运行模式	`STREAMING` / `BATCH`
`checkpoint.interval`	`10000`	Checkpoint 间隔	单位毫秒
`checkpoint.timeout`	`60000`	Checkpoint 超时时间	单位毫秒
`checkpoint.data_file`	...	Checkpoint 数据相关配置	一般不需要手工修改

三、Oracle-CDC Source 常用参数

复制代码

source {
    Oracle-CDC {
        url = "jdbc:oracle:thin:@//127.0.0.1:1521/sjztncdb"

        username = "anger"
        password = "******"

        database-names = ["SJZTNCDB"]

        schema-names = ["ANGER"]

        table-names = [
            "SJZTNCDB.ANGER.CDC_ORDERS",
            "SJZTNCDB.ANGER.TEST_CDC_ORDERS"
        ]

        startup.mode = "initial"
    }
}

核心参数可以整理成：

参数	示例	作用
`url`	`jdbc:oracle:thin:@//127.0.0.1:1521/sjztncdb`	Oracle JDBC 连接地址
`username`	`anger`	Oracle 用户
`password`	`******`	Oracle 密码
`database-names`	`["SJZTNCDB"]`	Oracle 数据库名
`schema-names`	`["ANGER"]`	Schema
`table-names`	`["SJZTNCDB.ANGER.CDC_ORDERS"]`	CDC 监控表
`startup.mode`	`initial`	CDC 启动方式
`startup.specific-offset`	-	从指定位置启动，具体支持取决于版本
`debezium.*`	-	部分底层 CDC 行为控制

四、startup.mode 是非常重要的参数

对于 CDC，这是最容易搞混的参数之一。

常见概念：

模式	含义
`initial`	先做历史数据 Snapshot，再继续 CDC
`latest`	从最新位置开始，通常不做历史全量
`earliest`	尽可能从较早的可用位置开始
`specific`	从指定位置开始

五、JDBC Sink 连接参数

复制代码

sink {
  Jdbc {
    url = "jdbc:mysql://127.0.0.1:6033"

    driver = "com.mysql.cj.jdbc.Driver"

    user = "cdcadmin"
    password = "Bai_yun123"

    generate_sink_sql = true

    database = "targetdb"

    table = "${table_name}"

    primary_keys = ["${primary_key}"]

    schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"

    data_save_mode = "APPEND_DATA"

    batch_size = 5000

    max_retries = 3

    connection_check_timeout_sec = 300

    properties {
      useUnicode = true
      characterEncoding = "utf8"
      serverTimezone = "Asia/Shanghai"

      rewriteBatchedStatements = "true"
      useCompression = "true"
      useServerPrepStmts = "false"
    }
  }
}

常用参数：

参数	示例	作用
`url`	`jdbc:mysql://127.0.0.1:6033`	MySQL JDBC 地址
`driver`	`com.mysql.cj.jdbc.Driver`	JDBC Driver
`user` / `username`	`cdcadmin`	数据库用户
`password`	`******`	数据库密码
`database`	`targetdb`	目标数据库
`table`	`${table_name}`	目标表

官方 JDBC Sink 中，url、driver 是核心连接参数；使用自动生成 SQL 模式时，需要配置 database，通常还需要 table。

六、最重要的几个 JDBC Sink 参数

现在最需要重点掌握的一组。

参数	作用	CDC 重要性
`generate_sink_sql`	自动生成目标 SQL	⭐⭐⭐⭐⭐
`primary_keys`	指定主键	⭐⭐⭐⭐⭐
`enable_upsert`	是否启用 Upsert	⭐⭐⭐⭐⭐
`database`	目标数据库	⭐⭐⭐⭐
`table`	目标表	⭐⭐⭐⭐
`schema_save_mode`	目标表结构处理方式	⭐⭐⭐⭐
`data_save_mode`	目标已有数据处理方式	⭐⭐⭐⭐
`batch_size`	批量提交数量	⭐⭐⭐⭐
`max_retries`	失败重试次数	⭐⭐⭐
`auto_commit`	JDBC 自动提交	⭐⭐⭐
`is_exactly_once`	是否启用 Exactly Once	⭐⭐⭐

generate_sink_sql = true

让 JDBC Sink 自动根据目标表、字段、主键以及 CDC RowKind 等信息生成写入 SQL。
primary_keys

primary_keys = $"${primary_key}"$

官方说明中，primary_keys 用于支持自动生成 SQL 时的 insert、delete、update 等操作。
enable_upsert

enable_upsert = true
schema_save_mode

任务启动之前，目标表结构怎么处理。

值	含义
`RECREATE_SCHEMA`	删除并重新创建
`CREATE_SCHEMA_WHEN_NOT_EXIST`	不存在则创建，存在则跳过
`ERROR_WHEN_SCHEMA_NOT_EXIST`	不存在就报错
`IGNORE`	不处理表结构

schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"

复制代码

目标表存在？
       │
   ┌───┴───┐
   │       │
  是       否
   │       │
跳过     创建表

data_save_mode

这个和 schema_save_mode 非常容易混淆。

schema_save_mode：管表结构。

data_save_mode：管表里面已经存在的数据。

参数	含义
`DROP_DATA`	保留表结构，删除已有数据
`APPEND_DATA`	保留已有数据，继续写
`CUSTOM_PROCESSING`	执行自定义 SQL
`ERROR_WHEN_DATA_EXISTS`	已有数据则报错

batch_size

表示 JDBC 批量写入时：

复制代码

数据
 ↓
5000条
 ↓
executeBatch()
 ↓
MySQL

官方说明是：缓存记录达到 batch_size，或者达到 checkpoint 间隔时，会刷新到数据库。

一般：

100

500

1000

5000

10000

但不能简单认为：batch_size 越大 = 越快

因为还受到：

MySQL

网络

内存

redo/binlog

锁

SQL长度

max_retries

JDBC 批量提交失败后，最多重新尝试 3 次。

复制代码

executeBatch()
     ↓
失败
     ↓
Retry 1
     ↓
失败
     ↓
Retry 2
     ↓
失败
     ↓
Retry 3
     ↓
仍然失败
     ↓
任务失败

官方默认值为 0，也就是默认不重试

connection_check_timeout_sec

单位：秒

用于检查数据库连接/数据库操作是否在规定时间内完成。

官方 2.3.12 JDBC 默认值为 30 秒
auto_commit

控制 JDBC 是否自动提交事务。

简单理解：

复制代码

true
 ↓
JDBC 自动提交

false
 ↓
由 SeaTunnel / 事务机制控制提交

properties

复制代码

properties {
    useUnicode = true
    characterEncoding = "utf8"
    serverTimezone = "Asia/Shanghai"

    rewriteBatchedStatements = "true"
    useCompression = "true"
    useServerPrepStmts = "false"
}

这些实际上是：传递给 JDBC Driver 的额外连接参数。

参数	作用
`useUnicode`	Unicode 支持
`characterEncoding`	字符集
`serverTimezone`	时区
`rewriteBatchedStatements`	MySQL 批量 INSERT 优化
`useCompression`	JDBC 通信压缩
`useServerPrepStmts`	是否使用 Server Prepared Statement

table = "tablename"这个参数对你目前的多表CDC非常重要。table="{table_name}" 这个参数对你目前的多表 CDC 非常重要。 table = "tablename"这个参数对你目前的多表CDC非常重要。table="{table_name}":意味着目标表名使用上游传来的表名。

例如：

复制代码

Oracle：

ANGER.CDC_ORDERS
ANGER.TEST_CDC_ORDERS

目标：

复制代码

targetdb.CDC_ORDERS
targetdb.TEST_CDC_ORDERS

官方 JDBC Sink 支持 tablename、{table_name}、tablename、{schema_name} 等变量。

七、query 和 generate_sink_sql 的区别

这是非常重要的一组。

自动生成 SQL

generate_sink_sql = true

database = "targetdb"

table = "${table_name}"

SeaTunnel 自己生成 SQL。

适合：

CDC

多表同步

自动建表

INSERT

UPDATE

DELETE

UPSERT

自定义 SQL，表示：SQL 由你自己定义。

官方文档明确指出，query 和 generate_sink_sql 是两种互斥的 JDBC 写入模式。

query = "INSERT INTO xxx VALUES (?, ?, ?)"

所以不要这样：

generate_sink_sql = true

query = "..."

八、参考配置

参数	当前值	作用	重要程度
`execution.parallelism`	`2`	并行度	⭐⭐⭐⭐
`job.mode`	`STREAMING`	流式任务	⭐⭐⭐⭐⭐
`checkpoint.interval`	`10000`	Checkpoint 周期	⭐⭐⭐⭐
`url`	Oracle JDBC	Oracle 地址	⭐⭐⭐⭐⭐
`username`	`anger`	Oracle 用户	⭐⭐⭐⭐⭐
`password`	`******`	Oracle 密码	⭐⭐⭐⭐⭐
`database-names`	`SJZTNCDB`	Oracle DB	⭐⭐⭐⭐
`schema-names`	`ANGER`	Oracle Schema	⭐⭐⭐⭐⭐
`table-names`	2张表	CDC 表范围	⭐⭐⭐⭐⭐
`startup.mode`	`initial`	初始快照方式	⭐⭐⭐⭐⭐
`generate_sink_sql`	`true`	自动生成 Sink SQL	⭐⭐⭐⭐⭐
`database`	`targetdb`	MySQL DB	⭐⭐⭐⭐⭐
`table`	`${table_name}`	目标表	⭐⭐⭐⭐⭐
`primary_keys`	`${primary_key}`	主键	⭐⭐⭐⭐⭐
`enable_upsert`	默认 `true`	Upsert	⭐⭐⭐⭐⭐
`schema_save_mode`	`CREATE_SCHEMA_WHEN_NOT_EXIST`	表结构处理	⭐⭐⭐⭐
`data_save_mode`	`APPEND_DATA`	已有数据处理	⭐⭐⭐⭐
`batch_size`	`5000`	批量提交数量	⭐⭐⭐⭐
`max_retries`	`3`	失败重试	⭐⭐⭐
`connection_check_timeout_sec`	`300`	连接检查超时	⭐⭐⭐
`properties`	MySQL 参数	JDBC Driver 参数	⭐⭐⭐⭐

尤其要注意：schema_save_mode / data_save_mode 管的是"任务启动前目标端怎么处理"，而 generate_sink_sql / primary_keys / enable_upsert 更直接关系到 CDC 数据运行过程中如何写入目标库。官方也明确区分了 Write Mode 和 Save Mode。