企业官网建设流程全解析

TDengine 零代码数据接入：通过 taosExplorer 将 MySQL 数据迁移/同步至 TDengine 完整指南

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

本文是 TDengine 零代码数据接入系列中针对 MySQL 数据源的操作指南，完整讲解如何在 taosExplorer 图形界面中创建从 MySQL 到当前 TDengine 集群的数据迁移与实时同步任务。读者将掌握数据源与认证配置、字符集与 SSL 协商、基于时间占位符的 SQL 模板、子表拆分防乱序、数据映射（提取/过滤/映射）、并发与批量参数调优，以及异常处理策略等全部实操要点，可直接上手搭建 MySQL → TDengine 的生产级数据管道。

功能概述：为什么用 TDengine 接入 MySQL 数据

MySQL 是最流行的关系型数据库之一，大量 IoT 与工业互联网系统曾长期使用 MySQL 存储设备上报的数据。但随着接入设备数量持续增长、用户对数据实时反馈的要求不断提高，MySQL 在高并发写入、海量时序数据压缩与查询性能上逐渐无法满足业务需求。

TDengine TSDB-Enterprise 提供内置的 MySQL 连接器，能够高效地从 MySQL 中读取数据并写入 TDengine，实现两类典型场景：

• 历史数据迁移：将 MySQL 中积压的历史时序数据一次性、分段地导入 TDengine；
• 实时数据同步：持续订阅 MySQL 中新增数据，实现准实时的双向业务衔接。

注意：本文所述功能属于TDengine TSDB-Enterprise 专属特性（Enterprise feature），开源版 TDengine TSDB-OSS 不包含这些能力，详见 Enterprise 特性声明。从源码结构看，该能力由外部连接器（External Connector）模块承载，extConnectorInt.h 中定义了以"mysql" / "postgresql" / "influxdb"为名称的 Provider 注册表，并通过mysqlProvider及其mysqlProviderInit/Cleanup/ThreadCleanup生命周期接口对外暴露 MySQL 连接能力。

前置条件

在创建任务前，请确认：

• 部署的是TDengine TSDB-Enterprise，且 taosExplorer 已正常启动；
• 浏览器可访问 taosExplorer 界面，其默认监听在 TDengine 所在主机（IP）的6060 端口；
• 目标 TDengine 集群中已有（或可在界面中即时创建）用于接收数据的数据库；
• 源 MySQL 数据库账号具备可读取目标库/表的权限。

操作流程概览

整个任务的创建过程如下：

1. 打开 taosExplorer，添加数据源（Data In → Add Task）；
2. 配置源 MySQL 的连接、认证与连接选项，并做连通性检查；
3. 配置 SQL 查询模板、时间窗口与取数粒度；
4. 配置数据映射（列提取/拆分、过滤、字段映射）；
5. 按需调整高级选项与异常处理策略；
6. 提交任务并在数据源列表页跟踪执行状态。

添加数据源

在浏览器中打开 taosExplorer（位于运行 TDengine 的主机名或 IP 的 6060 端口），按以下步骤新建数据接入任务：

1. 在左侧主菜单中点击Data In，然后点击Add Task；
2. 在Name字段中输入该数据接入任务的唯一名称；
3. 从Type下拉列表中选择MySQL；
4. （可选）如果该任务需要 Agent 支持，从Agent下拉列表中选择对应 Agent，也可以点击Create New Agent立即创建（Agent 的安装与说明可参考 安装 taosX-Agent）；
5. 从Target DB下拉列表中选择本任务数据写入的目标数据库，也可以点击Create Database立即创建。

配置连接信息

在Connection Configuration（连接配置）区域填写源 MySQL 数据库的连接信息：

包含以下字段：

• 连接信息：源 MySQL 数据库的主机地址、端口、库名等连接参数；
• 用户（User）：源 MySQL 数据库的用户名，该用户必须拥有对应组织内的读取权限；
• 密码（Password）：上述用户在该源 MySQL 数据库中的登录密码。

配置连接选项

字符集（Character Set）：设置连接使用的字符集，默认值为utf8mb4。utf8mb4自 MySQL 5.5.3 起支持；若连接的 MySQL 版本更旧，建议改为utf8。可选值包括：utf8、utf8mb4、utf16、utf32、gbk、big5、latin1、ascii。

SSL 模式（SSL Mode）：设置是否与服务器协商安全的 SSL TCP/IP 连接，以及协商优先级。默认值为PREFERRED。可选值包括：

配置完成后，点击Check Connectivity（检查连通性）按钮，验证上述填写的信息能否正常从源 MySQL 数据库中取到数据。

配置 SQL 查询

SQL 查询（SQL Query）区域是整个迁移任务取数的核心，包含以下配置项。

子表字段（Subtable Field）

用于拆分目标超级表（supertable）的子表，是一条select distinctSQL 语句，用于查询指定字段组合的非重复项，通常与 transform 中的tag相对应。

该配置主要用于解决数据迁移乱序问题，且必须与SQL Template配合使用，否则无法达到预期效果。使用示例如下：

1. 填写子表字段语句select distinct col_name1, col_name2 from table，表示用源表中的col_name1、col_name2两个字段来拆分目标超级表的子表；
2. 在SQL Template中添加子表字段占位符，例如在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 Template）

用于查询的 SQL 语句模板。SQL 语句必须包含时间范围条件，且开始、结束时间必须成对出现。模板中的时间范围由源数据库中表示时间的列，以及下面定义的占位符共同构成。

SQL 使用不同的占位符表达不同的时间格式要求，具体占位符格式如下：

1. ${start}、${end}：RFC3339 格式时间戳，例如2024-03-14T08:00:00+0800；
2. ${start_no_tz}、${end_no_tz}：不带时区的 RFC3339 字符串，例如2024-03-14T08:00:00；
3. ${start_date}、${end_date}：仅日期，例如2024-03-14。

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

时间窗口与取数粒度

• 开始时间（Start Time）：数据迁移的开始时间，必填；
• 结束时间（End Time）：数据迁移的结束时间，可留空。若设置，迁移任务到达结束时间后会自动停止；若留空，则持续同步实时数据，任务不会自动停止；
• 查询间隔（Query Interval）：分段查询数据的时间间隔，默认1 天。为避免一次性查询大量数据，每个数据同步子任务会按该间隔对取数进行分段；
• 延迟时长（Delay Duration）：在实时数据同步场景中，为避免因写入延迟导致丢数据，每个同步任务会从延迟时长之前的位置开始读取数据。

配置数据映射

在Data Mapping（数据映射）区域填写与数据映射相关的配置参数。

首先点击Retrieve from Server（从服务端获取）按钮，从 MySQL 服务器拉取样例数据。

• Extract or Split from Column（从列提取或拆分）：填写需要从消息体中提取或拆分的字段。例如将vValue字段拆分为vValue_0与vValue_1：选择拆分提取器，填入分隔符,与数量2；
• Filter（过滤）：填写过滤条件。例如写入Value > 0，则只有 Value 大于 0 的数据才会写入 TDengine；
• Mapping（映射）：选择要映射到的 TDengine 超级表，以及映射到超级表的列；
• Preview（预览）：点击预览查看映射结果，确认字段与取值是否符合预期。

配置高级选项

Advanced Options（高级选项）区域默认折叠，点击右侧>展开，包含以下参数：

• Maximum Read Concurrency（最大读取并发）：数据源连接数或读取线程数的上限。默认值0表示由连接器自动配置；当源响应较慢、需要提高并发时适当调大该值，也可在需要调整资源占用时修改；
• Batch Size（批量大小）：单次发送的最大消息数或行数，默认10000。

部分数据源还提供Write Concurrency（写入并发），用于指定可并发写入 TDengine 的任务数。与健康监控相关的选项（监控周期、繁忙阈值、写队列长度、写错误阈值等）可参考 Health Status 章节。

配置异常处理策略

Exception Handling Strategy（异常处理策略）区域默认折叠，点击>展开。通用策略包括：

• Archive（归档）：将无效数据写入归档文件（默认路径为${data_dir}/tasks/<id>/<datetime>），不写入目标数据库；
• Discard（丢弃）：忽略无效数据；
• Error（报错）：报告错误；
• Cache（缓存）：当目标连接失败或资源不足时，将数据写入缓存文件，待目标恢复后再摄入。

可针对下列异常场景分别配置处理策略：

其余相关设置包括：

• Connection Timeout（连接超时）：目标连接超时时间（秒），取值范围1～600；
• Temporary Storage Location（临时存储位置）：相对于${data_dir}/tasks/<id>/的路径；
• Archive Retention Days（归档保留天数）：非负整数，0表示不限；
• Archive Available Space（归档可用空间）：取值范围0～65535，0表示不限；
• Archive Location（归档位置）：相对于${data_dir}/tasks/<id>/的路径；
• Archive Write Failure Strategy（归档写入失败策略）：删除旧文件 / 丢弃数据 / 报错并停止任务。

上述策略的完整定义可查阅 异常处理策略资源文件。

提交任务并跟踪状态

点击Submit按钮，完成从 MySQL 到 TDengine 的数据同步任务创建，随后返回Data Source List（数据源列表）页面即可查看任务执行状态、监控运行指标，并在出现异常时依据上文策略查看归档或排查日志。

实现原理与源码佐证

从源码层面看，MySQL 连接器在 TDengine 中作为外部连接器（External Connector）的一个 Provider 实现：

• extConnectorInt.h 中定义了 Provider 名称注册表，"mysql"与"postgresql"、"influxdb"并列，说明 MySQL 是官方内置支持的数据源类型之一；
• 该文件同时声明了mysqlProvider（第 194 行）及其生命周期函数mysqlProviderInit、mysqlProviderCleanup、mysqlProviderThreadCleanup（第 196-198 行），对应连接器的初始化、资源回收与线程级清理，为任务运行时的连接管理与并发读取提供底层支撑；
• 外部连接器通过extConnectorLoadRuntimeLibrary/extConnectorLoadRuntimeSymbol/extConnectorCloseRuntimeLibrary（第 203-205 行）动态加载运行时库与符号，并在 extConnectorQuery.c 中完成取值与类型转换（value conversion），这解释了本文所述“从服务端获取样例数据”“拆分/过滤/映射”等界面能力背后的数据读取与转换链路。

理解这套 Provider 机制，有助于在遇到连接异常、并发不足或数据类型转换问题时，快速定位是连接器加载、查询执行还是值转换环节出现故障。

总结

通过 taosExplorer 的零代码界面，你可以在不编写任何代码的情况下完成 MySQL 到 TDengine 的历史数据迁移与实时同步：正确配置连接与认证、字符集与 SSL 模式，利用${start}/${end}等时间占位符与子表字段拆分保证取数有序，借助数据映射实现列提取、过滤与 tag 映射，再配合读取并发、批量大小和精细化的异常处理策略，即可构建稳定、可控、可观测的数据管道，将 MySQL 中积压的海量时序数据平稳迁入 TDengine，为后续的时序分析、实时告警与业务创新奠定数据基础。

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