大网数据广告活动
数据库部署与 SQL 参考

OceanBase CDC 自动建表同步

· 52CE 我爱测

OceanBase CDC 自动建表同步通过 实现。Doris 从 OBBinlog 服务读取 OceanBase 的全量和增量数据,并根据上游表结构自动创建 Doris 主键表。可以通过 同步一张、多张或全部表。

Doris 持续导入为实验性功能,自 Doris 4.1.5 版本起支持。

OceanBase CDC 自动建表同步通过 FROM OCEANBASE (...) TO DATABASE (...) 实现。Doris 从 OBBinlog 服务读取 OceanBase 的全量和增量数据,并根据上游表结构自动创建 Doris 主键表。可以通过 include_tables 同步一张、多张或全部表。

目前仅支持 OceanBase 的 MySQL 兼容模式和自动建表同步,不支持 Oracle 兼容模式与 SQL 映射同步。

适用场景

  • 将 OceanBase 中的一组表或整个数据库镜像到 Doris。
  • 由 Doris 根据上游表结构和主键自动创建目标表。
  • 需要先完成全量初始化,再持续同步增量变更。
  • 只需要目标表重命名或列裁剪,不需要 SQL 表达式、行过滤或数据转换。

能力与限制

项目 说明
兼容模式 仅支持 OceanBase MySQL 兼容模式
同步方式 仅支持自动建表同步,不支持 SQL 映射同步
一致性语义 at-least-once
表类型 上游表必须有主键;自动创建的 Doris 表为主键模型表(Unique Key)
权限要求 需要 Load 权限;目标表不存在时还需要 Create 权限
Schema Change 支持同步 ADD COLUMN 和 DROP COLUMN,详见 Schema Change 同步
数据类型 复用 MySQL 兼容类型映射,详见 数据类型映射

前置准备

创建作业前,请确认:

  1. OceanBase 运行在 MySQL 兼容模式。Doris 创建作业时会执行 SHOW VARIABLES LIKE 'ob_compatibility_mode' 进行校验。
  2. OBBinlog 服务已部署并可用,通过其 MySQL 协议地址执行 SHOW MASTER STATUS 能返回有效的 Binlog 文件名和位点。
  3. Doris FE、BE 与 CDC Client 均可访问 OBBinlog 服务。
  4. 已准备兼容的 MySQL Connector/J 驱动;jdbc_url 必须以 jdbc:mysql:// 开头。
  5. 源端账号可以读取待同步表、表结构和 Binlog。
  6. 待同步的上游表具有主键。

快速上手

第一步:创建导入作业

以下示例同步 source_db 中的 users 和 orders 表:

CREATE JOB oceanbase_db_sync
ON STREAMING
FROM OCEANBASE (
    "jdbc_url" = "jdbc:mysql://127.0.0.1:2883",
    "driver_url" = "mysql-connector-j-8.4.0.jar",
    "driver_class" = "com.mysql.cj.jdbc.Driver",
    "user" = "root@test",
    "password" = "123456",
    "database" = "source_db",
    "include_tables" = "users,orders",
    "offset" = "initial"
)
TO DATABASE target_db (
    "table.create.properties.replication_num" = "1"
);
  • jdbc_url 应指向 OBBinlog 服务的 MySQL 协议端口,具体端口以实际部署为准。
  • offset = "initial" 表示先同步存量数据,再持续同步 Binlog 增量。
  • include_tables 未设置时,同步 database 中所有符合要求的表。
  • 单 BE 部署需要将 replication_num 设为 1;生产环境请按集群规模设置副本数。

第二步:查看导入状态

SELECT Name, Status, CurrentOffset, ErrorMsg
FROM jobs("type" = "insert")
WHERE Name = "oceanbase_db_sync";

作业正常运行时,Status 为 RUNNING:

+-------------------+---------+------------------------------------------------+----------+
| Name              | Status  | CurrentOffset                                  | ErrorMsg |
+-------------------+---------+------------------------------------------------+----------+
| oceanbase_db_sync | RUNNING | {"file":"binlog.000001","pos":"154", ...} | NULL     |
+-------------------+---------+------------------------------------------------+----------+

第三步:验证增量同步

在 OceanBase 源表执行 INSERT、UPDATE 或 DELETE 后,查询对应 Doris 表,确认变更已同步:

SELECT * FROM target_db.users ORDER BY id;

更多暂停、恢复、删除和 Task 查询操作请参见持续导入概览。

数据源参数

参数 是否必填 默认值 说明
jdbc_url 是 - OBBinlog 服务的 JDBC 连接串,必须以 jdbc:mysql:// 开头。
driver_url 是 - MySQL Connector/J 驱动 jar 包路径,支持文件名、本地绝对路径或 HTTP URL。
driver_class 是 - MySQL JDBC 驱动类名,例如 com.mysql.cj.jdbc.Driver。
user 是 - OceanBase 用户名;租户信息按 OceanBase 的用户名格式填写。
password 是 - OceanBase 用户密码。
database 是 - OceanBase 数据库名。
include_tables 否 - 要同步的表名,多个表用逗号分隔;不设置时同步数据库中的全部表。
exclude_tables 否 - 不同步的表名,多个表用逗号分隔;仅在未设置 include_tables 时生效。
table.<table_name>.target_table 否 源表名 为指定源表设置 Doris 目标表名。
table.<table_name>.exclude_columns 否 - 排除指定源表中的非主键列,多个列用逗号分隔。列必须存在,且不能排除主键列。
offset 否 latest initial:全量 + 增量;snapshot:仅全量;earliest:从当前可用的最早 Binlog 位点开始;latest:仅同步作业启动后的增量;也可使用 {"file":"binlog.000001","pos":"154"} 形式的精确位点。
schema_change_behavior 否 evolve 字符串,不区分大小写。evolve 自动同步支持的列变更,ignore 关闭结构同步。可暂停后通过 ALTER JOB 修改;支持范围及暂停处理见 Schema Change 同步。
snapshot_split_size 否 40960 全量阶段每个 split 包含的行数,必须为正整数。
snapshot_parallelism 否 1 全量阶段单个 Task 最多并行调度的 split 数,必须为正整数。
skip_snapshot_backfill 否 true 是否跳过快照期间的 Binlog 回填。自动建表同步采用 at-least-once 语义。
server_id 否 自动生成 CDC Reader 的 server ID,可设置单值(如 5400)或闭区间(如 5400-5408);区间内 ID 数量不得小于 snapshot_parallelism。
ssl_mode 否 disable SSL 模式,可选值为 disable、require、verify-ca。
ssl_rootcert 条件必填 - ssl_mode 为 verify-ca 时必填,格式为 FILE:<file_name>;需先通过 CREATE FILE 上传。

不支持 schema、slot_name 和 publication_name 参数。指定这些参数时,作业创建失败。

参考手册

导入命令

CREATE JOB <job_name>
[job_properties]
ON STREAMING
[COMMENT <comment>]
FROM OCEANBASE (
    [source_properties]
)
TO DATABASE <target_db> (
    [target_properties]
);
模块 说明
job_name 作业名称。
job_properties Job 通用参数,例如 max_interval 和 compute_group。
comment 作业备注。
source_properties OceanBase 数据源参数。
target_properties Doris 目标库参数。

Doris 目标库参数

参数 默认值 说明
table.create.properties.* - 自动建表时附加的表属性,例如 table.create.properties.replication_num。
load.strict_mode false 是否为 Stream Load 开启严格模式。
load.max_filter_ratio 0 采样窗口内允许的最大过滤率,范围为 [0, 1];超过该值时作业暂停。

注意事项与最佳实践

  • 生产作业建议先用少量表验证 OBBinlog 连通性、类型映射和增量延迟,再扩大同步范围。
  • 使用 include_tables 明确限定同步范围,避免数据库中新增的无关表进入作业。
  • 对不支持的列类型,可通过 table.<table_name>.exclude_columns 排除;不能排除主键列。
  • 修改不受支持的表结构前,先暂停作业,在 Doris 端完成兼容变更后再恢复。
  • 定期检查 CurrentOffset、LagBytes 和 ErrorMsg,确认作业持续推进且没有被自动暂停。

FAQ

Q1:是否支持 OceanBase Oracle 兼容模式?

不支持。创建作业时 Doris 会检查 ob_compatibility_mode,非 MySQL 兼容模式会直接拒绝创建。

Q2:是否支持 SQL 映射同步?

不支持。OceanBase 当前仅支持 FROM OCEANBASE (...) TO DATABASE (...) 自动建表同步。

Q3:如何只同步作业启动后的增量数据?

将 offset 设置为 latest。在作业进入 RUNNING 后再写入的数据会被同步,已有数据不会执行快照导入。

Q4:目标表已存在时会被覆盖吗?

不会。自动建表阶段会跳过已存在的目标表;请确保其主键和列类型与源表兼容。

相关文档

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。