1. 项目概述DataX 与 MySQLReader 到底能干什么做数据同步的应该都听说过 DataX。阿里开源的这款异构数据源离线同步工具在我接触过的数据迁移方案里算是团队用得最多、也最让人省心的一个。这几天在做本地部署的时候又把 MySQLReader 插件的文档从头翻了一遍正好整理一篇实战向的介绍把插件的核心机制、参数细节、部署过程和常见坑一次说清楚。先回答一个很多人问过的问题DataX 是什么简单说它就是一个管道。一头接上各种数据源另一头接上各种目标端中间由框架负责切分任务、调度线程、流量控制和脏数据处理。你只需要写一份 JSON 格式的作业配置告诉它从哪读、写到哪、怎么切分剩下的体力活全部交给框架。MySQLReader 就是这根管道最常用的进水口专门负责从 MySQL 里把数据读出来交给下游的 Writer 插件写到目标端。这套东西解决了什么问题日常工作里最典型的三类场景第一业务库数据定期同步到数仓做离线分析第二从生产环境抽取数据到测试环境构造联调数据第三做数据迁移或归档把历史表搬到成本更低的存储上。如果没有 DataX 这类工具你可能要自己写 JDBC 代码、处理并发控制、设计重试机制一套下来至少一两周。而 DataX 把这些问题全部内置了你只需要学会写配置文件、理解几个关键参数半天就能跑通第一条同步链路。内容上我会先拆解 MySQLReader 的整体设计帮助理解它为什么快、为什么稳然后逐个解析核心参数用表格和实例讲清楚每个配置项的作用接着是本地部署的完整实操从下载到运行一个真实的同步任务最后分享几组性能调优的参数组合和我在实际项目中踩过的坑。无论你是第一次接触 DataX还是已经在生产环境用了很久想回头补补细节这篇都可以当一份顺手的参考手册。2. MySQLReader 的整体设计与工作原理2.1 框架怎么把一份配置变成并行任务MySQLReader 不是一个独立的程序它运行在 DataX 框架之上。理解 DataX 的作业生命周期是读懂插件参数的前提。整个执行过程可以拆成四个阶段Job 启动、Task 切分、Task 执行、结果汇总。在 Job 阶段框架读取你的 JSON 配置对 MySQLReader 来说它会校验 jdbcUrl、username、password、table、column 这些必填参数是否完整同时根据你写的查询模式确定是走单表查询还是自定义 SQL。校验通过后会进入最关键的一步——Task 切分。切分逻辑值得多说两句。DataX 框架本身只负责调度真正的切分策略是由 Reader 插件自己实现的。MySQLReader 的切分依据是 splitPk你用哪个字段做切分键框架就按照这个字段把数据分成多个区间每个区间分配给一个 Task。每个 Task 里的记录读取器在自己的 JDBC 连接上执行查询把结果集交给 Channel。Channel 可以理解成一条带缓冲的数据管道框架在这里做流量控制。上游 Task 往管道里放数据下游 Writer 从管道里取数据当管道满了上游就会阻塞等待这样就不会出现 Writer 消费不过来、内存被打爆的情况。所以 DataX 的并行度是由两个维度决定的Reader 的 Task 数量和 Channel 的并发数。前者决定你能开多少个查询线程后者决定每个线程里数据流动的速率上限。2.2 从数据源到目标端的数据流我们以最常见的 MySQL 到 MySQL 的场景来追踪一条数据的完整旅程。MySQLReader 在 Task 执行阶段做的事情非常直接它拿到自己的那一段查询任务拼出类似SELECT column1, column2 FROM table WHERE id ? AND id ?这样的 SQL通过 JDBC 执行然后遍历 ResultSet。每读取一行Reader 会把这一行的数据转换成 DataX 内部定义的 Record 结构。Record 里有一组 Column 对象每个 Column 保存了字段的原始值和数据类型标记。这一步很关键因为不同类型的 Writer 插件对数据类型的支持不一样比如 MySQLWriter 可以直接吃下 MySQL 的类型但写入 HDFS 时就要转换成 String 或特定的大数据类型。统一转成内部 Record 后框架才能保证 Reader 和 Writer 的解耦。随后 Record 被推入 Channel进入流量控制和缓冲环节。框架内置了多种限速策略你可以通过job.setting.speed.byte和job.setting.speed.channel两个参数控制总带宽和并发 Channel 数。实际项目中我一般会把流控关掉或者设得很大让性能测试跑出真实水平但在生产环境建议保留一个合理的限速值避免同步任务把业务库的 IO 和连接数打满。整条链路看起来不长但设计上每一环都考虑到了大数据量下的稳定性切分保证每个 Task 的数据量基本均衡Channel 缓冲消除上下游速度差异带来的抖动统一的 Record 结构让插件之间不用互相了解。理解这些后面调参会顺很多。3. MySQLReader 核心参数逐个拆解3.1 六个必填参数的使用细节MySQLReader 的参数不算多官方文档列得也比较清楚但实际用起来有几个坑。先看一组最基础的配置样例{ reader: { name: mysqlreader, parameter: { username: root, password: your_password, column: [id, name, age], splitPk: id, connection: [{ table: [user_info], jdbcUrl: [jdbc:mysql://127.0.0.1:3306/test_db] }] } } }逐个拆解jdbcUrl是 JDBC 连接地址注意它是数组形式可以配多个地址做负载均衡但实际使用中大多数人只填一个。连接串里建议显式加上useSSLfalsecharacterEncodingutf8serverTimezoneAsia/Shanghai这几个参数。尤其是 serverTimezone如果你的 MySQL 版本较新而驱动版本较旧不配这个会直接报时间相关的 SQLException。useSSL 在本地部署和内网环境通常不需要开着反而多一次握手开销。username和password没有太多讲究但要注意账号权限。Reader 只需要 SELECT 权限按照最小权限原则不要拿 root 去跑同步任务。我在公司里会单独建一个datax_sync账号只授权需要同步的库表的只读权限这样即使配置不小心泄露到代码仓库影响面也可控。table决定读取哪张表。它是数组结构可以写多张表但要注意所有表必须在同一个库下面而且列结构要一致。实际项目中我不太建议用多表方式因为一旦某张表有问题整个 Task 都会失败排查效率很低。更推荐的做法是把多张表的抽取拆成多个独立的 DataX 作业互不影响也方便单独重跑。column指定读取哪些列。这里支持三种写法全部字段用[*]显式列出字段名[id, name]还支持在字段上用函数比如[date_format(create_time, %Y-%m-%d)]。有函数需求时要注意如果使用函数map 里的 key 会变成函数的别名下游 Writer 取不到原始字段名这点很容易踩。正常场景我还是建议老老实实列字段名性能更可控语义也清晰。splitPk是并行切分的关键但官方文档对它的解释比较保守如果不填DataX 会退化成单 Task 运行。这个参数在大多数情况下建议必须设置。选择什么字段做切分键有讲究后面专门讲。where是可选参数用来做增量抽取。常见用法有两种where里写create_time 2024-01-01做时间增量或者结合一个独立的 offset 表做更灵活的水位线管理。需要注意 where 条件不要加where关键字直接写条件表达式即可。3.2 三种查询模式与 splitPk 的正确选型MySQLReader 提供了三种读数据的模式对应不同场景。第一种单表模式。就是上面配置里的样子通过 table 加 column 组合查询。此时框架生成SELECT column... FROM table WHERE splitPk x AND splitPk y这样的语句。切分时框架先查询一次SELECT MIN(splitPk), MAX(splitPk) FROM table拿到区间端点后按 Task 数量均匀分段每段分配一个 Task 去查。这个模式下切分字段必须是有序的否则区间定位不准数据可能重复或遗漏。第二种自定义 SQL 模式用querySql替代 table 和 column。例如parameter: { querySql: [SELECT id, name, create_time FROM user_info WHERE age 18] }这种模式下框架不再对 SQL 做任何改写每个 Task 执行完全相同的 SQL无法并行。所以 querySql 适合小数据量、强定制逻辑的场景。比如你要做多表 JOIN或者字段逻辑比较复杂用 querySql 最省事。但大数据量场景非常不建议单 Task 读全表性能会很难看。第三种querySql 配合 where 动态传参。DataX 没有内置参数替换机制但很多团队会用 Shell 脚本先渲染 JSON 模板里的 where 条件再提交作业这个在后面的部署章节我会展示一个简单写法。关于 splitPk 的选型直说结论优先选主键其次选有唯一索引的数值型字段再不行选日期时间字段。不要用字符串字段做切分键虽然 MySQLReader 支持但区间查询的边界判断在字符集排序规则下容易出问题尤其字段值前缀重复度高的时候会出现某个 Task 数据量特别大、其他 Task 很快跑完的情况并行效果大打折扣。数值型主键是最理想的因为MIN/MAX查询走索引快范围段等分均匀生成的 SQL 也能充分利用主键索引。3.3 不同场景下的参数组合建议整理了三组我在生产环境验证过的配置组合可以直接抄场景channel 数splitPk 建议关键配置千万级以下单表全量4-8主键 id默认配置即可不用刻意调大 channel亿级大表迁移8-16主键 idjob.setting.speed.byte 调大到 64MB/s 以上batchSize 调到 2048增量同步每天千万级增量4主键 idwhere 条件走 create_time 索引splitPk 仍用 id第一组适合绝大多数报表库全量抽取channel 数开太多反而会让源库连接数飙升。第二组是典型的大表迁移核心是把 channel 和 byte 限速同时调大否则框架默认 1MB/s 的限速会让你等到怀疑人生。第三组是增量场景注意 where 条件字段一定要有索引否则每天的增量抽取会演变成全表扫描非常伤源库。4. 本地部署与首个同步任务实操4.1 环境准备与 DataX 安装本地部署 DataX 其实是一个非常轻量的过程。DataX 是 Java 项目依赖 JDK 8 及以上版本除此之外不需要安装任何数据库客户端。我这次部署是在一台 CentOS 7 服务器上做的配置是 4 核 8G用来跑测试任务绰绰有余。安装步骤如下。先确认 JDK 版本java -version如果没装或者版本太低用 yum 或者直接解压 JDK 的 tar 包都行。接着下载 DataX 发行版。DataX 官方 GitHub 的 Release 页面提供了打包好的 tar.gz也有人习惯自己从源码编译。对于绝大多数人直接用官方发行包就够了自己编译要处理 Maven 依赖和插件打包时间成本划不来。下载完成后解压wget http://datax-opensource.oss-cn-hangzhou.aliyuncs.com/202308/datax.tar.gz tar -zxvf datax.tar.gz -C /opt/ cd /opt/datax解压后目录结构里bin/datax.py是提交作业的入口脚本job/目录放示例配置plugin/reader/和plugin/writer/下面是各个插件的目录。MySQLReader 对应的目录是plugin/reader/mysqlreader。版本升级时经常有人只替换插件目录这个思路是对的DataX 的插件是即插即用的替换后重启作业即可不必重新解压整个发行包。跑一下自带示例确认环境没问题python bin/datax.py job/job.json看到任务启动时刻和任务结束时刻两行日志以及最后的任务启动时刻统计信息说明 DataX 已经能正常工作了。需要留意的点是 DataX 的入口脚本是 Python 写的服务器上要有 Python 2 或 Python 3 环境CentOS 7 自带的 Python 就够用。如果系统里只有 Python 3个别旧版本 DataX 的脚本可能不兼容遇到报错可以直接python3 bin/datax.py试试。4.2 第一个 MySQLReader 作业从零到一跑通安装完成之后我们编写第一个真实的同步任务。假设场景把本机 MySQL 的test_db.user_info表全量同步到另一个库test_db_bak.user_info。表结构假设是CREATE TABLE user_info ( id int NOT NULL AUTO_INCREMENT, name varchar(64) DEFAULT NULL, age int DEFAULT NULL, create_time datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;先造一点测试数据随便插几千行进去保证任务跑起来有实际效果。然后编写作业配置文件保存为/opt/datax/job/mysql_to_mysql.json{ job: { setting: { speed: { byte: -1, channel: 4 } }, content: [ { reader: { name: mysqlreader, parameter: { username: datax_sync, password: sync_pass, column: [id, name, age, create_time], splitPk: id, connection: [ { table: [user_info], jdbcUrl: [jdbc:mysql://127.0.0.1:3306/test_db?useSSLfalsecharacterEncodingutf8serverTimezoneAsia/Shanghai] } ] } }, writer: { name: mysqlwriter, parameter: { username: datax_sync, password: sync_pass, column: [id, name, age, create_time], preSql: [truncate table user_info], batchSize: 1024, connection: [ { table: [user_info], jdbcUrl: jdbc:mysql://127.0.0.1:3306/test_db_bak?useSSLfalsecharacterEncodingutf8serverTimezoneAsia/Shanghai } ] } } } ] } }这里解释几个配置细节。speed.byte设为 -1 表示不限速测试场景这样最合适否则默认的 1MB/s 限速会让几千万行数据跑到天荒地老。channel设为 4相当于开 4 个并发通道。MySQLWriter 里的preSql是一个很实用的配置它在写入前先执行truncate保证目标表是干净的空表避免上次残留数据造成主键冲突。生产环境如果要做增量preSql 通常不写。执行作业python /opt/datax/bin/datax.py /opt/datax/job/mysql_to_mysql.json运行日志会分段显示每个 Task 的执行情况最后输出一段统计信息。重点看这几个指标总记录数是否和源表行数一致成功记录数和失败记录数是否为预期值总耗时用于后续性能参考。我第一次跑这个任务时插入了 5 万行测试数据4 个 channel 下总耗时大概 3 秒其中大部分时间花在 JVM 启动和插件加载上实际传输非常快。如果同步完成后想验证数据一致性可以在两边库分别执行SELECT COUNT(*) FROM user_info; SELECT SUM(id), MAX(create_time) FROM user_info;对主键、行数、业务字段汇总值做交叉核对比肉眼抽查靠谱得多。数据量大的时候还可以用CHECKSUM TABLE做全表校验这是我在生产环境最常用的验证手段。4.3 增量抽取的配置方法与 Shell 封装全量同步只是入门实际业务里增量同步才是常态。增量抽取最常用的方案就是 where 条件加时间水位线。假设我们要同步test_db.user_info里create_time 2024-06-01 00:00:00的数据配置改成parameter: { where: create_time 2024-06-01 00:00:00, column: [id, name, age, create_time], splitPk: id }这里同样要写完整 SQL但组合方式是SELECT column FROM table WHERE splitPk x AND splitPk y AND create_time 2024-06-01 00:00:00。框架切分时仍然基于 splitPk 做区间分段where 条件作为附加过滤条件拼接到每个 Task 的查询里。生产环境不可能每次手动改 JSON所以我会用 Shell 脚本封装。脚本从命令行接收日期参数通过 sed 替换 JSON 模板里的占位符然后调用 datax.py#!/bin/bash SYNC_DATE$1 if [ -z $SYNC_DATE ]; then SYNC_DATE$(date -d yesterday %Y-%m-%d) fi sed s/__DATE__/${SYNC_DATE}/g /opt/datax/job/mysql_incremental_template.json /opt/datax/job/mysql_incremental_${SYNC_DATE}.json python /opt/datax/bin/datax.py /opt/datax/job/mysql_incremental_${SYNC_DATE}.json模板文件里 where 条件写成where: create_time __DATE__ 00:00:00 AND create_time __DATE__ 23:59:59这种方式配合 crontab 定时任务每天凌晨跑一次就形成了一套最简单的离线增量管线。注意一个细节增量同步的 where 字段和 splitPk 字段最好不要是同一个。因为切分键参与区间定位如果 where 条件把数据过滤得很窄但 splitPk 的 MIN/MAX 是整张表的范围会导致区间段里有大量 Task 查到空数据白白浪费资源。我的习惯是切分永远用主键 id过滤用业务时间字段。5. 性能调优与常见问题排查5.1 从单 Task 到高并发调优参数实测性能调优是 MySQLReader 使用中最有成就感也最容易翻车的地方。调优的本质是找到源库可以承受的并发上限以及 Channel 管道不成为瓶颈的平衡点。我把调优拆成三个维度逐个说明。第一个维度是 Channel 并发数。配置项job.setting.speed.channel决定了框架启动多少个并发通道。每个通道会对应一个 Reader Task 和至少一个 Writer Task。在 MySQLReader 场景下channel 数基本等于同时执行的查询线程数。我在 4 核 8G 的测试机上试过不同 channel 数对 100 万行数据同步耗时的影响channel 数同步耗时秒源库 CPU 使用率18712%43545%82280%161895%从数据可以直观看到channel 从 1 加到 8性能提升接近 4 倍但从 8 加到 16只提升了不到 20%。这说明 8 个 channel 左右已经接近该测试机的资源上限继续加并发只会增加调度开销。不同机器配置不一样但趋势是一致的并发超过物理核心数两倍以后收益急剧递减。生产环境我一般从 8 开始观察源库的 CPU 和连接数再决定是升到 12 还是降到 4。第二个维度是 JVM 堆内存。DataX 默认的 JVM 参数在bin/datax.py脚本里默认堆内存通常是 1G。同步大表时如果 Channel 的缓冲和数据批量过大很容易触发频繁 GC表现为日志里 Task 执行速度忽快忽慢。我的做法是在启动命令里显式指定python /opt/datax/bin/datax.py --jvm-Xms2g -Xmx2g /opt/datax/job/big_sync.json2G 堆内存可以支撑千万级数据量的同步如果单表过亿建议上 4G。需要说明的是DataX 本身不适合作为常驻服务它的定位是一次性进程所以堆内存开大不会浪费进程退出后内存自然释放。第三个维度是 JDBC 连接串和 fetchSize。MySQLReader 底层通过 JDBC 读取数据时默认行为是一次性把 ResultSet 的数据拉回内存。对大数据量查询这会让 JVM 内存瞬间飙升。解决方案是让 JDBC 使用流式读取需要在连接串上追加两个参数jdbc:mysql://127.0.0.1:3306/test_db?useCursorFetchtruedefaultFetchSize1000useCursorFetchtrue让 MySQL 驱动采用服务端游标方式defaultFetchSize控制每次从服务端拉取的行数。设置后JDBC 会分批读取结果集内存占用大幅下降。这个配置对千万级以上的大表几乎是必须的否则经常会出现同步进程在任务执行到一半时 OOM 崩溃。5.2 我踩过的五个典型错误接触 MySQLReader 这两年多踩坑记录了不少。挑五个最有代表性的写出来每个都是线上环境真实遇到过的问题排查过程也一并分享。第一个坑连接串缺 serverTimezone。这个问题多发生在 MySQL 8.x 和驱动 8.x 的组合下。现象是作业启动后立刻报The server time zone value Öйú±ê׼ʱ¼ä is unrecognized一看就是时区配置问题。解决办法是在 jdbcUrl 里加上serverTimezoneAsia/Shanghai。如果是 MySQL 5.7 搭配旧驱动一般不会遇到。第二个坑characterEncoding 不指定导致乱码。有人同步完发现 MySQL 里的中文到目标端变成了问号多半是连接串没加characterEncodingutf8或者表本身是 utf8mb4 字符集但连接用的是 utf8。utf8mb4 是 utf8 的超集能存 emoji 和生僻字连接串建议统一写characterEncodingutf8因为 MySQL 驱动对 utf8mb4 的识别是靠连接串的 utf8 参数自动升级的。第三个坑splitPk 用了字符串字段。这个错误的表现不是报错而是性能退化。某个任务切分键是order_no字符串结果 8 个 Task 里 7 个秒完最后 1 个跑了半小时。原因前面讲过字符串的范围分段在分布不均匀的数据上会出现严重的数据倾斜。排查时看每个 Task 的耗时统计就能定位。解决方法是改成自增主键做切分如果没有主键考虑加一列自增 ID 或者用查询子查询ROW_NUMBER()生成序号列但后者开销较大最好是在表设计阶段就预留主键。第四个坑querySql 模式下 splitPk 失效。很多人没注意到官方文档明确写了querySql 模式下 splitPk 是不生效的作业会单 Task 运行。有一个实际案例同事把一段多表 JOIN 的 SQL 写进 querySql表数据量在千万级跑了一个多小时没跑完加了 splitPk 也没反应。后来我帮他改成先在 MySQL 里把 JOIN 结果物化成一张临时表再用单表模式读取channel 开到 8十分钟就同步完了。这个思路值得借鉴需要复杂 SQL 时不要让 DataX 去扛计算压力把计算留在 MySQLDataX 只做搬运。第五个坑大字段导致内存暴涨。某次同步一张带TEXT类型字段的表设置了很大的 channel 数结果 JVM 频繁 Full GC最后 OOM。原因是 Channel 里每行 Record 包含一个大字符串并发高时内存占用成倍上涨。排查后确认是 fetchSize 设置问题默认一次性把整个 ResultSet 拉回内存。给连接串加上useCursorFetchtruedefaultFetchSize500后内存占用降了七八成。所以遇到大字段表流式读取是必须的配置。5.3 常用的排查手段和日志定位技巧DataX 的日志是排查问题的第一手资料。默认情况下任务执行日志会同时输出到控制台和~/logs/datax/目录下的日志文件。控制台日志适合看任务整体进度文件日志适合搜索错误堆栈。最常见的定位思路是从下往上翻异常堆栈。DataX 的异常信息设计得比较友好通常在最后几行会直接告诉你错误类型和发生位置。比如连接失败的报错会包含Communications link failureSQL 语法错误会包含完整的 SQL 语句权限问题会报Access denied for user。把这些关键信息提取出来基本上能定位八成的配置问题。如果任务运行一半失败且没有明确的 SQL 错误重点查看有多少 Task 失败、失败的 Task 读取到哪条数据。DataX 的断点信息会显示任务进度百分比结合errorLimit配置可以控制脏数据的容忍度。零容忍场景下建议配errorLimit: { record: 0, percentage: 0 }这样任何一条脏数据都会让作业失败虽然严格但能保证数据质量。日常跑批我通常放宽到record: 100或percentage: 5给脏数据一个缓冲空间让主流程先跑通事后单独处理脏数据文件。DataX 会把脏数据记录在~/logs/datax/下的dirty-data目录里每次全量重跑前先清理这个目录否则日志会越积越多。6. 从 MySQLReader 出发还能怎么扩展这套工具链MySQLReader 只是 DataX 生态里众多 Reader 中的一个但把它用透了其他插件基本可以触类旁通。我见过不少团队把 DataX 作为数据中台的底座MySQLReader 负责从业务库抽数再配合 HDFS Writer、Hive Writer 或 ClickHouse Writer搭建离线数仓的入口管道。DataX 的插件机制决定了这个组合可以非常灵活——只要目标端有对应的 Writer就能把 MySQL 的数据送到那里。在本地部署的场景下这套工具链的价值会被进一步放大。你不需要复杂的集群环境一台普通的服务器、一个 MySQL 实例、一份 DataX 发行包就能构建一个轻量级的数据同步节点。相比那些重型的同步平台DataX 在离线批处理场景下的性价比非常高。我个人在实际操作中的体会是MySQLReader 的性能上限很少取决于它本身更多取决于你怎么理解源库的特征和配置参数的相互作用。把 splitPk 选对把 channel 调到合适水位把 JDBC 连接串写完整就已经能覆盖九成以上的业务场景。剩下的那些极端情况就用 querySql 和 where 条件慢慢打磨数据同步这件事耐心和细心比技巧更值钱。最后再分享一个小技巧如果你经常要调试 MySQLReader 的配置可以在 JSON 里临时把job.setting.speed.channel设为 1并把where条件加一个LIMIT类的过滤比如id 1000这样每次验证配置和网络连通性只需要几秒钟不用拿全量数据去试错。配置验证通过后再改回正式的并发数和过滤条件。这套“小样验证、全量执行”的思路让我少走了很多弯路。
1. 项目概述DataX 与 MySQLReader 到底能干什么做数据同步的应该都听说过 DataX。阿里开源的这款异构数据源离线同步工具在我接触过的数据迁移方案里算是团队用得最多、也最让人省心的一个。这几天在做本地部署的时候又把 MySQLReader 插件的文档从头翻了一遍正好整理一篇实战向的介绍把插件的核心机制、参数细节、部署过程和常见坑一次说清楚。先回答一个很多人问过的问题DataX 是什么简单说它就是一个管道。一头接上各种数据源另一头接上各种目标端中间由框架负责切分任务、调度线程、流量控制和脏数据处理。你只需要写一份 JSON 格式的作业配置告诉它从哪读、写到哪、怎么切分剩下的体力活全部交给框架。MySQLReader 就是这根管道最常用的进水口专门负责从 MySQL 里把数据读出来交给下游的 Writer 插件写到目标端。这套东西解决了什么问题日常工作里最典型的三类场景第一业务库数据定期同步到数仓做离线分析第二从生产环境抽取数据到测试环境构造联调数据第三做数据迁移或归档把历史表搬到成本更低的存储上。如果没有 DataX 这类工具你可能要自己写 JDBC 代码、处理并发控制、设计重试机制一套下来至少一两周。而 DataX 把这些问题全部内置了你只需要学会写配置文件、理解几个关键参数半天就能跑通第一条同步链路。内容上我会先拆解 MySQLReader 的整体设计帮助理解它为什么快、为什么稳然后逐个解析核心参数用表格和实例讲清楚每个配置项的作用接着是本地部署的完整实操从下载到运行一个真实的同步任务最后分享几组性能调优的参数组合和我在实际项目中踩过的坑。无论你是第一次接触 DataX还是已经在生产环境用了很久想回头补补细节这篇都可以当一份顺手的参考手册。2. MySQLReader 的整体设计与工作原理2.1 框架怎么把一份配置变成并行任务MySQLReader 不是一个独立的程序它运行在 DataX 框架之上。理解 DataX 的作业生命周期是读懂插件参数的前提。整个执行过程可以拆成四个阶段Job 启动、Task 切分、Task 执行、结果汇总。在 Job 阶段框架读取你的 JSON 配置对 MySQLReader 来说它会校验 jdbcUrl、username、password、table、column 这些必填参数是否完整同时根据你写的查询模式确定是走单表查询还是自定义 SQL。校验通过后会进入最关键的一步——Task 切分。切分逻辑值得多说两句。DataX 框架本身只负责调度真正的切分策略是由 Reader 插件自己实现的。MySQLReader 的切分依据是 splitPk你用哪个字段做切分键框架就按照这个字段把数据分成多个区间每个区间分配给一个 Task。每个 Task 里的记录读取器在自己的 JDBC 连接上执行查询把结果集交给 Channel。Channel 可以理解成一条带缓冲的数据管道框架在这里做流量控制。上游 Task 往管道里放数据下游 Writer 从管道里取数据当管道满了上游就会阻塞等待这样就不会出现 Writer 消费不过来、内存被打爆的情况。所以 DataX 的并行度是由两个维度决定的Reader 的 Task 数量和 Channel 的并发数。前者决定你能开多少个查询线程后者决定每个线程里数据流动的速率上限。2.2 从数据源到目标端的数据流我们以最常见的 MySQL 到 MySQL 的场景来追踪一条数据的完整旅程。MySQLReader 在 Task 执行阶段做的事情非常直接它拿到自己的那一段查询任务拼出类似SELECT column1, column2 FROM table WHERE id ? AND id ?这样的 SQL通过 JDBC 执行然后遍历 ResultSet。每读取一行Reader 会把这一行的数据转换成 DataX 内部定义的 Record 结构。Record 里有一组 Column 对象每个 Column 保存了字段的原始值和数据类型标记。这一步很关键因为不同类型的 Writer 插件对数据类型的支持不一样比如 MySQLWriter 可以直接吃下 MySQL 的类型但写入 HDFS 时就要转换成 String 或特定的大数据类型。统一转成内部 Record 后框架才能保证 Reader 和 Writer 的解耦。随后 Record 被推入 Channel进入流量控制和缓冲环节。框架内置了多种限速策略你可以通过job.setting.speed.byte和job.setting.speed.channel两个参数控制总带宽和并发 Channel 数。实际项目中我一般会把流控关掉或者设得很大让性能测试跑出真实水平但在生产环境建议保留一个合理的限速值避免同步任务把业务库的 IO 和连接数打满。整条链路看起来不长但设计上每一环都考虑到了大数据量下的稳定性切分保证每个 Task 的数据量基本均衡Channel 缓冲消除上下游速度差异带来的抖动统一的 Record 结构让插件之间不用互相了解。理解这些后面调参会顺很多。3. MySQLReader 核心参数逐个拆解3.1 六个必填参数的使用细节MySQLReader 的参数不算多官方文档列得也比较清楚但实际用起来有几个坑。先看一组最基础的配置样例{ reader: { name: mysqlreader, parameter: { username: root, password: your_password, column: [id, name, age], splitPk: id, connection: [{ table: [user_info], jdbcUrl: [jdbc:mysql://127.0.0.1:3306/test_db] }] } } }逐个拆解jdbcUrl是 JDBC 连接地址注意它是数组形式可以配多个地址做负载均衡但实际使用中大多数人只填一个。连接串里建议显式加上useSSLfalsecharacterEncodingutf8serverTimezoneAsia/Shanghai这几个参数。尤其是 serverTimezone如果你的 MySQL 版本较新而驱动版本较旧不配这个会直接报时间相关的 SQLException。useSSL 在本地部署和内网环境通常不需要开着反而多一次握手开销。username和password没有太多讲究但要注意账号权限。Reader 只需要 SELECT 权限按照最小权限原则不要拿 root 去跑同步任务。我在公司里会单独建一个datax_sync账号只授权需要同步的库表的只读权限这样即使配置不小心泄露到代码仓库影响面也可控。table决定读取哪张表。它是数组结构可以写多张表但要注意所有表必须在同一个库下面而且列结构要一致。实际项目中我不太建议用多表方式因为一旦某张表有问题整个 Task 都会失败排查效率很低。更推荐的做法是把多张表的抽取拆成多个独立的 DataX 作业互不影响也方便单独重跑。column指定读取哪些列。这里支持三种写法全部字段用[*]显式列出字段名[id, name]还支持在字段上用函数比如[date_format(create_time, %Y-%m-%d)]。有函数需求时要注意如果使用函数map 里的 key 会变成函数的别名下游 Writer 取不到原始字段名这点很容易踩。正常场景我还是建议老老实实列字段名性能更可控语义也清晰。splitPk是并行切分的关键但官方文档对它的解释比较保守如果不填DataX 会退化成单 Task 运行。这个参数在大多数情况下建议必须设置。选择什么字段做切分键有讲究后面专门讲。where是可选参数用来做增量抽取。常见用法有两种where里写create_time 2024-01-01做时间增量或者结合一个独立的 offset 表做更灵活的水位线管理。需要注意 where 条件不要加where关键字直接写条件表达式即可。3.2 三种查询模式与 splitPk 的正确选型MySQLReader 提供了三种读数据的模式对应不同场景。第一种单表模式。就是上面配置里的样子通过 table 加 column 组合查询。此时框架生成SELECT column... FROM table WHERE splitPk x AND splitPk y这样的语句。切分时框架先查询一次SELECT MIN(splitPk), MAX(splitPk) FROM table拿到区间端点后按 Task 数量均匀分段每段分配一个 Task 去查。这个模式下切分字段必须是有序的否则区间定位不准数据可能重复或遗漏。第二种自定义 SQL 模式用querySql替代 table 和 column。例如parameter: { querySql: [SELECT id, name, create_time FROM user_info WHERE age 18] }这种模式下框架不再对 SQL 做任何改写每个 Task 执行完全相同的 SQL无法并行。所以 querySql 适合小数据量、强定制逻辑的场景。比如你要做多表 JOIN或者字段逻辑比较复杂用 querySql 最省事。但大数据量场景非常不建议单 Task 读全表性能会很难看。第三种querySql 配合 where 动态传参。DataX 没有内置参数替换机制但很多团队会用 Shell 脚本先渲染 JSON 模板里的 where 条件再提交作业这个在后面的部署章节我会展示一个简单写法。关于 splitPk 的选型直说结论优先选主键其次选有唯一索引的数值型字段再不行选日期时间字段。不要用字符串字段做切分键虽然 MySQLReader 支持但区间查询的边界判断在字符集排序规则下容易出问题尤其字段值前缀重复度高的时候会出现某个 Task 数据量特别大、其他 Task 很快跑完的情况并行效果大打折扣。数值型主键是最理想的因为MIN/MAX查询走索引快范围段等分均匀生成的 SQL 也能充分利用主键索引。3.3 不同场景下的参数组合建议整理了三组我在生产环境验证过的配置组合可以直接抄场景channel 数splitPk 建议关键配置千万级以下单表全量4-8主键 id默认配置即可不用刻意调大 channel亿级大表迁移8-16主键 idjob.setting.speed.byte 调大到 64MB/s 以上batchSize 调到 2048增量同步每天千万级增量4主键 idwhere 条件走 create_time 索引splitPk 仍用 id第一组适合绝大多数报表库全量抽取channel 数开太多反而会让源库连接数飙升。第二组是典型的大表迁移核心是把 channel 和 byte 限速同时调大否则框架默认 1MB/s 的限速会让你等到怀疑人生。第三组是增量场景注意 where 条件字段一定要有索引否则每天的增量抽取会演变成全表扫描非常伤源库。4. 本地部署与首个同步任务实操4.1 环境准备与 DataX 安装本地部署 DataX 其实是一个非常轻量的过程。DataX 是 Java 项目依赖 JDK 8 及以上版本除此之外不需要安装任何数据库客户端。我这次部署是在一台 CentOS 7 服务器上做的配置是 4 核 8G用来跑测试任务绰绰有余。安装步骤如下。先确认 JDK 版本java -version如果没装或者版本太低用 yum 或者直接解压 JDK 的 tar 包都行。接着下载 DataX 发行版。DataX 官方 GitHub 的 Release 页面提供了打包好的 tar.gz也有人习惯自己从源码编译。对于绝大多数人直接用官方发行包就够了自己编译要处理 Maven 依赖和插件打包时间成本划不来。下载完成后解压wget http://datax-opensource.oss-cn-hangzhou.aliyuncs.com/202308/datax.tar.gz tar -zxvf datax.tar.gz -C /opt/ cd /opt/datax解压后目录结构里bin/datax.py是提交作业的入口脚本job/目录放示例配置plugin/reader/和plugin/writer/下面是各个插件的目录。MySQLReader 对应的目录是plugin/reader/mysqlreader。版本升级时经常有人只替换插件目录这个思路是对的DataX 的插件是即插即用的替换后重启作业即可不必重新解压整个发行包。跑一下自带示例确认环境没问题python bin/datax.py job/job.json看到任务启动时刻和任务结束时刻两行日志以及最后的任务启动时刻统计信息说明 DataX 已经能正常工作了。需要留意的点是 DataX 的入口脚本是 Python 写的服务器上要有 Python 2 或 Python 3 环境CentOS 7 自带的 Python 就够用。如果系统里只有 Python 3个别旧版本 DataX 的脚本可能不兼容遇到报错可以直接python3 bin/datax.py试试。4.2 第一个 MySQLReader 作业从零到一跑通安装完成之后我们编写第一个真实的同步任务。假设场景把本机 MySQL 的test_db.user_info表全量同步到另一个库test_db_bak.user_info。表结构假设是CREATE TABLE user_info ( id int NOT NULL AUTO_INCREMENT, name varchar(64) DEFAULT NULL, age int DEFAULT NULL, create_time datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;先造一点测试数据随便插几千行进去保证任务跑起来有实际效果。然后编写作业配置文件保存为/opt/datax/job/mysql_to_mysql.json{ job: { setting: { speed: { byte: -1, channel: 4 } }, content: [ { reader: { name: mysqlreader, parameter: { username: datax_sync, password: sync_pass, column: [id, name, age, create_time], splitPk: id, connection: [ { table: [user_info], jdbcUrl: [jdbc:mysql://127.0.0.1:3306/test_db?useSSLfalsecharacterEncodingutf8serverTimezoneAsia/Shanghai] } ] } }, writer: { name: mysqlwriter, parameter: { username: datax_sync, password: sync_pass, column: [id, name, age, create_time], preSql: [truncate table user_info], batchSize: 1024, connection: [ { table: [user_info], jdbcUrl: jdbc:mysql://127.0.0.1:3306/test_db_bak?useSSLfalsecharacterEncodingutf8serverTimezoneAsia/Shanghai } ] } } } ] } }这里解释几个配置细节。speed.byte设为 -1 表示不限速测试场景这样最合适否则默认的 1MB/s 限速会让几千万行数据跑到天荒地老。channel设为 4相当于开 4 个并发通道。MySQLWriter 里的preSql是一个很实用的配置它在写入前先执行truncate保证目标表是干净的空表避免上次残留数据造成主键冲突。生产环境如果要做增量preSql 通常不写。执行作业python /opt/datax/bin/datax.py /opt/datax/job/mysql_to_mysql.json运行日志会分段显示每个 Task 的执行情况最后输出一段统计信息。重点看这几个指标总记录数是否和源表行数一致成功记录数和失败记录数是否为预期值总耗时用于后续性能参考。我第一次跑这个任务时插入了 5 万行测试数据4 个 channel 下总耗时大概 3 秒其中大部分时间花在 JVM 启动和插件加载上实际传输非常快。如果同步完成后想验证数据一致性可以在两边库分别执行SELECT COUNT(*) FROM user_info; SELECT SUM(id), MAX(create_time) FROM user_info;对主键、行数、业务字段汇总值做交叉核对比肉眼抽查靠谱得多。数据量大的时候还可以用CHECKSUM TABLE做全表校验这是我在生产环境最常用的验证手段。4.3 增量抽取的配置方法与 Shell 封装全量同步只是入门实际业务里增量同步才是常态。增量抽取最常用的方案就是 where 条件加时间水位线。假设我们要同步test_db.user_info里create_time 2024-06-01 00:00:00的数据配置改成parameter: { where: create_time 2024-06-01 00:00:00, column: [id, name, age, create_time], splitPk: id }这里同样要写完整 SQL但组合方式是SELECT column FROM table WHERE splitPk x AND splitPk y AND create_time 2024-06-01 00:00:00。框架切分时仍然基于 splitPk 做区间分段where 条件作为附加过滤条件拼接到每个 Task 的查询里。生产环境不可能每次手动改 JSON所以我会用 Shell 脚本封装。脚本从命令行接收日期参数通过 sed 替换 JSON 模板里的占位符然后调用 datax.py#!/bin/bash SYNC_DATE$1 if [ -z $SYNC_DATE ]; then SYNC_DATE$(date -d yesterday %Y-%m-%d) fi sed s/__DATE__/${SYNC_DATE}/g /opt/datax/job/mysql_incremental_template.json /opt/datax/job/mysql_incremental_${SYNC_DATE}.json python /opt/datax/bin/datax.py /opt/datax/job/mysql_incremental_${SYNC_DATE}.json模板文件里 where 条件写成where: create_time __DATE__ 00:00:00 AND create_time __DATE__ 23:59:59这种方式配合 crontab 定时任务每天凌晨跑一次就形成了一套最简单的离线增量管线。注意一个细节增量同步的 where 字段和 splitPk 字段最好不要是同一个。因为切分键参与区间定位如果 where 条件把数据过滤得很窄但 splitPk 的 MIN/MAX 是整张表的范围会导致区间段里有大量 Task 查到空数据白白浪费资源。我的习惯是切分永远用主键 id过滤用业务时间字段。5. 性能调优与常见问题排查5.1 从单 Task 到高并发调优参数实测性能调优是 MySQLReader 使用中最有成就感也最容易翻车的地方。调优的本质是找到源库可以承受的并发上限以及 Channel 管道不成为瓶颈的平衡点。我把调优拆成三个维度逐个说明。第一个维度是 Channel 并发数。配置项job.setting.speed.channel决定了框架启动多少个并发通道。每个通道会对应一个 Reader Task 和至少一个 Writer Task。在 MySQLReader 场景下channel 数基本等于同时执行的查询线程数。我在 4 核 8G 的测试机上试过不同 channel 数对 100 万行数据同步耗时的影响channel 数同步耗时秒源库 CPU 使用率18712%43545%82280%161895%从数据可以直观看到channel 从 1 加到 8性能提升接近 4 倍但从 8 加到 16只提升了不到 20%。这说明 8 个 channel 左右已经接近该测试机的资源上限继续加并发只会增加调度开销。不同机器配置不一样但趋势是一致的并发超过物理核心数两倍以后收益急剧递减。生产环境我一般从 8 开始观察源库的 CPU 和连接数再决定是升到 12 还是降到 4。第二个维度是 JVM 堆内存。DataX 默认的 JVM 参数在bin/datax.py脚本里默认堆内存通常是 1G。同步大表时如果 Channel 的缓冲和数据批量过大很容易触发频繁 GC表现为日志里 Task 执行速度忽快忽慢。我的做法是在启动命令里显式指定python /opt/datax/bin/datax.py --jvm-Xms2g -Xmx2g /opt/datax/job/big_sync.json2G 堆内存可以支撑千万级数据量的同步如果单表过亿建议上 4G。需要说明的是DataX 本身不适合作为常驻服务它的定位是一次性进程所以堆内存开大不会浪费进程退出后内存自然释放。第三个维度是 JDBC 连接串和 fetchSize。MySQLReader 底层通过 JDBC 读取数据时默认行为是一次性把 ResultSet 的数据拉回内存。对大数据量查询这会让 JVM 内存瞬间飙升。解决方案是让 JDBC 使用流式读取需要在连接串上追加两个参数jdbc:mysql://127.0.0.1:3306/test_db?useCursorFetchtruedefaultFetchSize1000useCursorFetchtrue让 MySQL 驱动采用服务端游标方式defaultFetchSize控制每次从服务端拉取的行数。设置后JDBC 会分批读取结果集内存占用大幅下降。这个配置对千万级以上的大表几乎是必须的否则经常会出现同步进程在任务执行到一半时 OOM 崩溃。5.2 我踩过的五个典型错误接触 MySQLReader 这两年多踩坑记录了不少。挑五个最有代表性的写出来每个都是线上环境真实遇到过的问题排查过程也一并分享。第一个坑连接串缺 serverTimezone。这个问题多发生在 MySQL 8.x 和驱动 8.x 的组合下。现象是作业启动后立刻报The server time zone value Öйú±ê׼ʱ¼ä is unrecognized一看就是时区配置问题。解决办法是在 jdbcUrl 里加上serverTimezoneAsia/Shanghai。如果是 MySQL 5.7 搭配旧驱动一般不会遇到。第二个坑characterEncoding 不指定导致乱码。有人同步完发现 MySQL 里的中文到目标端变成了问号多半是连接串没加characterEncodingutf8或者表本身是 utf8mb4 字符集但连接用的是 utf8。utf8mb4 是 utf8 的超集能存 emoji 和生僻字连接串建议统一写characterEncodingutf8因为 MySQL 驱动对 utf8mb4 的识别是靠连接串的 utf8 参数自动升级的。第三个坑splitPk 用了字符串字段。这个错误的表现不是报错而是性能退化。某个任务切分键是order_no字符串结果 8 个 Task 里 7 个秒完最后 1 个跑了半小时。原因前面讲过字符串的范围分段在分布不均匀的数据上会出现严重的数据倾斜。排查时看每个 Task 的耗时统计就能定位。解决方法是改成自增主键做切分如果没有主键考虑加一列自增 ID 或者用查询子查询ROW_NUMBER()生成序号列但后者开销较大最好是在表设计阶段就预留主键。第四个坑querySql 模式下 splitPk 失效。很多人没注意到官方文档明确写了querySql 模式下 splitPk 是不生效的作业会单 Task 运行。有一个实际案例同事把一段多表 JOIN 的 SQL 写进 querySql表数据量在千万级跑了一个多小时没跑完加了 splitPk 也没反应。后来我帮他改成先在 MySQL 里把 JOIN 结果物化成一张临时表再用单表模式读取channel 开到 8十分钟就同步完了。这个思路值得借鉴需要复杂 SQL 时不要让 DataX 去扛计算压力把计算留在 MySQLDataX 只做搬运。第五个坑大字段导致内存暴涨。某次同步一张带TEXT类型字段的表设置了很大的 channel 数结果 JVM 频繁 Full GC最后 OOM。原因是 Channel 里每行 Record 包含一个大字符串并发高时内存占用成倍上涨。排查后确认是 fetchSize 设置问题默认一次性把整个 ResultSet 拉回内存。给连接串加上useCursorFetchtruedefaultFetchSize500后内存占用降了七八成。所以遇到大字段表流式读取是必须的配置。5.3 常用的排查手段和日志定位技巧DataX 的日志是排查问题的第一手资料。默认情况下任务执行日志会同时输出到控制台和~/logs/datax/目录下的日志文件。控制台日志适合看任务整体进度文件日志适合搜索错误堆栈。最常见的定位思路是从下往上翻异常堆栈。DataX 的异常信息设计得比较友好通常在最后几行会直接告诉你错误类型和发生位置。比如连接失败的报错会包含Communications link failureSQL 语法错误会包含完整的 SQL 语句权限问题会报Access denied for user。把这些关键信息提取出来基本上能定位八成的配置问题。如果任务运行一半失败且没有明确的 SQL 错误重点查看有多少 Task 失败、失败的 Task 读取到哪条数据。DataX 的断点信息会显示任务进度百分比结合errorLimit配置可以控制脏数据的容忍度。零容忍场景下建议配errorLimit: { record: 0, percentage: 0 }这样任何一条脏数据都会让作业失败虽然严格但能保证数据质量。日常跑批我通常放宽到record: 100或percentage: 5给脏数据一个缓冲空间让主流程先跑通事后单独处理脏数据文件。DataX 会把脏数据记录在~/logs/datax/下的dirty-data目录里每次全量重跑前先清理这个目录否则日志会越积越多。6. 从 MySQLReader 出发还能怎么扩展这套工具链MySQLReader 只是 DataX 生态里众多 Reader 中的一个但把它用透了其他插件基本可以触类旁通。我见过不少团队把 DataX 作为数据中台的底座MySQLReader 负责从业务库抽数再配合 HDFS Writer、Hive Writer 或 ClickHouse Writer搭建离线数仓的入口管道。DataX 的插件机制决定了这个组合可以非常灵活——只要目标端有对应的 Writer就能把 MySQL 的数据送到那里。在本地部署的场景下这套工具链的价值会被进一步放大。你不需要复杂的集群环境一台普通的服务器、一个 MySQL 实例、一份 DataX 发行包就能构建一个轻量级的数据同步节点。相比那些重型的同步平台DataX 在离线批处理场景下的性价比非常高。我个人在实际操作中的体会是MySQLReader 的性能上限很少取决于它本身更多取决于你怎么理解源库的特征和配置参数的相互作用。把 splitPk 选对把 channel 调到合适水位把 JDBC 连接串写完整就已经能覆盖九成以上的业务场景。剩下的那些极端情况就用 querySql 和 where 条件慢慢打磨数据同步这件事耐心和细心比技巧更值钱。最后再分享一个小技巧如果你经常要调试 MySQLReader 的配置可以在 JSON 里临时把job.setting.speed.channel设为 1并把where条件加一个LIMIT类的过滤比如id 1000这样每次验证配置和网络连通性只需要几秒钟不用拿全量数据去试错。配置验证通过后再改回正式的并发数和过滤条件。这套“小样验证、全量执行”的思路让我少走了很多弯路。
