企业官网建设流程全解析

TDengine 零代码接入 MySQL：从历史迁移到实时同步的完整实践指南

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

本篇指南基于 TDengine 官方文档，讲解如何通过 taosExplorer 图形界面创建 MySQL 到 TDengine 的数据写入任务，覆盖新增数据源、连接与认证配置、SQL 查询模板、时间占位符、数据映射与异常处理策略等全部配置环节，并结合文档仓库中的配套资料拆解子表拆分、乱序规避与断点恢复等关键机制。读完本文，你能够独立完成一个从 MySQL 迁移历史数据并持续同步实时数据的任务。

功能概述与版本要求

MySQL 是最流行的关系型数据库之一，很多系统都曾经或正在使用 MySQL 存储物联网、工业互联网等设备上报的数据。但随着接入系统设备量日益增长、用户对数据实时性反馈的要求不断提高，MySQL 往往已无法满足业务需求。

自TDengine 企业版 3.3.0.0开始，TDengine 可以高效地从 MySQL 读取数据并写入 TDengine，支持两种典型场景：

1. 历史数据迁移：指定「起始时间」与「结束时间」，将存量数据一次性搬迁到 TDengine；
2. 实时数据同步：「结束时间」留空，任务持续拉取增量数据，不会自动停止。

在数据源支持范围上，官方文档的零代码写入总览页列明 MySQL 的受支持版本为5.6、5.7、8.0+（见 零代码数据写入总览 中的数据源表），使用该能力前请确认源库版本在此范围内，且运行的是 TDengine 企业版（该写入平台由 taosExplorer 与 taosX 组件提供，社区版不包含 taosX）。

创建 MySQL 写入任务

1. 进入新增数据源页面

登录 taosExplorer 后，在左侧导航进入数据写入页面，点击+新增数据源按钮进入新增数据源页面：

2. 配置基本信息

• 名称：任务名称，例如test_mysql_01；
• 类型：在下拉框中选择MySQL，选择完成后页面字段会随之变化；
• 代理：非必填项。如有需要可选择指定代理，也可点击右侧+创建新的代理按钮新建；
• 目标数据库：必填项，可点击右侧+创建数据库按钮先创建一个 TDengine 数据库作为数据落库位置。

3. 配置连接信息与认证信息

在连接配置区域填写源 MySQL 数据库的连接信息（主机地址、端口等）：

随后在认证区域填写：

• 用户：源 MySQL 数据库的用户，该用户必须拥有读取权限；
• 密码：上方用户的登录密码。

4. 配置连接选项

字符集：设置连接的字符集，默认utf8mb4（MySQL 5.5.3 及以上支持该字符集；如需连接旧版本，建议改为utf8）。可选项为：

utf8、utf8mb4、utf16、utf32、gbk、big5、latin1、ascii

SSL 模式：设置是否与服务器协商安全 SSL TCP/IP 连接或以何种优先级协商，默认值为PREFERRED。可选项：

填写完成后，点击检查连通性按钮，验证上述信息能否正常读取源 MySQL 数据库的数据。连通性检查是后续步骤的基础，建议在提交任务前确认通过。

5. 配置 SQL 查询（采集配置）

这是 MySQL 数据源最核心的区域，决定了「从哪里查、按什么节奏查」。

子表字段

用于拆分子表的字段，是一条select distinct的 SQL 语句，查询指定字段组合的非重复项，通常与 transform 中的 tag 相对应。此项配置主要为了解决数据迁移乱序问题，需要结合SQL 模板共同使用，否则不能达到预期效果。典型用法分三步：

1. 子表字段填写select distinct col_name1, col_name2 from table，表示使用源表中的col_name1与col_name2拆分目标超级表的子表；
2. 在 SQL 模板中添加入参占位符，例如select * from table where ts >= ${start} and ts < ${end} and ${col_name1} and ${col_name2}。运行时${col_name1}、${col_name2}会展开为等值条件（如col_name1='deviceA'、col_name2=1），而不是裸列名；
3. 在transform中配置col_name1与col_name2两个 tag 映射。

SQL 模板

用于查询的 SQL 语句模板。约束条件为：SQL 语句中必须包含时间范围条件，且开始时间和结束时间必须成对出现。模板中的时间范围由源数据库中代表时间的列与下列占位符组合而成：

为避免迁移数据乱序，建议在查询语句中添加排序条件，例如order by ts asc。

起始时间（必填）：迁移数据的起始时间。

结束时间（可留空）：设置后，任务执行到结束时间即自动停止；留空则持续同步实时数据，任务不会自动停止。

查询间隔：分段查询数据的时间间隔，默认1 天。为避免一次查询数据量过大，每个同步子任务会按查询间隔拆分时间段分批查询。

延迟时长：与查询间隔配合使用。在实时同步场景中，为避免延迟到达（迟到）的数据丢失，每次同步会在「时间间隔 + 延迟时长」的时间点触发查询。例如：查询间隔为 3600s、延迟时长为 60s，则查询任务会在 09:01 触发，查询源数据库中 08:00–09:00 时间段的数据。

6. 配置数据映射

在数据映射区域填写映射相关参数：

1. 点击从服务器检索按钮，从 MySQL 服务器获取示例数据；
2. 从列中提取或拆分：填写从字段中提取或拆分的规则。例如将vValue字段拆分成vValue_0和vValue_1两个字段：选择split提取器，separator 填写分割符,，number 填写2；
3. 过滤：填写过滤条件。例如填写Value > 0，则只有 Value 大于 0 的数据才会被写入 TDengine；
4. 映射：选择要映射到 TDengine 的超级表，以及映射到超级表的列；
5. 点击预览查看映射结果，确认无误后再提交。

这里的提取、过滤与映射能力属于零代码写入平台通用的内置 ETL 能力：解析（JSON Path/正则）、从列中提取或拆分（split/正则/转换）、过滤（布尔表达式）、映射（字段到超级表列的转换）。更完整的表达式语法与函数列表（如parse_int、between_time_range、format 格式化、expr 数学运算等）见 零代码数据写入总览中的数据提取、过滤和转换章节。

7. 配置高级选项

高级选项区域默认折叠，点击右侧>展开。不同数据源展示的字段略有差异，MySQL 常见配置项（见 高级选项说明）：

• 最大读取并发数：限制数据源连接数或读取线程数，默认0表示由采集器自动配置，数据源响应较慢时可适当增大；
• 批次大小：单次发送的最大消息数或行数，默认值因数据源而异（常见为1000或10000）；
• 写入并发数量：部分数据源提供，表示同时写入 TDengine 的并发任务数；
• 健康监测选项：健康监测时段、Busy 状态阈值、写入队列长度、写入错误阈值等，用于配合任务列表中的健康状态展示。

8. 配置异常处理策略

异常处理策略区域同样默认折叠（见 异常处理策略说明）。通用处理策略有三种：归档（写入归档文件，不写入目标库）、丢弃（忽略）、报错（任务报错）。MySQL 同步任务中常见的异常项及可选策略包括：

此外还有归档与缓存的存储参数：连接超时（1~600 秒）、临时存储文件位置（实际生效为${data_dir}/tasks/:id/{location}）、归档数据保留天数、归档数据可用空间、归档数据文件位置、归档失败处理策略（删除旧文件/丢弃/报错并停止任务）等。对于迁移历史数据这类长周期任务，建议将关键异常项配置为「归档」，配合保留天数便于事后补数。

9. 提交任务并查看执行情况

点击提交按钮，即完成 MySQL 到 TDengine 的数据同步任务创建。回到数据源列表页面可查看任务状态与执行情况；任务提交成功后状态切换为「运行中」，失败时可通过任务的活动日志查找错误原因。

断点恢复与任务可靠性

从文档仓库的总览页可以看出，taosX 的 MySQL 数据源支持断点恢复：MySQL（以及 PostgreSQL、Oracle、SQL Server、MongoDB 等）会持久化记录上次查询的时间戳，任务重新启动后从记录的时间戳继续查询，不会从头重扫。结合上文「延迟时长」机制——查询时间点滞后于数据到达时间——二者共同降低了重启与迟报两类场景下丢数的风险。

另外，自v3.3.5.0起任务管理列表提供健康状态（Ready/Idle/Active/Pending/Busy/Bounce/SourceError/SinkError/Fatal 等），配合高级选项中的健康监测阈值，可以直观判断 MySQL 同步任务是否出现源端错误、写入积压或数据异常（状态含义见 总览页健康状态章节）。

关键配置速查

参考文档

• MySQL 数据接入原始文档
• 零代码数据写入总览（数据源支持列表、ETL 能力、健康状态、断点恢复）
• 高级选项说明
• 异常处理策略说明
• 同类关系型数据源：PostgreSQL、Oracle、SQL Server

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine