关系型数据库集成
本节介绍 TDengine 与主流关系型数据库的整体集成方案,包括支持的数据库、同步模式、字段映射、数据类型转换、事务一致性与数据校验。各数据库的任务创建步骤见对应页面:达梦、MySQL、Oracle、PostgreSQL、SQL Server。
方案概述
工业、能源、电力等行业的大量设备数据、业务数据和测点台账存放在关系型数据库中。TDengine 企业版通过 taosX 和 taosExplorer 提供统一的关系型数据库接入能力:
- 统一接入:在 taosExplorer 中以相同的页面结构配置达梦、MySQL、Oracle、PostgreSQL、SQL Server 等数据源,各数据库使用各自的原生协议连接,无需编写代码。
- 多格式数据:源表可以是每行一个测点值的窄表,也可以是每行多个测量值的宽表;文本列中的 JSON、分隔符字符串等可以在映射阶段拆分为多个字段。
- 三种同步模式:全量迁移、增量同步和定时同步,见 同步模式。
- 可视化映射:在页面上完成源字段到超级表列、标签和子表名的映射,并预览转换结果,见 字段映射。
- 类型自动转换:按统一规则把源数据库类型转换为 TDengine 类型,见 数据类型转换。
- 一致性与校验:只读取已提交的数据,按窗口保存断点、幂等写入,并支持逐窗口核对行数和摘要,确保同步结果与源数据一致,见 事务一致性 和 数据校验。
数据流转过程如下:
- taosX(或部署在源库网络内的 taosX-Agent)按 SQL 模板和时间窗口查询源数据库。
- 查询结果经过提取、过滤和映射,转换为 TDengine 的超级表、子表和列。
- 数据写入 TDengine。写入成功后保存该窗口的断点;开启数据校验时,先完成校验再保存断点。
支持的数据库
| 数据库 | 支持版本 | 连接方式 | 全量迁移 | 增量同步 | 定时同步 |
|---|---|---|---|---|---|
| 达梦 | DM8 | 达梦 DPI 接口 | 支持 | 支持 | 支持 |
| MySQL | 5.6、5.7、8.0 及以上 | MySQL 协议 | 支持 | 支持 | 支持 |
| Oracle | 11g、12c、19c | Oracle OCI | 支持 | 支持 | 支持 |
| PostgreSQL | 15.0 及以上 | PostgreSQL 协议 | 支持 | 支持 | — |
| SQL Server | 2012、2022 | TDS 协议 | 支持 | 支持 | — |
说明:
- 兼容 MySQL 协议的数据库(如 MariaDB、Apache Doris)可以使用 MySQL 数据源接入,注意事项见 MySQL。
同步模式
三种模式使用同一套参数:起始时间、结束时间、查询间隔、延迟时长 和 定时计划。根据参数组合,任务以不同的模式运行:
| 模式 | 参数组合 | 运行方式 | 结束条件 | 典型场景 |
|---|---|---|---|---|
| 全量迁移 | 设置起始时间和结束时间,定时计划选择 持续同步 | 从起始时间开始按查询间隔逐窗口读取,直到结束时间 | 读完结束时间前的数据后自动停止 | 历史数据一次性迁移 |
| 增量同步 | 设置起始时间,结束时间留空,定时计划选择 持续同步 | 读完历史数据后,持续按查询间隔读取新数据 | 不自动停止 | 源库持续写入,需要准实时同步 |
| 定时同步 | 设置起始时间,定时计划选择 定时窗口同步,配置调度周期或 Cron 表达式 | 每次触发时从断点读取到安全水位,处理完后等待下一次触发 | 设置了结束时间时,断点到达结束时间后任务完成 | 源库按批次入库,或需要避开业务高峰时段 |
全量迁移
全量迁移用于把源库中一段时间的历史数据完整迁移到 TDengine。
- 起始时间 设为源数据中最早的时间,结束时间 设为迁移截止时间。
- 查询间隔 决定单次查询的时间跨度。数据密集时减小间隔,避免单次查询数据量过大;数据稀疏时增大间隔,减少查询次数。
- 在 SQL 模板 中加入
ORDER BY时间列,保证按时间顺序写入。 - 任务执行中断后重新启动,会从最后一个成功的窗口继续,不会从头开始。
迁移完成后,任务状态变为 已完成。如需在迁移后继续同步新数据,可以复制该任务,将起始时间设为原结束时间、结束时间留空,改为增量同步。
增量同步
增量同步在完成历史数据读取后,持续读取源库的新数据。
- 游标列:SQL 模板中的时间条件应使用能反映数据写入顺序的列,推荐使用入库时间或更新时间列,而不是设备的采集时间。采集时间可能乱序,以它为游标会漏读晚到的数据。
- 延迟时长:每个窗口在
窗口结束时间 + 延迟时长后才查询,给源库中尚未提交的事务留出时间。延迟时长应大于源库中最长写入事务的持续时间。 - 捕获范围:增量同步按游标列读取新增或更新的行。源表中更新的行,只要游标列随更新刷新,就会被重新读取并按主键覆盖写入 TDengine。源表中删除的行不会同步删除。
定时同步
定时同步按计划触发,每次触发处理从断点到安全水位(当前时间减去延迟时长)之间的窗口。
- 调度方式:可以设置首次计划时刻和固定调度周期(分钟),也可以设置五字段分钟级 Cron 表达式。调度使用 taosExplorer 页面当前时区。
- 单轮最多窗口数:限制每次触发读取的窗口数,控制单轮对源库的查询压力。积压的窗口在后续触发中继续处理。
- 失败重试:某一轮失败后任务显示为失败,调度计划保留,下一次触发时从未确认的窗口重试。
配置示例见 Oracle · 定时窗口同步示例,达梦和 MySQL 的配置方式相同。
断点续传
三种模式都以窗口为单位保存断点。断点保存在 taosX 中,任务停止、taosX 重启或 taosX-Agent 断线恢复后,都从最后一个成功的窗口之后继续读取。
字段映射
字段映射在任务的 数据映射 区域配置,决定源数据的每一列写入 TDengine 的哪个位置。
映射对象
| 源数据 | 映射目标 | 说明 |
|---|---|---|
| 时间列 | 超级表主键时间戳列 | 必须映射,每行数据必须有非空时间 |
| 测点 / 设备标识列 | 子表名、标签 | 通过 子表名称 模板生成子表名,例如 meter_{METER_ID} |
| 测点属性列(位置、型号等) | 标签 | 测点属性写入标签,可通过 SELECT 查询,并可通过 UPDATE 修改 |
| 测量值列 | 普通数据列 | 列名可以与源列名不同 |
| 唯一区分同一时间多行的列 | 复合主键列 | 同一测点在同一时间有多行数据时必须配置,见 事务一致性 |
映射方式
- 点击 从服务器检索,按 SQL 模板从源库获取示例数据。
- 选择目标超级表。超级表不存在时,可以根据示例数据自动生成超级表结构,列类型按 数据类型转换 规则推导,生成后可以手动调整。
- 系统按列名自动匹配源字段和目标列(不区分大小写)。名称不同的列可以在下拉框中手动选择源字段,也可以填写表达式,例如
VOLTAGE / 1000、CONCAT(AREA, '-', LINE)。 - 不需要写入的源字段保持未映射即可。
- 点击 预览,确认映射后的子表名、标签和列值符合预期。
宽表与窄表
- 宽表:每行包含一个设备的多个测量值,例如
(TS, DEVICE_ID, VOLTAGE, CURRENT, PHASE)。每个测量值列映射到超级表的一个普通列。 - 窄表:每行只包含一个测点的一个值,例如
(TS, TAG_NAME, VALUE, QUALITY)。通常以TAG_NAME生成子表名,VALUE和QUALITY映射为普通列,测点属性映射为标签。 - 文本中的复合数据:使用 从列中提取或拆分,按分隔符、正则表达式或 JSON 路径从一个文本列提取多个字段,再参与映射。
映射示例
源库中的电表读数表结构如下:
CREATE TABLE METER_READINGS (
ID BIGINT PRIMARY KEY,
METER_ID VARCHAR(32),
LOCATION VARCHAR(64),
READING_TS TIMESTAMP,
INGEST_TS TIMESTAMP,
VOLTAGE DECIMAL(10, 3),
CURRENT_A DOUBLE
);
映射到 TDengine 超级表 meters(ts TIMESTAMP, voltage DECIMAL(10, 3), current DOUBLE) TAGS (meter_id VARCHAR(32), location NCHAR(64)):
| 源字段 | 目标 | 说明 |
|---|---|---|
READING_TS | ts | 使用采集时间作为主键 |
METER_ID | 子表名 meter_{METER_ID}、标签 meter_id | 每个电表一张子表 |
LOCATION | 标签 location | 中文位置信息使用 NCHAR |
VOLTAGE | voltage | 精度不变 |
CURRENT_A | current | 列名不同,手动映射 |
INGEST_TS | 不写入 | 仅在 SQL 模板中作为增量游标 |
ID | 不写入 | — |
对应的 SQL 模板:
SELECT METER_ID, LOCATION, READING_TS, INGEST_TS, VOLTAGE, CURRENT_A
FROM METER_READINGS
WHERE INGEST_TS >= ${start} AND INGEST_TS < ${end}
ORDER BY INGEST_TS, ID
数据类型转换
taosX 读取源数据后,按下表把源数据库类型转换为 TDengine 类型。自动生成超级表时使用表中的 TDengine 类型;写入已有超级表时,源值会转换为目标列的类型,无法转换时按 异常处理策略 处理。
类型对照
| 类别 | 达梦 | MySQL | Oracle | TDengine | 说明 |
|---|---|---|---|---|---|
| 布尔 | BIT、BOOLEAN | BOOLEAN、BIT(1) | BOOLEAN(23ai) | BOOL | |
| 1 字节整数 | TINYINT、BYTE | TINYINT | — | TINYINT | MySQL 无符号类型转换为 TINYINT UNSIGNED |
| 2 字节整数 | SMALLINT | SMALLINT | — | SMALLINT | MySQL 无符号类型转换为 SMALLINT UNSIGNED |
| 4 字节整数 | INT、INTEGER | INT、MEDIUMINT | — | INT | MySQL 无符号类型转换为 INT UNSIGNED |
| 8 字节整数 | BIGINT | BIGINT | — | BIGINT | MySQL 无符号类型转换为 BIGINT UNSIGNED |
| 定点数 | NUMBER(p,s)、DECIMAL(p,s)、NUMERIC(p,s) | DECIMAL(p,s) | NUMBER(p,s) | DECIMAL(p,s) | p 不超过 38 时精度不变;p 超过 38 转换为 DOUBLE |
| 不定精度数值 | NUMBER | — | NUMBER | DOUBLE | 未指定精度的 NUMBER |
| 单精度浮点 | REAL、FLOAT(p ≤ 24) | FLOAT | BINARY_FLOAT | FLOAT | |
| 双精度浮点 | DOUBLE、DOUBLE PRECISION、FLOAT | DOUBLE | BINARY_DOUBLE、FLOAT | DOUBLE | |
| 字符串 | CHAR、VARCHAR、VARCHAR2 | CHAR、VARCHAR | CHAR、VARCHAR2、NCHAR、NVARCHAR2 | NCHAR(n) | 默认转换为 NCHAR 以保留中文;只含 ASCII 字符时可改为 VARCHAR |
| 大文本 | TEXT、CLOB、LONGVARCHAR | TEXT、MEDIUMTEXT、LONGTEXT | CLOB、NCLOB、LONG | NCHAR / VARCHAR | 普通列最大 65,517 字节,超出时按 列长度溢出 策略处理 |
| 二进制 | BINARY、VARBINARY | BINARY、VARBINARY | RAW | VARBINARY | |
| 大二进制 | BLOB、IMAGE、LONGVARBINARY | BLOB、MEDIUMBLOB、LONGBLOB | BLOB、LONG RAW | BLOB | 单值最大 16 MB |
| 日期时间 | DATE、TIMESTAMP、DATETIME | DATE、DATETIME、TIMESTAMP | DATE、TIMESTAMP | TIMESTAMP | 时区与精度规则见下文 |
| 带时区时间 | TIMESTAMP WITH TIME ZONE、DATETIME WITH TIME ZONE | — | TIMESTAMP WITH TIME ZONE、TIMESTAMP WITH LOCAL TIME ZONE | TIMESTAMP | 按时区换算为绝对时间 |
| 仅时间 | TIME | TIME | — | VARCHAR(18) | 以 HH:MI:SS[.ffffff] 格式的字符串写入 |
| JSON | JSON | JSON | JSON(21c) | NCHAR | 写入 JSON 文本,可先用 从列中提取或拆分 解析为多列 |
表中未列出的类型(如空间类型、INTERVAL、ROWID、数组和自定义类型),请在 SQL 模板中用 CAST 或数据库函数转换为字符串或数值后再读取。
时间与时区
- 无时区的时间类型(如
DATETIME、TIMESTAMP)按任务 时区 选项解释,默认使用 taosX 所在主机的时区。源库存储的是 UTC 时间时,请将任务时区设为UTC。 - 带时区的时间类型 按值中的时区换算,不受任务时区选项影响。
- 时间精度:目标数据库的精度应不低于源数据的时间精度。例如源数据精确到微秒,目标数据库应使用微秒或纳秒精度。目标精度低于源精度时,超出部分会被截断,原本不同的时间可能变为相同的时间戳并相互覆盖,导致行数减少。开启 数据校验 可以发现这类问题。
数值与字符串
- 数值写入范围更小的列时(如
BIGINT写入INT),超出范围的值按 数据异常 策略处理,不会被截断为错误的值。 - 定点数写入
DECIMAL列时保持精度;写入FLOAT或DOUBLE列时可能损失精度,对精度敏感的数据(如计量、结算数据)应使用DECIMAL。 - 字符串按源库字符集读取,统一转换为 UTF-8 写入。字符集需在连接配置中与源库一致,例如达梦使用 GB18030 时,连接字符集也应设为 GB18030。
NULL原样写入为NULL。
异常处理
类型转换失败、长度超限、时间戳为空等情况,按任务的 异常处理策略 处理,可选归档、丢弃、报错等方式。需要保证同步数据完整时,建议把 数据异常 和 列长度溢出 设为 报错,避免数据被静默丢弃或截断。
事务一致性
关系型数据库通过事务保证数据一致,TDengine 则以时间戳主键组织时序数据。集成方案从读取、写入和断点三个环节保证同步结果与源库已提交的数据一致。
只读取已提交的数据
- 每个窗口的数据由一条只读查询读取。达梦、Oracle 提供语句级一致性读,MySQL InnoDB 使用一致性快照读,查询结果反映某一时刻已提交的数据,不包含未提交事务的修改。
- taosX 只执行
SELECT,不对源表加锁,不影响源库业务写入。 - 源库事务提交时间可能晚于其中数据的时间。为避免窗口查询时事务尚未提交而漏读,延迟时长 应大于源库中最长写入事务的持续时间,并以入库时间列作为游标。
幂等写入
- TDengine 中同一张子表内主键相同的行只保留一行。重复写入同一行数据,结果不变。
- 一个窗口写入失败时,整个窗口重新读取、重新写入。已经写入的部分会被相同的数据覆盖,不会产生重复数据。
- 同一测点在同一时间有多行数据(例如同一时间的多次检测记录)时,必须在超级表上定义复合主键,并把能区分这些行的源字段映射为复合主键列。否则这些行会按时间戳互相覆盖,只保留最后一行。
断点原子推进
- 一个窗口内的全部数据写入成功后,才保存该窗口的断点;开启数据校验时,校验通过后才保存断点。
- 任务在窗口处理过程中中断,断点仍停留在上一个窗口,恢复后重新处理当前窗口。
- 因此每一行源数据最终在 TDengine 中恰好保留一份:不丢失,也不重复。
一致性范围
- 一个窗口涉及的多张子表可能分布在不同 vnode 上,写入过程中查询可能看到部分子表已写入、部分子表未写入的中间状态。窗口写入完成后,数据达到一致。
- 源库中被删除的行不会自动从 TDengine 中删除。需要同步删除时,请在源库使用逻辑删除标记列,并把该列映射到 TDengine,由查询过滤。
数据校验
达梦、MySQL、Oracle 数据源提供数据校验功能,逐窗口核对源数据与写入 TDengine 的数据,确保同步数据准确率 100%。
校验模式
在任务的 高级选项 中设置 数据校验:
| 模式 | 校验内容 | 开销 |
|---|---|---|
| 关闭 | 不校验,默认值 | 无 |
| 行数校验 | 核对每个窗口的源数据行数与 TDengine 中实际写入的行数 | 每个窗口在源库和 TDengine 各多执行一次计数查询 |
| 行数和摘要校验 | 在行数校验的基础上,对每个窗口的数据按主键排序后计算 SM3 摘要,核对源数据与 TDengine 中的数据是否逐值一致 | 需要回读窗口内已写入的数据,查询量约增加一倍 |
校验规则
每个窗口写入完成后,taosX 执行以下核对:
- 行数平衡:
源库读取行数 = 写入成功行数 + 过滤行数 + 按异常策略丢弃或归档的行数。 - 落库核对:在 TDengine 中按窗口时间范围和映射的子表查询行数,与写入成功行数一致。
- 逐值核对(仅行数和摘要校验):对写入成功的数据按映射后的列值计算摘要,与从 TDengine 回读的同一批数据的摘要一致。浮点数按目标列类型的精度比较。
全部核对通过后保存断点。任一项不一致时,按 校验失败策略 处理:
- 重做窗口(默认):重新读取并写入该窗口,最多重试 校验重试次数(默认 3)次,仍不一致则任务报错。
- 报错停止:立即停止任务,保留断点,等待人工处理。
查看校验结果
在任务详情页的 数据校验 页签中,可以查看每个窗口的校验记录,包括窗口时间范围、源库读取行数、写入行数、过滤行数、异常行数、校验结果和重试次数。可以按校验结果筛选,并导出为 CSV 作为数据核对报告。
同步完成后,也可以分别在源库和 TDengine 中执行汇总查询,人工复核:
-- 源库(以达梦为例)
SELECT COUNT(*), SUM(VOLTAGE) FROM METER_READINGS
WHERE READING_TS >= '2024-01-01 00:00:00' AND READING_TS < '2024-02-01 00:00:00';
-- TDengine
SELECT COUNT(*), SUM(voltage) FROM meters
WHERE ts >= '2024-01-01 00:00:00' AND ts < '2024-02-01 00:00:00';
保证准确率的前提
满足以下条件并开启 行数和摘要校验 后,所有窗口校验通过即表示 TDengine 中的数据与源库已提交的数据完全一致:
- 时间列和复合主键列能唯一标识源数据中的每一行,见 幂等写入。
- 目标数据库的时间精度不低于源数据的时间精度。
- 数据异常、列长度溢出 等异常处理策略设为 报错,或者确认被丢弃、归档的数据属于预期。
- 延迟时长覆盖源库中最长的写入事务。
配置流程
在 taosExplorer 中创建关系型数据库同步任务的通用流程如下,各数据库的具体字段见对应页面:
- 进入 数据写入 页面,点击 +新增数据源,选择数据库类型,填写任务名称和目标数据库。
- 填写连接信息和认证信息,点击 检查连通性。
- 编写 SQL 模板,设置起始时间、结束时间、查询间隔、延迟时长和定时计划,确定同步模式。
- 在 数据映射 中配置子表名、标签和列的映射,点击 预览 确认结果。
- 在 高级选项 中设置读写并发、批次大小和数据校验。
- 设置异常处理策略。
- 点击 提交,在任务列表中查看运行状态、写入行数和校验结果。








