TDengine 无代码数据接入通过 taosExplorer 将 PostgreSQL 数据迁移至 TDengine 集群【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本文基于当前仓库 docs/en/08-data-ingest-and-delivery/01-no-code-ingestion/14-postgres.md 编写完整介绍如何通过 taosExplorer 界面创建无代码数据接入任务将 PostgreSQL 中的数据迁移或实时同步到 TDengine 集群。读完本文你将掌握从新增数据源、配置连接与认证、编写 SQL 查询模板、配置数据映射到异常处理策略与任务提交的完整实操流程并能理解子表字段拆分子表、时间占位符格式化、查询分片等关键机制的底层原理。功能概述PostgreSQL 是一个功能非常强大、源代码开放的客户/服务器关系型数据库管理系统拥有许多大型商业 RDBMS 才具备的特性包括事务transactions、子选择subselects、触发器triggers、视图views、外键引用完整性foreign key referential integrity以及复杂的锁定locking能力。在许多 IoT 与工业互联网系统中PostgreSQL 常被用作业务数据的关系型存储。TDengine 可以高效地从 PostgreSQL 读取数据并将其写入 TDengine从而实现两类核心诉求历史数据迁移将 PostgreSQL 中指定时间范围内的存量数据一次性迁移到 TDengine实时数据同步持续读取 PostgreSQL 中新增/变更的数据近乎实时地写入 TDengine。版本说明本文介绍的功能属于TDengine TSDB-Enterprise企业版专属能力TDengine TSDB-OSS开源社区版不包含这些数据接入组件使用时需确认部署版本。整体工作流通过 taosExplorer 界面创建 PostgreSQL 数据接入任务的整体流程如下打开 taosExplorerWeb 界面位于运行 TDengine 的主机或 IP 的6060 端口在左侧主菜单点击Data In数据写入再点击Add Task / 新增数据源进入任务创建页依次配置基本信息 → 连接信息 → 认证信息 → 连接选项 → SQL 查询 → 数据映射 → 高级选项 → 异常处理策略点击Submit提交任务返回数据源列表页查看任务执行状态。从源码结构看这类外部数据源接入能力由 source/libs/extconnector 提供实现支撑执行器层如 federatedscanoperator.c负责对跨源数据的扫描与转换最终将外部数据映射写入 TDengine 的目标库表。新增数据源在数据写入页面中点击新增数据源按钮进入新增数据源页面按下述步骤创建任务对应 resources/_resources.mdx 中的统一流程在 Web 浏览器中打开taosExplorer该界面位于运行 TDengine 的主机名或 IP 的6060 端口在左侧主菜单点击Data In然后点击Add Task在Name字段中输入一个唯一的数据接入任务名称例如test_postgres_01从Type下拉框中选择PostgreSQL选择完成后页面中的字段会动态切换为 PostgreSQL 专用表单可选如果该数据接入任务需要代理执行从Agent下拉框中选择代理也可以点击Create New Agent立即创建一个新代理taosX-Agent 的安装方式见仓库内相关说明从Target DB下拉框中选择该任务写入的目标数据库也可以点击Create Database立即创建新数据库。配置连接信息在Connection Configuration / 连接配置区域填写源 PostgreSQL 数据库的连接信息包括主机地址、端口、数据库名等。这些参数决定了 taosExplorer 将如何建立到源库的 TCP/IP 连接。配置认证信息User用户输入源 PostgreSQL 数据库的用户名该用户必须在源数据库组织中拥有读取权限即具备对迁移目标表/视图执行查询的权限。Password密码输入上述用户在源 PostgreSQL 数据库中的登录密码。配置连接选项Application Name应用名称设置应用程序名称用于在源 PostgreSQL 数据库中标识当前连接的应用便于数据库侧的会话追踪与排查。SSL ModeSSL 模式设置是否与服务器协商安全的 SSL TCP/IP 连接以及以何种优先级进行协商。默认值为PREFER可选值如下选项含义DISABLE只尝试非 SSL 连接ALLOW先尝试非 SSL 连接失败后再尝试 SSL 连接PREFER默认先尝试 SSL 连接失败后再尝试非 SSL 连接REQUIRE只尝试 SSL 连接若服务器不支持则连接失败配置完成后点击Check Connectivity检查连通性按钮taosExplorer 会立即校验上述信息是否可以正常从源 PostgreSQL 数据库获取数据若检查失败请根据提示调整连接、认证或 SSL 配置后重试。配置 SQL 查询SQL QuerySQL 查询区域是决定迁移哪些数据、如何切分数据的核心配置包含以下参数子表字段Subtable Field子表字段用于拆分子表它是一条select distinct的 SQL 语句查询指定字段组合的非重复项通常与 transform数据映射中的 tag 相对应。该配置主要用于解决数据迁移乱序问题必须与SQL 模板配合使用否则无法达到预期效果。用法示例如下填写子表字段语句select distinct col_name1, col_name2 from table表示使用源表中的col_name1和col_name2字段来拆分目标超级表supertable的子表在SQL 模板中添加子表字段占位符例如在select * from table where ts ${start} and ts ${end} and ${col_name1} and ${col_name2}中加入${col_name1}和${col_name2}。运行时每个占位符会展开为一个等值谓词如col_name1deviceA或col_name21而不是裸的列名在transform中配置col_name1和col_name2两个 tag 映射。通过子表字段每个设备或设备组合的数据在查询阶段就被按条件隔离配合有序读取可避免多子表数据交错写入导致的目标库乱序问题。SQL 模板SQL TemplateSQL 模板是用于查询的 SQL 语句模板必须满足以下约束SQL 语句必须包含时间范围条件且开始时间和结束时间必须成对出现时间范围由源数据库中代表时间的列 下述时间占位符共同定义。不同的占位符代表 SQL 中不同的时间格式要求具体如下占位符时间格式示例${start}、${end}RFC3339 格式时间戳含时区2024-03-14T08:00:000800${start_no_tz}、${end_no_tz}不带时区的 RFC3339 字符串2024-03-14T08:00:00${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从服务器获取按钮可从 PostgreSQL 服务器拉取示例数据用于后续映射配置Extract or Split from Column从列中提取或拆分填写从消息体中提取或拆分的字段。例如将vValue字段拆分为vValue_0和vValue_1选择split拆分提取器填写分隔符,与数量2Filter过滤填写过滤条件。例如填写Value 0则只有Value大于 0 的数据才会被写入 TDengineMapping映射选择要映射到的 TDengine 超级表以及映射到超级表的列列、tag 的对应关系在此定义子表字段查询出的字段应在此映射为 tag点击Preview预览可查看映射结果确认字段对应关系无误后再提交。配置高级选项Advanced Options高级选项区域默认折叠点击右侧的展开Maximum Read Concurrency最大读取并发数据源连接数或读取线程数的上限。当默认参数不满足需求或需要调整资源占用时修改此参数。该值越大单任务并发读取能力越强但会占用更多源库连接与本地线程资源。Batch Size批量大小单次发送的消息或行数的最大值默认为 10000。该参数决定了每批次写入 TDengine 的数据量需结合网络带宽与目标库写入能力权衡。配置异常处理Exception Handling Strategy异常处理策略区域默认折叠点击展开完整策略清单对应仓库内 resources/_03-exception-handling-strategy.mdx。通用的处置方式包括策略行为Archive归档将无效数据写入归档文件默认位于${data_dir}/tasks/id/datetime下不写入目标数据库Discard丢弃忽略无效数据Error报错报告错误Cache缓存当目标连接失败或资源不足时将数据写入缓存文件待目标恢复后继续接入可为以下具体异常场景分别配置策略目标连接超时可归档、丢弃、报错或缓存目标数据库不存在可归档、丢弃或报错表不存在可归档、丢弃、报错或自动建表后重试主时间戳超出范围now - keep1至now 100y可归档、丢弃或报错主时间戳为 null可归档、丢弃、报错或使用当前时间复合主键为 null可归档、丢弃或报错表名超过 192 字符可归档、丢弃、报错、截断或截断并归档表名含非法字符如.可归档、丢弃、报错或将非法字符替换为配置的字符串表名模板变量为 null可丢弃、保留变量为空或替换为配置的字符串列不存在可归档、丢弃、报错或自动补列后重试列名超过 64 字符可归档、丢弃或报错列值超过定义长度可归档、丢弃、报错、截断或截断并归档也可通过Automatic Column Expansion自动扩列修改表结构后重试其他数据错误可归档、丢弃或报错。除此之外还有以下附加设置Connection Timeout连接超时目标连接超时秒数取值范围1600Temporary Storage Location临时存储位置相对于${data_dir}/tasks/id/的路径Archive Retention Days归档保留天数非负整数0表示无限期保留Archive Available Space归档可用空间取值范围0655350表示不限制Archive Location归档位置相对于${data_dir}/tasks/id/的路径Archive Write Failure Strategy归档写入失败策略可删除旧文件、丢弃数据或报错并停止任务。合理的异常处理策略可显著提升任务在弱网、源数据异常等场景下的健壮性。例如生产环境建议将主时间戳为 null配置为归档而非丢弃便于事后追溯问题数据。完成任务点击Submit提交按钮即可完成从 PostgreSQL 到 TDengine 的数据同步任务的创建。随后返回Data Source List数据源列表页面查看任务执行状态、进度与日志。任务运行期间进度信息会持久化到磁盘相关机制可参考同目录下 TDengine Query 迁移任务说明 中关于进度保存的描述因此任务暂停后重启、或异常后自动恢复时不会从头开始执行。实践要点与注意事项子表字段 SQL 模板 tag 映射三者必须配套子表字段负责按字段组合拆分子表SQL 模板中的占位符在运行时展开为等值谓词而非列名transform 中必须配置对应的 tag 映射三者缺一不可否则无法实现有序拆分迁移时间占位符成对使用SQL 模板中开始与结束时间必须成对出现且可按需选择带时区${start}/${end}、不带时区${start_no_tz}/${end_no_tz}或仅日期${start_date}/${end_date}三种格式排序是乱序问题的关键建议在 SQL 模板中追加order by ts asc配合子表字段拆分保证写入目标库的数据按子表、按时间有序实时同步注意延迟窗口Delay Duration让每个同步周期从延迟时长之前的位置读取为源库写入延迟留出缓冲避免丢数End Time留空即为持续实时同步模式查询间隔平衡资源默认 1 天的Query Interval将大时间范围切分为多个子任务分片执行可避免单次查询数据量过大批量大小默认 10000与最大读取并发共同决定写入吞吐企业版能力本功能依赖 TDengine TSDB-Enterprise 的数据接入组件taosX 生态社区版TSDB-OSS不包含使用时请确认部署的版本与许可。本文档的中文版本见 docs/zh/08-data-ingest-and-delivery/01-no-code-ingestion/14-postgres.md同类关系型数据库接入如 MySQL、Oracle、SQL Server的配置流程与本文高度一致可对照参考。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考