跳到主要内容

关系型数据库集成

本节介绍 TDengine 与主流关系型数据库的整体集成方案,包括支持的数据库、同步模式、字段映射、数据类型转换、事务一致性与数据校验。各数据库的任务创建步骤见对应页面:达梦、MySQL、Oracle、PostgreSQL、SQL Server。

方案概述​

工业、能源、电力等行业的大量设备数据、业务数据和测点台账存放在关系型数据库中。TDengine 企业版通过 taosX 和 taosExplorer 提供统一的关系型数据库接入能力:

  • 统一接入:在 taosExplorer 中以相同的页面结构配置达梦、MySQL、Oracle、PostgreSQL、SQL Server 等数据源,各数据库使用各自的原生协议连接,无需编写代码。
  • 多格式数据:源表可以是每行一个测点值的窄表,也可以是每行多个测量值的宽表;文本列中的 JSON、分隔符字符串等可以在映射阶段拆分为多个字段。
  • 三种同步模式:全量迁移、增量同步和定时同步,见 同步模式。
  • 可视化映射:在页面上完成源字段到超级表列、标签和子表名的映射,并预览转换结果,见 字段映射。
  • 类型自动转换:按统一规则把源数据库类型转换为 TDengine 类型,见 数据类型转换。
  • 一致性与校验:只读取已提交的数据,按窗口保存断点、幂等写入,并支持逐窗口核对行数和摘要,确保同步结果与源数据一致,见 事务一致性 和 数据校验。

数据流转过程如下:

  1. taosX(或部署在源库网络内的 taosX-Agent)按 SQL 模板和时间窗口查询源数据库。
  2. 查询结果经过提取、过滤和映射,转换为 TDengine 的超级表、子表和列。
  3. 数据写入 TDengine。写入成功后保存该窗口的断点;开启数据校验时,先完成校验再保存断点。

支持的数据库​

数据库支持版本连接方式全量迁移增量同步定时同步
达梦DM8达梦 DPI 接口支持支持支持
MySQL5.6、5.7、8.0 及以上MySQL 协议支持支持支持
Oracle11g、12c、19cOracle OCI支持支持支持
PostgreSQL15.0 及以上PostgreSQL 协议支持支持—
SQL Server2012、2022TDS 协议支持支持—

说明:

  • 兼容 MySQL 协议的数据库(如 MariaDB、Apache Doris)可以使用 MySQL 数据源接入,注意事项见 MySQL。

同步模式​

三种模式使用同一套参数:起始时间、结束时间、查询间隔、延迟时长 和 定时计划。根据参数组合,任务以不同的模式运行:

模式参数组合运行方式结束条件典型场景
全量迁移设置起始时间和结束时间,定时计划选择 持续同步从起始时间开始按查询间隔逐窗口读取,直到结束时间读完结束时间前的数据后自动停止历史数据一次性迁移
增量同步设置起始时间,结束时间留空,定时计划选择 持续同步读完历史数据后,持续按查询间隔读取新数据不自动停止源库持续写入,需要准实时同步
定时同步设置起始时间,定时计划选择 定时窗口同步,配置调度周期或 Cron 表达式每次触发时从断点读取到安全水位,处理完后等待下一次触发设置了结束时间时,断点到达结束时间后任务完成源库按批次入库,或需要避开业务高峰时段

全量迁移​

全量迁移用于把源库中一段时间的历史数据完整迁移到 TDengine。

  1. 起始时间 设为源数据中最早的时间,结束时间 设为迁移截止时间。
  2. 查询间隔 决定单次查询的时间跨度。数据密集时减小间隔,避免单次查询数据量过大;数据稀疏时增大间隔,减少查询次数。
  3. 在 SQL 模板 中加入 ORDER BY 时间列,保证按时间顺序写入。
  4. 任务执行中断后重新启动,会从最后一个成功的窗口继续,不会从头开始。

迁移完成后,任务状态变为 已完成。如需在迁移后继续同步新数据,可以复制该任务,将起始时间设为原结束时间、结束时间留空,改为增量同步。

增量同步​

增量同步在完成历史数据读取后,持续读取源库的新数据。

  • 游标列:SQL 模板中的时间条件应使用能反映数据写入顺序的列,推荐使用入库时间或更新时间列,而不是设备的采集时间。采集时间可能乱序,以它为游标会漏读晚到的数据。
  • 延迟时长:每个窗口在 窗口结束时间 + 延迟时长 后才查询,给源库中尚未提交的事务留出时间。延迟时长应大于源库中最长写入事务的持续时间。
  • 捕获范围:增量同步按游标列读取新增或更新的行。源表中更新的行,只要游标列随更新刷新,就会被重新读取并按主键覆盖写入 TDengine。源表中删除的行不会同步删除。

定时同步​

定时同步按计划触发,每次触发处理从断点到安全水位(当前时间减去延迟时长)之间的窗口。

  • 调度方式:可以设置首次计划时刻和固定调度周期(分钟),也可以设置五字段分钟级 Cron 表达式。调度使用 taosExplorer 页面当前时区。
  • 单轮最多窗口数:限制每次触发读取的窗口数,控制单轮对源库的查询压力。积压的窗口在后续触发中继续处理。
  • 失败重试:某一轮失败后任务显示为失败,调度计划保留,下一次触发时从未确认的窗口重试。

配置示例见 Oracle · 定时窗口同步示例,达梦和 MySQL 的配置方式相同。

断点续传​

三种模式都以窗口为单位保存断点。断点保存在 taosX 中,任务停止、taosX 重启或 taosX-Agent 断线恢复后,都从最后一个成功的窗口之后继续读取。

字段映射​

字段映射在任务的 数据映射 区域配置,决定源数据的每一列写入 TDengine 的哪个位置。

映射对象​

源数据映射目标说明
时间列超级表主键时间戳列必须映射,每行数据必须有非空时间
测点 / 设备标识列子表名、标签通过 子表名称 模板生成子表名,例如 meter_{METER_ID}
测点属性列(位置、型号等)标签测点属性写入标签,可通过 SELECT 查询,并可通过 UPDATE 修改
测量值列普通数据列列名可以与源列名不同
唯一区分同一时间多行的列复合主键列同一测点在同一时间有多行数据时必须配置,见 事务一致性

映射方式​

  1. 点击 从服务器检索,按 SQL 模板从源库获取示例数据。
  2. 选择目标超级表。超级表不存在时,可以根据示例数据自动生成超级表结构,列类型按 数据类型转换 规则推导,生成后可以手动调整。
  3. 系统按列名自动匹配源字段和目标列(不区分大小写)。名称不同的列可以在下拉框中手动选择源字段,也可以填写表达式,例如 VOLTAGE / 1000、CONCAT(AREA, '-', LINE)。
  4. 不需要写入的源字段保持未映射即可。
  5. 点击 预览,确认映射后的子表名、标签和列值符合预期。

宽表与窄表​

  • 宽表:每行包含一个设备的多个测量值,例如 (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_TSts使用采集时间作为主键
METER_ID子表名 meter_{METER_ID}、标签 meter_id每个电表一张子表
LOCATION标签 location中文位置信息使用 NCHAR
VOLTAGEvoltage精度不变
CURRENT_Acurrent列名不同,手动映射
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 类型;写入已有超级表时,源值会转换为目标列的类型,无法转换时按 异常处理策略 处理。

类型对照​

类别达梦MySQLOracleTDengine说明
布尔BIT、BOOLEANBOOLEAN、BIT(1)BOOLEAN(23ai)BOOL
1 字节整数TINYINT、BYTETINYINT—TINYINTMySQL 无符号类型转换为 TINYINT UNSIGNED
2 字节整数SMALLINTSMALLINT—SMALLINTMySQL 无符号类型转换为 SMALLINT UNSIGNED
4 字节整数INT、INTEGERINT、MEDIUMINT—INTMySQL 无符号类型转换为 INT UNSIGNED
8 字节整数BIGINTBIGINT—BIGINTMySQL 无符号类型转换为 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—NUMBERDOUBLE未指定精度的 NUMBER
单精度浮点REAL、FLOAT(p ≤ 24)FLOATBINARY_FLOATFLOAT
双精度浮点DOUBLE、DOUBLE PRECISION、FLOATDOUBLEBINARY_DOUBLE、FLOATDOUBLE
字符串CHAR、VARCHAR、VARCHAR2CHAR、VARCHARCHAR、VARCHAR2、NCHAR、NVARCHAR2NCHAR(n)默认转换为 NCHAR 以保留中文;只含 ASCII 字符时可改为 VARCHAR
大文本TEXT、CLOB、LONGVARCHARTEXT、MEDIUMTEXT、LONGTEXTCLOB、NCLOB、LONGNCHAR / VARCHAR普通列最大 65,517 字节,超出时按 列长度溢出 策略处理
二进制BINARY、VARBINARYBINARY、VARBINARYRAWVARBINARY
大二进制BLOB、IMAGE、LONGVARBINARYBLOB、MEDIUMBLOB、LONGBLOBBLOB、LONG RAWBLOB单值最大 16 MB
日期时间DATE、TIMESTAMP、DATETIMEDATE、DATETIME、TIMESTAMPDATE、TIMESTAMPTIMESTAMP时区与精度规则见下文
带时区时间TIMESTAMP WITH TIME ZONE、DATETIME WITH TIME ZONE—TIMESTAMP WITH TIME ZONE、TIMESTAMP WITH LOCAL TIME ZONETIMESTAMP按时区换算为绝对时间
仅时间TIMETIME—VARCHAR(18)以 HH:MI:SS[.ffffff] 格式的字符串写入
JSONJSONJSONJSON(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 执行以下核对:

  1. 行数平衡:源库读取行数 = 写入成功行数 + 过滤行数 + 按异常策略丢弃或归档的行数。
  2. 落库核对:在 TDengine 中按窗口时间范围和映射的子表查询行数,与写入成功行数一致。
  3. 逐值核对(仅行数和摘要校验):对写入成功的数据按映射后的列值计算摘要,与从 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 中创建关系型数据库同步任务的通用流程如下,各数据库的具体字段见对应页面:

  1. 进入 数据写入 页面,点击 +新增数据源,选择数据库类型,填写任务名称和目标数据库。
  2. 填写连接信息和认证信息,点击 检查连通性。
  3. 编写 SQL 模板,设置起始时间、结束时间、查询间隔、延迟时长和定时计划,确定同步模式。
  4. 在 数据映射 中配置子表名、标签和列的映射,点击 预览 确认结果。
  5. 在 高级选项 中设置读写并发、批次大小和数据校验。
  6. 设置异常处理策略。
  7. 点击 提交,在任务列表中查看运行状态、写入行数和校验结果。