1. MySQLWriter到底解决什么问题为什么你需要单独了解它先聊一个在很多团队里反复出现的场景业务库每天产生大量数据需要同步到数仓、分析库或另一套MySQL实例。大多数人第一反应是写个JDBC循环插入跑起来发现慢得离谱然后就陷入调优的泥潭——改批量大小、调自动提交、换连接池参数一套组合拳打在JDBC这层效果有限。等你真正用上DataX会发现同步任务的写端几乎都是靠插件完成的而MySQLWriter就是DataX生态里最常被点名的一个写端插件。DataX的架构并不复杂Reader插件负责从源头读数据Writer插件负责把数据写到目标端中间通过Channel和缓冲机制把两者解耦。你可以把Reader想成水龙头把Writer想成排水口MySQLWriter就是这个排水口里专门适配MySQL的那一节管道。它的核心价值不是帮你写SQL而是解决如何高效、稳定、可控地把一批数据落到MySQL里这一整件事。单独把MySQLWriter拎出来讲是因为它在使用中的坑远比看起来多。配置项不多但每一项都藏着自己的脾气它支持的写入模式、批量提交机制、连接参数、字段映射规则直接决定了同步任务能不能跑得又快又稳。很多人用DataX同步到MySQL任务慢、报错、丢数据最后排查下来问题都出在MySQLWriter的配置和理解上而不是DataX框架本身。这篇文章就围绕MySQLWriter展开从配置结构、写入逻辑、性能调优到踩坑复盘把我实际用过、测过、踩过的东西都摊开讲。适合正在上手DataX、想把同步任务做得更稳的人也适合那种配置能跑但不知道为什么要这么配的读者——读完你应该能自己判断一个MySQLWriter参数该怎么调而不是靠百度抄作业。2. job.json里MySQLWriter的配置逐项拆解从字段映射到写入控制DataX的任务核心是一个JSON格式的job配置文件MySQLWriter的所有行为都由其中的writer参数控制。很多新手拿到一份模板就直接填库名表名跑通了就觉得完事了其实这里面每个参数都有讲究。2.1 一个完整的MySQLWriter配置长什么样我先给出一份我在生产环境常用的MySQLWriter配置后续逐个参数拆解{ job: { setting: { speed: { channel: 4, byte: 1048576 } }, content: [ { reader: { name: mysqlreader, parameter: { username: root, password: 123456, column: [id, name, create_time], connection: [ { table: [source_table], jdbcUrl: [jdbc:mysql://127.0.0.1:3306/source_db?useUnicodetruecharacterEncodingutf8] } ] } }, writer: { name: mysqlwriter, parameter: { username: root, password: 123456, writeMode: insert, column: [id, name, create_time], session: [ SET NAMES utf8mb4, SET SESSION query_cache_size 0 ], preSql: [ DELETE FROM target_table WHERE create_time 2024-01-01 AND create_time 2024-01-02 ], connection: [ { jdbcUrl: jdbc:mysql://127.0.0.1:3306/target_db?useUnicodetruecharacterEncodingutf8useSSLfalserewriteBatchedStatementstrue, table: [target_table] } ] } } } ] } }这份配置覆盖了大多数场景。下面我把重点参数拆开讲。2.2 connection、table、jdbcUrl之间的关系MySQLWriter里的connection是一个数组数组里每个元素是一组连接配置。每组配置有自己的jdbcUrl和tabletable是目标表名支持配置多张表——你没看错官方文档里table可以写多个表名这在分表写入场景下很有用。比如你有user_202401、user_202402两张结构相同的表table写成数组DataX会按顺序在每张表上执行写入操作。jdbcUrl里最值得注意的就是那串参数。建议至少保留useUnicodetrue和characterEncodingutf8这能避免中文写进去变成乱码。如果目标库是MySQL 8.0以上useSSLfalse也要加上否则会有SSL连接警告虽然不致命但很烦人。另一个关键参数是rewriteBatchedStatementstrue后面讲性能的时候我会重点说它。2.3 column数组的三个常见用法column定义的是目标表接收数据的字段列表它和reader端的column形成映射关系。我的经验是column的顺序必须和reader端column的顺序一一对应而不是和目标表的物理顺序对应。DataX是按位置把一条记录里的第N个值塞给column数组里的第N个字段名字对不上没关系位置错了才要命。column里有几个特殊写法值得知道[*]表示目标表全部字段都不管按表结构顺序接收。但强烈不建议在生产环境这么干因为一旦源表和目标表字段顺序不一致数据就全错位了。可以写常量如[id, name, 固定值]单引号包裹的字符串会被当成常量处理每次插入都用这个值。可以写函数如[now()]DataX会把now()解析成MySQL函数在INSERT语句里直接执行。这在填充create_time这类默认值字段的时候很省事。但这里有个容易踩的坑如果某个字段在column里没出现而这个字段在目标表里又没有默认值插入时会报字段不能为空的错误。所以column数组不是想省就省的必须先对齐目标表结构。2.4 writeMode参数insert和replace的真实差异MySQLWriter的writeMode只支持两种取值insert和replace。注意官方文档里写的update模式在MySQLWriter里实际并不可用这是一个很常见的理解误区。insert模式生成INSERT INTO语句如果主键或唯一索引冲突直接报错任务失败。replace模式生成REPLACE INTO语句冲突时先删除旧记录再插入新记录。很多人看到replace就下意识觉得这不就是upsert吗好用但实际上replace有一个隐患只要表里任意一个唯一键冲突它就把整行删掉重插。如果表里有多个唯一索引replace的行为可能比你想的更激进——它会把所有冲突行全部删除而不是只更新冲突字段。举一个真实例子目标表有主键id和唯一索引uk_user_id数据源里有一条记录id变了但user_id没变replace模式会先删旧行再插新行如果这个表有外键引用或者有其他业务读取这条记录就会产生短暂的记录消失窗口。我的建议是如果目标表只有主键、没有其他唯一约束replace可以用如果有多个唯一键尽量用insert配合preSql做幂等处理或者用insert ignore——虽然MySQLWriter没有直接暴露insert ignore参数但可以通过preSql先删除需要覆盖的数据来实现。2.5 preSql和postSql被低估的清洗利器preSql在写入前执行postSql在写入后执行都是SQL数组可以写多条。这是MySQLWriter里最容易被忽视的功能但它能解决大量数据同步的痛点。最常见的用法是做幂等同步每天跑同步任务先删除当天的目标数据再插入这样就算任务重跑也不会产生重复数据。比如preSql: [ DELETE FROM target_table WHERE stat_date 2024-06-01 ]还可以做临时表切换先把数据写入临时表postSql里执行一个原子操作把临时表数据搬到正式表这样目标表的查询永远不会看到写到一半的数据。preSql执行失败会直接中断任务这个行为要记住。有时候preSql里的SQL写错了任务会秒失败排查时第一反应应该看preSql——我有一段时间排查一个固定报错的任务怎么都找不到原因后来才发现是preSql里引用了一张不存在的表。2.6 session参数会话级设置的妙用session数组里的每项都会在建立连接后、执行写入前以SET语句的形式下发到MySQL会话。常见用途是设置SQL模式、字符集、隔离级别等。比如我前面配置里的SET SESSION query_cache_size 0是为了避免在支持查询缓存的MySQL版本中产生不必要的缓存维护开销。又比如session: [ SET SESSION sql_mode STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION ]这样可以在写入时统一会话的SQL模式防止因为sql_mode不一致导致的行为差异。另一个实用的场景是设置SET SESSION group_concat_max_len 102400如果你在单条SQL里用GROUP_CONCAT拼了大量数据这个值不够会导致写入失败。3. MySQLWriter写入的内部机制批处理、缓冲和事务边界了解MySQLWriter怎么工作的比背配置参数重要得多。这一节我从原理层面拆解讲清楚一条数据从Channel流到MySQL的完整链路。3.1 DataX写完一条数据后发生了什么DataX的Reader把数据读出来后并不是一条条直接交给MySQLWriter而是先放进一个内存缓冲。这个缓冲的大小由setting.speed.channel、setting.speed.byte这些参数决定。你可以把Channel理解成一条传送带数据在传送带上排队MySQLWriter作为传送带的终点按批次往下游MySQL倒数据。MySQLWriter内部有一个批处理刷盘机制攒够一定数量的记录或者缓冲区达到某个阈值才真正执行一次JDBC batch INSERT。这个攒批的动作是MySQLWriter高效的核心。如果一条条插JDBC往返时间会完全吃掉吞吐量而批量插入可以把1000条记录的插入压缩成少数几次网络往返。3.2 批处理rewriteBatchedStatements为什么重要这里必须单独讲rewriteBatchedStatements这个JDBC URL参数。很多人配置MySQLWriter时漏掉它结果发现batchSize配得很大性能却上不去。原因很简单MySQL的JDBC驱动默认情况下不会把你连续提交的INSERT语句合并成一条多VALUES语句而是逐条发给服务器。你虽然调了批处理接口但底层还是单条执行网络开销根本没省下来。加了rewriteBatchedStatementstrue之后JDBC驱动会在客户端把同一表上的批量INSERT重写为一条INSERT INTO table VALUES (...),(...),(...)这样的多值语句网络往返次数瞬间减少好几个数量级。实测中同样一批10万条数据开与不开这个参数写入耗时可以差3到5倍。所以你在配置MySQLWriter的jdbcUrl时一定要把这句话拼进去jdbc:mysql://127.0.0.1:3306/db?useUnicodetruecharacterEncodingutf8useSSLfalserewriteBatchedStatementstrue3.3 batchSize和缓冲区的配合逻辑MySQLWriter的batchSize参数有些版本在plugin里叫batchSize默认1024控制单次batch插入的记录条数。它和Channel的缓冲大小是互相配合的关系batchSize太大比如5000甚至10000单条INSERT语句的VALUES数量过多MySQL需要解析更长的SQL内存占用也上升反而导致性能下降。batchSize太小比如50批处理优势发挥不出来走回低吞吐的老路。我的经验值batchSize设置在1024到2048之间最稳。10万条以上数据量的任务2048的batchSize配合4个channel写入速度通常能跑到每秒1万到3万条左右具体取决于表结构、索引数量和MySQL服务器性能。这里有个容易被忽略的细节不是所有reader端的数据都适合大batchSize。如果单条记录特别大比如有长文本、JSON字段batchSize要相应调小否则一条INSERT语句可能超过max_allowed_packet的限制直接报错。大记录场景下batchSize可以降到200到500牺牲一点批量优势换来稳定。3.4 事务边界MySQLWriter怎么保证数据一致性MySQLWriter默认情况下每批次batchSize提交一次事务。也就是说假设batchSize是1024那么每1024条数据提交一次而不是整个任务跑完才提交一次。这个设计有好处也有代价。好处是任务中断时丢数据可控——最多丢一个batch的数据重跑时可以基于preSql的幂等逻辑做恢复。代价是MySQLWriter不具备跨批次的事务一致性如果你希望整个同步任务是原子的要么靠preSql把任务设计成可重跑的先删后插要么在任务外层包一层事务控制——但DataX官方框架不保证这一点所以设计同步方案时一定要把可重跑作为基本要求。这也解释了为什么前面反复强调preSql的重要性MySQLWriter的任务天然是分段提交的一旦中途失败已经提交的batch不会回滚。没有幂等保护的同步任务重跑就会产生重复数据。而幂等保护的最佳实现位置就是preSql和任务设计而不是指望MySQLWriter帮你做全量回滚。4. 实测经验MySQLWriter的性能调优从配置到压测性能部分我直接放一组压测数据都是我在同一台测试机上跑出来的结果硬件环境是4核8G的云主机MySQL 8.0表结构包含一个主键、两个普通索引单条记录平均大小约700字节。数据量100万条源端是另一台MySQL的相同表。4.1 四组对照实验channel、batchSize、rewriteBatchedStatements的影响实验组channel数batchSizerewriteBatchedStatements总耗时每秒吞吐A11024否约680秒约1500条B41024否约210秒约4800条C41024是约55秒约18000条D42048是约42秒约24000条可以看出channel从1升到4提速三倍左右这是因为并行度上来了多个连接同时写入。但真正质变是加rewriteBatchedStatements直接又翻了将近四倍。D组相对C组的提升说明batchSize从1024涨到2048在中等记录大小下依然有正向收益。4.2 channel数不是越大越好很多人的第一反应是channel越多越快但实测发现channel超过6以后收益明显递减不说副作用也来了。连接数增多MySQL端需要维护更多连接连接池配置、最大连接数都要跟着调。多channel并发写同一张表时索引维护、行锁、插入缓冲的竞争加剧尤其是目标表有大量二级索引时写入速度会受到明显影响。更大的隐患是多channel配合replace模式可能出现死锁。多个连接同时执行REPLACE INTO遇到同一批主键冲突时MySQL的锁竞争可能导致死锁错误任务随机失败。我建议的启动配置channel数不要超过目标库CPU核心数的两倍。4核的库最多给到8个channel再往上加MySQL自身会成为瓶颈。实际场景里4到6个channel是性价比最高的区间。4.3 索引对写入性能的影响以及临时降级策略目标表的索引数量直接决定写入瓶颈。还是前面那张表我把两个二级索引临时删掉重跑百万条数据的写入耗时从42秒直接降到19秒。这说明索引维护占用了超过一半的写入开销。在生产环境如果同步窗口很紧有个临时策略可以考虑写入前drop掉非必要索引同步完再重建。这个操作可以放在preSql和postSql里preSql: [ ALTER TABLE target_table DROP INDEX idx_user_id, ALTER TABLE target_table DROP INDEX idx_status ], postSql: [ ALTER TABLE target_table ADD INDEX idx_user_id (user_id), ALTER TABLE target_table ADD INDEX idx_status (status) ]但要清醒认识到风险索引删除期间目标表的线上查询性能会退化业务侧可能受不了。所以这个策略只适合夜深人静的大批量离线同步白天的增量同步千万别这么干。4.4 内存与GCDataX本身也吃资源DataX是Java写的通道和缓冲都在内存里。每个channel默认缓冲一部分记录如果单条记录较大或channel数较多DataX进程的堆内存占用会上升。默认启动命令的JVM参数往往不够用建议调一下python datax.py job.json -j -Xms2G -Xmx4G这里-Xms和-Xmx分别指定堆内存初始值和最大值千万记得两个值设成一样避免运行期动态扩容导致的停顿。还有一点容易被忽视setting.speed.byte这个参数是全局字节限速单位是字节每秒它和channel一起构成DataX对整个任务的限速控制。如果任务跑得慢先看一眼是不是byte参数设小了——它默认不限制但很多人会为了控制资源给它一个很低的值。4.5 如何利用DataX日志判断写入瓶颈DataX自带一套完整的运行日志跑完任务会在任务目录下生成plugin/writer/mysqlwriter子目录里的日志文件。里面最有价值的两个信息Total 1000000 records, 700000000 bytes | Speed 3.0MB/s, 24000 records/s这句是总吞吐直观告诉你任务跑得多快。日志里的JOB和TASK两个级别的信息可以区分是框架瓶颈还是插件瓶颈。我自己排查性能问题的思路一般是先看总吞吐如果低于5000条/秒先确认有没有开rewriteBatchedStatements开了还慢再确认channel数是不是太少接着看目标表的索引数量和MySQL的max_allowed_packet最后才怀疑源端reader读得慢。这个顺序帮你少走很多弯路。5. MySQLWriter踩坑实录从报错到恢复的完整排查链路MySQLWriter的坑我这些年基本上都踩过一轮。这一节不列干巴巴的报错码直接讲场景和排查思路每个问题都是真实项目里遇到的。5.1 连接超时与max_allowed_packet数据写不进去的隐藏元凶第一个高频坑是大记录写入失败。任务跑到某个batch突然报PacketTooBigException错误信息里有max_allowed_packet的字样。这个报错的意思是你单次INSERT语句的包大小超过了MySQL服务器允许的最大值。默认情况下max_allowed_packet在MySQL 8.0是64MB看起来很大但如果batchSize较大、单条记录又包含大字段很容易撞上。比如一条记录里有个2MB的TEXT字段batchSize 1024一次INSERT就有2GB的包远超限制。排查链路是这样的查看MySQL当前配置SHOW VARIABLES LIKE max_allowed_packet;如果值太小临时调大SET GLOBAL max_allowed_packet 536870912;512MB更重要的是调整writer侧把batchSize降到256以下大记录场景甚至直接降到100。同步完成后记得把配置改回来因为过大max_allowed_packet会带来潜在的内存压力。还有一个容易被忽略的版本差异MySQL 8.0的驱动对max_allowed_packet的处理比5.7严格升级数据库之后原本能跑的同步任务可能突然报错排查时别只盯着数据量先看配置。5.2 数据库多个实例的增量同步MySQLWriter怎么配合热门搜索词里有一条是datax 实现数据库多个实例的增量同步这个场景我实际搭建过这里分享下思路。多实例增量同步的核心不是MySQLWriter本身而是它配合reader端的where条件实现每次只同步增量部分。做法大致是在每个源实例的表中找到增量字段比如update_time或自增id。在reader的connection里配置表名和where条件where携带上次同步的水位线。在writer的preSql里做幂等控制先删除同一水位线范围内的旧数据再插入这样即使任务重跑也不会重复。水位线的记录可以放在额外的元数据表里跑批前读取、跑批后更新。DataX本身不负责记录水位线这是任务调度系统比如DataX-web或你自己的cron脚本要做的。MySQLWriter在这个方案里的角色是可靠落盘。insert模式加preSql删除的组合比replace模式更安全因为insert在冲突时报错能尽快暴露问题而replace会悄悄覆盖反而不利于增量数据正确性校验。5.3 主键冲突、死锁和任务重跑的完整处理遇到过这样一个真实场景全量同步任务跑了一半因为网络抖动断掉了重新跑又报主键冲突。原因很简单第一次跑已经插入了一部分数据第二次从头开始跑已插入的部分再次执行insert冲突了。我的处理方式成了固定套路任务设计时就在preSql里写清理SQL把目标表当天要同步的数据先删掉。全量同步就TRUNCATE如果允许增量就DELETE WHERE ...。如果preSql已经删了还是报主键冲突那基本可以断定是reader端读到了重复数据。检查源表的查询逻辑尤其是多表JOIN产生的结果是不是有重复行。死锁报错的话错误信息里通常有Deadlock found when trying to get lock。这时候先确认是不是多个channel并发replace导致的。我的处理是把writeMode切回insert并把channel数降一半死锁问题基本能消除。这里还有一个细节值得记DataX任务失败后下次重跑时reader端读到的数据和上次一样所以所有同步任务都要建立在可重跑的基础上。这应该是MySQLWriter应用里最核心的一条经验也是很多数据同步事故的根源。别指望DataX给你自动断点续传它不干这个活你自己用preSql加上幂等逻辑才是正确的做法。5.4 时区、字符集和特殊字符数据错乱的隐形杀手最后聊一个很隐蔽但影响极大的问题时区和字符集。MySQLWriter写入的datetime类型如果jdbcUrl里没有设置serverTimezoneMySQL 8.0驱动会默认用服务器时区而连接时区和服务器的会话时区不一致时时间数据会出现偏移。最常见的是差了8个小时写入的时间比源端早或晚8小时排查起来非常迷惑。解决方案是在jdbcUrl里显式指定serverTimezoneAsia/Shanghai字符集方面如果表里有emoji这类四字节字符确保jdbcUrl包含characterEncodingutf8mb4而不是utf8——utf8在MySQL里实际是utf8mb3遇到emoji会直接报错或者变成乱码。这个配置要和目标表的字符集保持一致否则轻则显示异常重则任务失败。6. 从MySQLWriter看整个DataX插件机制不只为了配好一个插件很多人学会配MySQLWriter之后会把DataX当成MysqlToMysql工具来用这其实是浪费。MySQLWriter只是DataX的其中一个写端理解它的设计等于理解DataX所有Writer插件的一半。6.1 Writer插件的通用结构DataX里任何Writer插件都有两个核心组成部分Writer和Task。Writer负责初始化、配置校验、任务切分Task是实际干活的执行单元由多个并发实例组成对应前面说的channel数。MySQLWriter的Task内部做的事情是建立数据库连接执行session配置。执行preSql。循环从Channel取数据攒批后批量写入。所有数据写完执行postSql释放连接。切换其他Writer插件比如PostgreSQLWriter、HDFSWriter你会发现配置结构基本是同一套骨架——connection、table、column、preSql、postSql——只是每个插件针对目标端的特性做了适配。所以当你真正了解了MySQLWriter再去用其他插件会非常顺。6.2 容器化部署DataX和MySQLWriter的注意点既然热词里出现容器化部署datax与datax-web我也顺带说下我在Docker里跑DataX的经验。MySQLWriter在容器里的表现和本地没有本质区别但有几个坑值得提防容器内连接MySQL时jdbcUrl不能写localhost或127.0.0.1因为那是容器自己的lo接口要写宿主机IP或者服务发现地址。DataX是Python启动Java进程容器镜像需要同时包含Python环境和JDK构建镜像时容易漏。容器内存限制和JVM堆内存要同步设置否则容器限了内存但JVM不管不顾分配直接被OOMKilled。DataX任务目录要挂载成卷否则每次容器重建要重新上传配置文件日志目录最好也挂出来方便排查。这些细节处理好了DataX在容器里就和一个普通进程一样稳定。6.3 从MySQLWriter扩展出去数据同步方案的架构级思考最后聊聊一个更上层的经验。用MySQLWriter写了那么多同步任务之后我最大的体会是工具只是执行层数据同步方案的成败取决于任务设计和恢复策略。一个好的MySQLWriter使用方案一定要回答这几个问题任务重跑会不会产生重复数据preSql里怎么清理任务失败了一半怎么知道哪些数据已经写进去了目标表的索引会不会拖垮写入性能同步延迟能不能满足业务要求这些都是靠配置之外的工程习惯解决的。比如我习惯在每个同步任务的元数据表里记录开始时间、结束时间、成功条数、失败信息跑批结束后做个简单校验数据对不上就告警。这些朴素的工程实践可比堆channel数管用多了。MySQLWriter本身只是一个插件但你把它放到一个完整的数据同步体系里它就是一个可靠的落地点——上游不管从哪来下游MySQL这边永远有条不紊地接收数据。理解了这一点你配的就不只是一个job.json而是一套能扛住线上环境考验的同步机制。 DataX MySQLWriter全面解析：配置、原理与性能调优
1. MySQLWriter到底解决什么问题为什么你需要单独了解它先聊一个在很多团队里反复出现的场景业务库每天产生大量数据需要同步到数仓、分析库或另一套MySQL实例。大多数人第一反应是写个JDBC循环插入跑起来发现慢得离谱然后就陷入调优的泥潭——改批量大小、调自动提交、换连接池参数一套组合拳打在JDBC这层效果有限。等你真正用上DataX会发现同步任务的写端几乎都是靠插件完成的而MySQLWriter就是DataX生态里最常被点名的一个写端插件。DataX的架构并不复杂Reader插件负责从源头读数据Writer插件负责把数据写到目标端中间通过Channel和缓冲机制把两者解耦。你可以把Reader想成水龙头把Writer想成排水口MySQLWriter就是这个排水口里专门适配MySQL的那一节管道。它的核心价值不是帮你写SQL而是解决如何高效、稳定、可控地把一批数据落到MySQL里这一整件事。单独把MySQLWriter拎出来讲是因为它在使用中的坑远比看起来多。配置项不多但每一项都藏着自己的脾气它支持的写入模式、批量提交机制、连接参数、字段映射规则直接决定了同步任务能不能跑得又快又稳。很多人用DataX同步到MySQL任务慢、报错、丢数据最后排查下来问题都出在MySQLWriter的配置和理解上而不是DataX框架本身。这篇文章就围绕MySQLWriter展开从配置结构、写入逻辑、性能调优到踩坑复盘把我实际用过、测过、踩过的东西都摊开讲。适合正在上手DataX、想把同步任务做得更稳的人也适合那种配置能跑但不知道为什么要这么配的读者——读完你应该能自己判断一个MySQLWriter参数该怎么调而不是靠百度抄作业。2. job.json里MySQLWriter的配置逐项拆解从字段映射到写入控制DataX的任务核心是一个JSON格式的job配置文件MySQLWriter的所有行为都由其中的writer参数控制。很多新手拿到一份模板就直接填库名表名跑通了就觉得完事了其实这里面每个参数都有讲究。2.1 一个完整的MySQLWriter配置长什么样我先给出一份我在生产环境常用的MySQLWriter配置后续逐个参数拆解{ job: { setting: { speed: { channel: 4, byte: 1048576 } }, content: [ { reader: { name: mysqlreader, parameter: { username: root, password: 123456, column: [id, name, create_time], connection: [ { table: [source_table], jdbcUrl: [jdbc:mysql://127.0.0.1:3306/source_db?useUnicodetruecharacterEncodingutf8] } ] } }, writer: { name: mysqlwriter, parameter: { username: root, password: 123456, writeMode: insert, column: [id, name, create_time], session: [ SET NAMES utf8mb4, SET SESSION query_cache_size 0 ], preSql: [ DELETE FROM target_table WHERE create_time 2024-01-01 AND create_time 2024-01-02 ], connection: [ { jdbcUrl: jdbc:mysql://127.0.0.1:3306/target_db?useUnicodetruecharacterEncodingutf8useSSLfalserewriteBatchedStatementstrue, table: [target_table] } ] } } } ] } }这份配置覆盖了大多数场景。下面我把重点参数拆开讲。2.2 connection、table、jdbcUrl之间的关系MySQLWriter里的connection是一个数组数组里每个元素是一组连接配置。每组配置有自己的jdbcUrl和tabletable是目标表名支持配置多张表——你没看错官方文档里table可以写多个表名这在分表写入场景下很有用。比如你有user_202401、user_202402两张结构相同的表table写成数组DataX会按顺序在每张表上执行写入操作。jdbcUrl里最值得注意的就是那串参数。建议至少保留useUnicodetrue和characterEncodingutf8这能避免中文写进去变成乱码。如果目标库是MySQL 8.0以上useSSLfalse也要加上否则会有SSL连接警告虽然不致命但很烦人。另一个关键参数是rewriteBatchedStatementstrue后面讲性能的时候我会重点说它。2.3 column数组的三个常见用法column定义的是目标表接收数据的字段列表它和reader端的column形成映射关系。我的经验是column的顺序必须和reader端column的顺序一一对应而不是和目标表的物理顺序对应。DataX是按位置把一条记录里的第N个值塞给column数组里的第N个字段名字对不上没关系位置错了才要命。column里有几个特殊写法值得知道[*]表示目标表全部字段都不管按表结构顺序接收。但强烈不建议在生产环境这么干因为一旦源表和目标表字段顺序不一致数据就全错位了。可以写常量如[id, name, 固定值]单引号包裹的字符串会被当成常量处理每次插入都用这个值。可以写函数如[now()]DataX会把now()解析成MySQL函数在INSERT语句里直接执行。这在填充create_time这类默认值字段的时候很省事。但这里有个容易踩的坑如果某个字段在column里没出现而这个字段在目标表里又没有默认值插入时会报字段不能为空的错误。所以column数组不是想省就省的必须先对齐目标表结构。2.4 writeMode参数insert和replace的真实差异MySQLWriter的writeMode只支持两种取值insert和replace。注意官方文档里写的update模式在MySQLWriter里实际并不可用这是一个很常见的理解误区。insert模式生成INSERT INTO语句如果主键或唯一索引冲突直接报错任务失败。replace模式生成REPLACE INTO语句冲突时先删除旧记录再插入新记录。很多人看到replace就下意识觉得这不就是upsert吗好用但实际上replace有一个隐患只要表里任意一个唯一键冲突它就把整行删掉重插。如果表里有多个唯一索引replace的行为可能比你想的更激进——它会把所有冲突行全部删除而不是只更新冲突字段。举一个真实例子目标表有主键id和唯一索引uk_user_id数据源里有一条记录id变了但user_id没变replace模式会先删旧行再插新行如果这个表有外键引用或者有其他业务读取这条记录就会产生短暂的记录消失窗口。我的建议是如果目标表只有主键、没有其他唯一约束replace可以用如果有多个唯一键尽量用insert配合preSql做幂等处理或者用insert ignore——虽然MySQLWriter没有直接暴露insert ignore参数但可以通过preSql先删除需要覆盖的数据来实现。2.5 preSql和postSql被低估的清洗利器preSql在写入前执行postSql在写入后执行都是SQL数组可以写多条。这是MySQLWriter里最容易被忽视的功能但它能解决大量数据同步的痛点。最常见的用法是做幂等同步每天跑同步任务先删除当天的目标数据再插入这样就算任务重跑也不会产生重复数据。比如preSql: [ DELETE FROM target_table WHERE stat_date 2024-06-01 ]还可以做临时表切换先把数据写入临时表postSql里执行一个原子操作把临时表数据搬到正式表这样目标表的查询永远不会看到写到一半的数据。preSql执行失败会直接中断任务这个行为要记住。有时候preSql里的SQL写错了任务会秒失败排查时第一反应应该看preSql——我有一段时间排查一个固定报错的任务怎么都找不到原因后来才发现是preSql里引用了一张不存在的表。2.6 session参数会话级设置的妙用session数组里的每项都会在建立连接后、执行写入前以SET语句的形式下发到MySQL会话。常见用途是设置SQL模式、字符集、隔离级别等。比如我前面配置里的SET SESSION query_cache_size 0是为了避免在支持查询缓存的MySQL版本中产生不必要的缓存维护开销。又比如session: [ SET SESSION sql_mode STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION ]这样可以在写入时统一会话的SQL模式防止因为sql_mode不一致导致的行为差异。另一个实用的场景是设置SET SESSION group_concat_max_len 102400如果你在单条SQL里用GROUP_CONCAT拼了大量数据这个值不够会导致写入失败。3. MySQLWriter写入的内部机制批处理、缓冲和事务边界了解MySQLWriter怎么工作的比背配置参数重要得多。这一节我从原理层面拆解讲清楚一条数据从Channel流到MySQL的完整链路。3.1 DataX写完一条数据后发生了什么DataX的Reader把数据读出来后并不是一条条直接交给MySQLWriter而是先放进一个内存缓冲。这个缓冲的大小由setting.speed.channel、setting.speed.byte这些参数决定。你可以把Channel理解成一条传送带数据在传送带上排队MySQLWriter作为传送带的终点按批次往下游MySQL倒数据。MySQLWriter内部有一个批处理刷盘机制攒够一定数量的记录或者缓冲区达到某个阈值才真正执行一次JDBC batch INSERT。这个攒批的动作是MySQLWriter高效的核心。如果一条条插JDBC往返时间会完全吃掉吞吐量而批量插入可以把1000条记录的插入压缩成少数几次网络往返。3.2 批处理rewriteBatchedStatements为什么重要这里必须单独讲rewriteBatchedStatements这个JDBC URL参数。很多人配置MySQLWriter时漏掉它结果发现batchSize配得很大性能却上不去。原因很简单MySQL的JDBC驱动默认情况下不会把你连续提交的INSERT语句合并成一条多VALUES语句而是逐条发给服务器。你虽然调了批处理接口但底层还是单条执行网络开销根本没省下来。加了rewriteBatchedStatementstrue之后JDBC驱动会在客户端把同一表上的批量INSERT重写为一条INSERT INTO table VALUES (...),(...),(...)这样的多值语句网络往返次数瞬间减少好几个数量级。实测中同样一批10万条数据开与不开这个参数写入耗时可以差3到5倍。所以你在配置MySQLWriter的jdbcUrl时一定要把这句话拼进去jdbc:mysql://127.0.0.1:3306/db?useUnicodetruecharacterEncodingutf8useSSLfalserewriteBatchedStatementstrue3.3 batchSize和缓冲区的配合逻辑MySQLWriter的batchSize参数有些版本在plugin里叫batchSize默认1024控制单次batch插入的记录条数。它和Channel的缓冲大小是互相配合的关系batchSize太大比如5000甚至10000单条INSERT语句的VALUES数量过多MySQL需要解析更长的SQL内存占用也上升反而导致性能下降。batchSize太小比如50批处理优势发挥不出来走回低吞吐的老路。我的经验值batchSize设置在1024到2048之间最稳。10万条以上数据量的任务2048的batchSize配合4个channel写入速度通常能跑到每秒1万到3万条左右具体取决于表结构、索引数量和MySQL服务器性能。这里有个容易被忽略的细节不是所有reader端的数据都适合大batchSize。如果单条记录特别大比如有长文本、JSON字段batchSize要相应调小否则一条INSERT语句可能超过max_allowed_packet的限制直接报错。大记录场景下batchSize可以降到200到500牺牲一点批量优势换来稳定。3.4 事务边界MySQLWriter怎么保证数据一致性MySQLWriter默认情况下每批次batchSize提交一次事务。也就是说假设batchSize是1024那么每1024条数据提交一次而不是整个任务跑完才提交一次。这个设计有好处也有代价。好处是任务中断时丢数据可控——最多丢一个batch的数据重跑时可以基于preSql的幂等逻辑做恢复。代价是MySQLWriter不具备跨批次的事务一致性如果你希望整个同步任务是原子的要么靠preSql把任务设计成可重跑的先删后插要么在任务外层包一层事务控制——但DataX官方框架不保证这一点所以设计同步方案时一定要把可重跑作为基本要求。这也解释了为什么前面反复强调preSql的重要性MySQLWriter的任务天然是分段提交的一旦中途失败已经提交的batch不会回滚。没有幂等保护的同步任务重跑就会产生重复数据。而幂等保护的最佳实现位置就是preSql和任务设计而不是指望MySQLWriter帮你做全量回滚。4. 实测经验MySQLWriter的性能调优从配置到压测性能部分我直接放一组压测数据都是我在同一台测试机上跑出来的结果硬件环境是4核8G的云主机MySQL 8.0表结构包含一个主键、两个普通索引单条记录平均大小约700字节。数据量100万条源端是另一台MySQL的相同表。4.1 四组对照实验channel、batchSize、rewriteBatchedStatements的影响实验组channel数batchSizerewriteBatchedStatements总耗时每秒吞吐A11024否约680秒约1500条B41024否约210秒约4800条C41024是约55秒约18000条D42048是约42秒约24000条可以看出channel从1升到4提速三倍左右这是因为并行度上来了多个连接同时写入。但真正质变是加rewriteBatchedStatements直接又翻了将近四倍。D组相对C组的提升说明batchSize从1024涨到2048在中等记录大小下依然有正向收益。4.2 channel数不是越大越好很多人的第一反应是channel越多越快但实测发现channel超过6以后收益明显递减不说副作用也来了。连接数增多MySQL端需要维护更多连接连接池配置、最大连接数都要跟着调。多channel并发写同一张表时索引维护、行锁、插入缓冲的竞争加剧尤其是目标表有大量二级索引时写入速度会受到明显影响。更大的隐患是多channel配合replace模式可能出现死锁。多个连接同时执行REPLACE INTO遇到同一批主键冲突时MySQL的锁竞争可能导致死锁错误任务随机失败。我建议的启动配置channel数不要超过目标库CPU核心数的两倍。4核的库最多给到8个channel再往上加MySQL自身会成为瓶颈。实际场景里4到6个channel是性价比最高的区间。4.3 索引对写入性能的影响以及临时降级策略目标表的索引数量直接决定写入瓶颈。还是前面那张表我把两个二级索引临时删掉重跑百万条数据的写入耗时从42秒直接降到19秒。这说明索引维护占用了超过一半的写入开销。在生产环境如果同步窗口很紧有个临时策略可以考虑写入前drop掉非必要索引同步完再重建。这个操作可以放在preSql和postSql里preSql: [ ALTER TABLE target_table DROP INDEX idx_user_id, ALTER TABLE target_table DROP INDEX idx_status ], postSql: [ ALTER TABLE target_table ADD INDEX idx_user_id (user_id), ALTER TABLE target_table ADD INDEX idx_status (status) ]但要清醒认识到风险索引删除期间目标表的线上查询性能会退化业务侧可能受不了。所以这个策略只适合夜深人静的大批量离线同步白天的增量同步千万别这么干。4.4 内存与GCDataX本身也吃资源DataX是Java写的通道和缓冲都在内存里。每个channel默认缓冲一部分记录如果单条记录较大或channel数较多DataX进程的堆内存占用会上升。默认启动命令的JVM参数往往不够用建议调一下python datax.py job.json -j -Xms2G -Xmx4G这里-Xms和-Xmx分别指定堆内存初始值和最大值千万记得两个值设成一样避免运行期动态扩容导致的停顿。还有一点容易被忽视setting.speed.byte这个参数是全局字节限速单位是字节每秒它和channel一起构成DataX对整个任务的限速控制。如果任务跑得慢先看一眼是不是byte参数设小了——它默认不限制但很多人会为了控制资源给它一个很低的值。4.5 如何利用DataX日志判断写入瓶颈DataX自带一套完整的运行日志跑完任务会在任务目录下生成plugin/writer/mysqlwriter子目录里的日志文件。里面最有价值的两个信息Total 1000000 records, 700000000 bytes | Speed 3.0MB/s, 24000 records/s这句是总吞吐直观告诉你任务跑得多快。日志里的JOB和TASK两个级别的信息可以区分是框架瓶颈还是插件瓶颈。我自己排查性能问题的思路一般是先看总吞吐如果低于5000条/秒先确认有没有开rewriteBatchedStatements开了还慢再确认channel数是不是太少接着看目标表的索引数量和MySQL的max_allowed_packet最后才怀疑源端reader读得慢。这个顺序帮你少走很多弯路。5. MySQLWriter踩坑实录从报错到恢复的完整排查链路MySQLWriter的坑我这些年基本上都踩过一轮。这一节不列干巴巴的报错码直接讲场景和排查思路每个问题都是真实项目里遇到的。5.1 连接超时与max_allowed_packet数据写不进去的隐藏元凶第一个高频坑是大记录写入失败。任务跑到某个batch突然报PacketTooBigException错误信息里有max_allowed_packet的字样。这个报错的意思是你单次INSERT语句的包大小超过了MySQL服务器允许的最大值。默认情况下max_allowed_packet在MySQL 8.0是64MB看起来很大但如果batchSize较大、单条记录又包含大字段很容易撞上。比如一条记录里有个2MB的TEXT字段batchSize 1024一次INSERT就有2GB的包远超限制。排查链路是这样的查看MySQL当前配置SHOW VARIABLES LIKE max_allowed_packet;如果值太小临时调大SET GLOBAL max_allowed_packet 536870912;512MB更重要的是调整writer侧把batchSize降到256以下大记录场景甚至直接降到100。同步完成后记得把配置改回来因为过大max_allowed_packet会带来潜在的内存压力。还有一个容易被忽略的版本差异MySQL 8.0的驱动对max_allowed_packet的处理比5.7严格升级数据库之后原本能跑的同步任务可能突然报错排查时别只盯着数据量先看配置。5.2 数据库多个实例的增量同步MySQLWriter怎么配合热门搜索词里有一条是datax 实现数据库多个实例的增量同步这个场景我实际搭建过这里分享下思路。多实例增量同步的核心不是MySQLWriter本身而是它配合reader端的where条件实现每次只同步增量部分。做法大致是在每个源实例的表中找到增量字段比如update_time或自增id。在reader的connection里配置表名和where条件where携带上次同步的水位线。在writer的preSql里做幂等控制先删除同一水位线范围内的旧数据再插入这样即使任务重跑也不会重复。水位线的记录可以放在额外的元数据表里跑批前读取、跑批后更新。DataX本身不负责记录水位线这是任务调度系统比如DataX-web或你自己的cron脚本要做的。MySQLWriter在这个方案里的角色是可靠落盘。insert模式加preSql删除的组合比replace模式更安全因为insert在冲突时报错能尽快暴露问题而replace会悄悄覆盖反而不利于增量数据正确性校验。5.3 主键冲突、死锁和任务重跑的完整处理遇到过这样一个真实场景全量同步任务跑了一半因为网络抖动断掉了重新跑又报主键冲突。原因很简单第一次跑已经插入了一部分数据第二次从头开始跑已插入的部分再次执行insert冲突了。我的处理方式成了固定套路任务设计时就在preSql里写清理SQL把目标表当天要同步的数据先删掉。全量同步就TRUNCATE如果允许增量就DELETE WHERE ...。如果preSql已经删了还是报主键冲突那基本可以断定是reader端读到了重复数据。检查源表的查询逻辑尤其是多表JOIN产生的结果是不是有重复行。死锁报错的话错误信息里通常有Deadlock found when trying to get lock。这时候先确认是不是多个channel并发replace导致的。我的处理是把writeMode切回insert并把channel数降一半死锁问题基本能消除。这里还有一个细节值得记DataX任务失败后下次重跑时reader端读到的数据和上次一样所以所有同步任务都要建立在可重跑的基础上。这应该是MySQLWriter应用里最核心的一条经验也是很多数据同步事故的根源。别指望DataX给你自动断点续传它不干这个活你自己用preSql加上幂等逻辑才是正确的做法。5.4 时区、字符集和特殊字符数据错乱的隐形杀手最后聊一个很隐蔽但影响极大的问题时区和字符集。MySQLWriter写入的datetime类型如果jdbcUrl里没有设置serverTimezoneMySQL 8.0驱动会默认用服务器时区而连接时区和服务器的会话时区不一致时时间数据会出现偏移。最常见的是差了8个小时写入的时间比源端早或晚8小时排查起来非常迷惑。解决方案是在jdbcUrl里显式指定serverTimezoneAsia/Shanghai字符集方面如果表里有emoji这类四字节字符确保jdbcUrl包含characterEncodingutf8mb4而不是utf8——utf8在MySQL里实际是utf8mb3遇到emoji会直接报错或者变成乱码。这个配置要和目标表的字符集保持一致否则轻则显示异常重则任务失败。6. 从MySQLWriter看整个DataX插件机制不只为了配好一个插件很多人学会配MySQLWriter之后会把DataX当成MysqlToMysql工具来用这其实是浪费。MySQLWriter只是DataX的其中一个写端理解它的设计等于理解DataX所有Writer插件的一半。6.1 Writer插件的通用结构DataX里任何Writer插件都有两个核心组成部分Writer和Task。Writer负责初始化、配置校验、任务切分Task是实际干活的执行单元由多个并发实例组成对应前面说的channel数。MySQLWriter的Task内部做的事情是建立数据库连接执行session配置。执行preSql。循环从Channel取数据攒批后批量写入。所有数据写完执行postSql释放连接。切换其他Writer插件比如PostgreSQLWriter、HDFSWriter你会发现配置结构基本是同一套骨架——connection、table、column、preSql、postSql——只是每个插件针对目标端的特性做了适配。所以当你真正了解了MySQLWriter再去用其他插件会非常顺。6.2 容器化部署DataX和MySQLWriter的注意点既然热词里出现容器化部署datax与datax-web我也顺带说下我在Docker里跑DataX的经验。MySQLWriter在容器里的表现和本地没有本质区别但有几个坑值得提防容器内连接MySQL时jdbcUrl不能写localhost或127.0.0.1因为那是容器自己的lo接口要写宿主机IP或者服务发现地址。DataX是Python启动Java进程容器镜像需要同时包含Python环境和JDK构建镜像时容易漏。容器内存限制和JVM堆内存要同步设置否则容器限了内存但JVM不管不顾分配直接被OOMKilled。DataX任务目录要挂载成卷否则每次容器重建要重新上传配置文件日志目录最好也挂出来方便排查。这些细节处理好了DataX在容器里就和一个普通进程一样稳定。6.3 从MySQLWriter扩展出去数据同步方案的架构级思考最后聊聊一个更上层的经验。用MySQLWriter写了那么多同步任务之后我最大的体会是工具只是执行层数据同步方案的成败取决于任务设计和恢复策略。一个好的MySQLWriter使用方案一定要回答这几个问题任务重跑会不会产生重复数据preSql里怎么清理任务失败了一半怎么知道哪些数据已经写进去了目标表的索引会不会拖垮写入性能同步延迟能不能满足业务要求这些都是靠配置之外的工程习惯解决的。比如我习惯在每个同步任务的元数据表里记录开始时间、结束时间、成功条数、失败信息跑批结束后做个简单校验数据对不上就告警。这些朴素的工程实践可比堆channel数管用多了。MySQLWriter本身只是一个插件但你把它放到一个完整的数据同步体系里它就是一个可靠的落地点——上游不管从哪来下游MySQL这边永远有条不紊地接收数据。理解了这一点你配的就不只是一个job.json而是一套能扛住线上环境考验的同步机制。