如何把数据从 TDengine 2.x 迁移到 3.x ？

一.迁移背景：

随着时序数据库（Time Series Database） TDengine 3.0 的发布至今，我们除了在持续地优化产品质量的本身，也一直在努力地提升用户体验。但由于 3.0 底层有大量的重构优化，导致开源版的 2.0 用户无法通过常规途径来升级到 3.0 ，本期文章将会协助大部分开源版用户解决这个问题。

正文：

首先，我们先说下 taosdump 为什么是协助“大部分”开源版用户解决这个问题：

taosdump 的导出行为的本质其实是使用 SQL 进行查询，将数据压缩后输出到本地，导入行为则是通过 STMT 接口再把导出的数据导入新的环境。在内部，它嵌入了一个 TDengine 客户端，通过 -T 参数的线程数配置，并发地把所有 SQL 请求发给数据库，此后，后续的查询工作就是数据库自己的事情了。鉴于以上原因，所以它的导出导入的性能都十分依赖于数据库本身的部署建模是否科学，硬件资源是否充足等因素。

举个简单例子：假如某用户在建表的时候，对于一列本应使用 binary(100) 就足够的数据使用了 nchar(2000)，那么等到导出 SQL 执行的时候，性能就会被拖累很多。

因此，能够顺利完成数据导出的用户，应尽量拥有如下几个特征：

1. 拥有足够磁盘空间——因为硬盘上的数据是列式压缩，而导出数据为行式压缩。如果选择一次性导出全部数据，建议需要至少留出 du -sh $dataDir/vnode --exclude='wal' 大小的 3 倍空间（多多益善）。但如果是按照库/表为单位分批导出，或者指定时间范围导出的话，就比较灵活了。
   

2. 数据库日常使用负载不高，在大量导出 SQL 执行时，数据库仍有充足资源可以保障正常生产使用。
   

3. 待迁移的 2.0 数据为测试环境不需担心影响业务，或者生产环境的业务间歇期足够完成数据的导出——这两点需要结合当前导出速度自己评估。

总结而言，导出/导入数据的快慢是由 SQL 执行效率来决定的，而 SQL 执行效率的背后又是由部署建模，硬件资源等因素决定的。

只要磁盘空间充足，时间充足，就可以完成导出操作。导入则相对简单，没有额外需求，按照正常的数据库部署思路即可。

因为 taosdump 本身的产品特征决定了在上述特殊情况下，迁移数据会有效率问题，因此这也是我们开发专业的企业版数据迁移工具 taosX 的原因之一。

二.迁移操作

导出方：

对于 2.0 一侧，首先要准备好最新版本的 TDengine 和 taosdump 工具，具体操作如下：

1. 把数据库升级到 2.6.0.34，升级注意事项以及操作步骤都可以参考这篇文章：https://www.taosdata.com/engineering/10222.html。（注意：RPM 和 Deb 包不含 taosdump ，它需要通过安装 taosTools 包获得。 所以建议大家直接使用包含 TDengine 的 Tar 包完成升级。）TDengine 安装包需从 2.6 版本的文档去下载：https://www.taosdata.com/all-downloads 。如果使用了 RPM 和 Deb 的话，同样需要通过上述链接下载最新版的 taostool 获取 taosdump 工具（当前最新版为 2.4.5）

1. 使用 taosdump 把数据导出：

具体操作可参考：https://docs.taosdata.com/2.6/reference/taosdump/

举例：taosdump -o /test  -D test  -T 4

这条命令会把 test 库的数据，用 4 个线程导出到 /test 目录下面，文件形式如下：

接下来，我们需要把 test 路径下的导出文件，迁移到 3.0 的环境中，准备数据导入。

导入方：

1. 3.0 这一侧，新环境我们建议使用最新版，各方面都更好（当前最新版为 3.0.4.1），正常安装部署即可。（同样：RPM 和 Deb 包不含 taosdump ，它需要通过安装 taosTools 包获得。 所以建议大家直接使用包含 taosdump 的 tar 包完成部署，下载链接：https://docs.taosdata.com/releases/tdengine/）但是如果只能使用 RPM 或者 Deb ，taosTools 则需要从 3.0 的文档单独下载，地址：https://docs.taosdata.com/releases/tools/ （当前最新版为 2.5.0）

2. 导入之前，我们首先要进入导出文件目录下的标红目录，打开里面的 dbs.sql，针对建库 SQL 做一些针对性的调整。尤其需要注意的是 VGROUPS 参数，这是 3.0 的新增参数，代替了此前 2.0 的一系列建表逻辑，默认是 2 ，代表着这个库有 2 个 VGROUP 。如果原本的 2.0 环境使用了 4 个 VGROUP，那么就需要手动添加 "VGROUPS 4" 到建库语句后面，即可保持和 2.0 版本一样的 VGROUP 数量了。（其他参数同理，直接在建库 SQL 后添加即可，至于该语句中 2.0 时代的旧参数则会被导入程序自动屏蔽掉。具体的 3.0 建库参数细节可参考：https://docs.taosdata.com/taos-sql/database/）

示例：

原本的建库语句：

CREATE DATABASE IF NOT EXISTS test REPLICA 1  QUORUM 1 DAYS 10 KEEP 3650 CACHE 16 BLOCKS 6 FSYNC 3000  PRECISION 'ms'  MINROWS 100 MAXROWS 4096 COMP 2 ;

添加参数后：

CREATE DATABASE IF NOT EXISTS test REPLICA 1  QUORUM 1 DAYS 10 KEEP 3650 CACHE 16 BLOCKS 6 FSYNC 3000  PRECISION 'ms'  MINROWS 100 MAXROWS 4096 COMP 2 VGROUPS 4;

1. 修改完 dbs.sql 后，便可以执行导入操作了，导入操作本身是比较简单的，具体操作可参考：https://docs.taosdata.com/2.6/reference/taosdump/
   

举例：taosdump -i /test -T 4 

这条命令会把 /test 目录下的数据，用 4 个线程导入到当前环境下面，地址默认为 localhost，线程数可根据机器配置酌情设置。

导入完毕之后检验数据内容，确认无误之后，开源版 TDengine 2.0 至 3.0 数据迁移便完成了。

如果上述方案不能帮助我们完成数据迁移，欢迎联系 TDengine 企业版团队做定制化的支持服务。