简介这份资源是经过源码改造的DataX数据同步引擎专门解决PostgreSQL中geometry地理空间类型无法通过原生DataX正常同步的问题面向需要处理空间数据ETL的数据库开发与数据集成工程师。包内共113个文件以97个jar依赖为核心辅以10个json配置、3个Python脚本、1个xml、1个md说明及1个properties文件压缩包约56.67MB其中plugin目录下的reader与writer仅保留postgresql和rdbms模块结构精简、开箱即用。使用时只需将下载的DataX压缩包替换本地DataX即可若需接入其他数据库把对应模块复制进plugin目录便能扩展。目前已有490人学习下载适合希望快速打通PostGIS空间字段同步链路、减少自行改造引擎成本的开发者参考可省去从零调试源码的时间直接获得可运行的改造版本与依赖清单。1. DataX 改造引擎支持 geometry 类型同步从丢字段到空间数据完整落库做数仓的同学大概率遇到过这种场景MySQL 里存着POINT、POLYGON、MULTIPOLYGON这类 geometry 字段用 DataX 抽到 Hive 或者另一套 MySQL 时任务不报错但目标表里那一列全是null或者干脆被截断成一段乱码。我第一次碰到这个问题时排查了大半天最后发现是 DataX 内置的 MySQL Reader 和 Writer 对 geometry 类型没有做专门处理走的是默认的字符串转换逻辑二进制 WKB 数据在中间环节被静默丢弃。这篇笔记就围绕「DataX 改造引擎支持 geometry 类型同步」这件事把原理、改造点、参数配置和踩坑记录讲清楚。适合正在做空间数据同步、GIS 平台数据迁移、或者单纯被 geometry 字段坑过的后端和数据工程师。读完你能自己动手改 Reader 和 Writer 插件让 geometry 字段完整地从源库落到目标库。2. 为什么 DataX 默认同步不了 geometry类型映射与二进制链路拆解2.1 DataX 的类型转换机制到底在哪一层丢数据DataX 的核心设计是 Reader 和 Writer 解耦中间通过Record和Column传递数据。Reader 负责从源库读取数据并转换成 DataX 内部类型Writer 负责把内部类型再转成目标库的类型。问题就出在这个「内部类型」上。DataX 内部定义的类型非常有限主要是Long、Double、String、Boolean、Date、Bytes这几种。MySQL Reader 在读取时会通过ResultSetMetaData.getColumnType()拿到列的 JDBC 类型然后走一个switch分支映射到内部类型。geometry 字段在 JDBC 里对应的类型是BINARY或VARBINARY但 MySQL Connector/J 对 geometry 列返回的getColumnType()有时是LONGVARBINARY有时是BINARY取决于驱动版本和useInformationSchema等参数。关键问题在于MySQL Reader 默认的getColumnType映射表里BINARY/VARBINARY这类类型如果没有显式配置会被归到Bytes或者直接走String转换。而 geometry 的二进制是 WKB 格式里面包含字节0x00一旦被当成字符串处理遇到0x00就截断了。这就是为什么你看到的结果要么是null要么是一小段乱码。另一个丢数据的地方在 Writer 端。MySQL Writer 在写入时会根据目标列的columnType决定用setString还是setBytes。如果目标列是 geometry 类型但 Writer 拿到的是String类型的内部值它可能会调用setString而 MySQL 对 geometry 列的setString行为是不确定的很多版本直接报错或者写入空值。2.2 geometry 在 MySQL 里的存储格式与 WKB 字节序要改造先得搞清楚 geometry 在 MySQL 里到底存的是什么。MySQL 的 geometry 类型底层存储是 WKBWell-Known Binary格式外加 4 个字节的 SRID空间参考系 ID。具体结构是部分长度说明SRID4 字节小端序整数标识空间参考系WKB变长OGC 标准定义的几何二进制WKB 本身第一个字节是字节序标记0x01表示小端序0x00表示大端序。第二个到第五个字节是几何类型1Point, 2LineString, 3Polygon, 4MultiPoint, 5MultiLineString, 6MultiPolygon, 7GeometryCollection。后面跟着坐标数据。MySQL 在SELECT一个 geometry 列时默认返回的是不带 SRID 的 WKB除非你用ST_AsWKB或者直接查内部格式。但如果你用SELECT geom_column FROM tableJDBC 驱动返回的byte[]实际上是 MySQL 内部格式也就是带 4 字节 SRID 的。这一点非常关键因为如果你在 Reader 里直接把这个byte[]透传给 WriterWriter 再用setBytes写回去MySQL 是能识别的。但如果你中间做了任何字符串转换SRID 那 4 个字节可能就被吃掉了。2.3 改造点定位Reader 端和 Writer 端各要动什么改造的核心思路是让 Reader 把 geometry 列读成Bytes类型并且保留完整的字节数组让 Writer 在遇到目标列为 geometry 时用setBytes写入。Reader 端需要改的地方在com.alibaba.datax.plugin.reader.mysqlreader.MysqlReader$Task类里具体是getColumnType方法或者transportOneRecord方法。常见做法是增加一个判断如果columnType是BINARY、VARBINARY、LONGVARBINARY或者GEOMETRY就强制走Bytes分支并且用resultSet.getBytes(columnIndex)而不是getString。Writer 端需要改的地方在com.alibaba.datax.plugin.writer.mysqlwriter.MysqlWriter$Task里具体是fillPreparedStatement方法。当内部Column的类型是Bytes且目标列类型是 geometry 时调用preparedStatement.setBytes(index, (byte[]) column.getRawData())。还有一个容易被忽略的点DataX 的Column类在setRawData时如果传入的是byte[]它会正确存储。但如果你在 Reader 里用了String类型Column会调用toString()那就全毁了。所以改造的第一步是确保 Reader 输出的是Bytes类型。提示不同版本的 DataX 源码包结构略有差异但核心类名和包路径基本一致。改造前先确认你用的是哪个版本建议基于官方 master 分支或者稳定 release 版本改不要在生产环境直接改编译好的 jar。3. 动手改 Reader让 geometry 列以 Bytes 类型完整读出3.1 定位 MysqlReader 的类型映射代码先把 DataX 源码拉下来找到mysqlreader插件模块。路径通常是datax/plugin/reader/mysqlreader/src/main/java/com/alibaba/datax/plugin/reader/mysqlreader/MysqlReader.java。里面有一个内部类Task继承自Reader.Task。在Task类里找到startRead或者transportOneRecord方法。通常长这样private void transportOneRecord(Record record, ResultSet resultSet, ...) { for (int i 0; i columnCount; i) { String columnType resultSetMetaData.getColumnTypeName(i 1); // 默认走字符串 record.setColumn(i, new StringColumn(resultSet.getString(i 1))); } }这段代码就是罪魁祸首。resultSet.getString对 geometry 列会返回乱码或者 null。我们要改成根据列类型判断。3.2 增加 geometry 类型判断与 Bytes 分支改造后的代码逻辑如下private void transportOneRecord(Record record, ResultSet resultSet, ResultSetMetaData metaData, int columnCount) throws SQLException { for (int i 0; i columnCount; i) { int columnIndex i 1; String columnTypeName metaData.getColumnTypeName(columnIndex).toUpperCase(); int columnType metaData.getColumnType(columnIndex); // 判断是否为 geometry 或二进制类型 if (GEOMETRY.equals(columnTypeName) || POINT.equals(columnTypeName) || LINESTRING.equals(columnTypeName) || POLYGON.equals(columnTypeName) || MULTIPOINT.equals(columnTypeName) || MULTILINESTRING.equals(columnTypeName) || MULTIPOLYGON.equals(columnTypeName) || GEOMETRYCOLLECTION.equals(columnTypeName) || columnType Types.BINARY || columnType Types.VARBINARY || columnType Types.LONGVARBINARY) { byte[] bytes resultSet.getBytes(columnIndex); if (bytes null) { record.setColumn(i, new BytesColumn(null)); } else { record.setColumn(i, new BytesColumn(bytes)); } } else { // 原有逻辑 String value resultSet.getString(columnIndex); record.setColumn(i, new StringColumn(value)); } } }这段代码的核心改动是先通过getColumnTypeName拿到数据库层面的类型名再结合getColumnType的 JDBC 类型做双重判断。为什么两个都要因为 MySQL 驱动对 geometry 列的getColumnType返回值不稳定有的版本返回BINARY有的返回VARBINARY但getColumnTypeName通常能稳定返回GEOMETRY或者具体的子类型名。两个条件用||连接覆盖面更广。BytesColumn是 DataX 内部类型构造时传入byte[]。注意这里不要做任何编码转换直接透传原始字节。resultSet.getBytes对 geometry 列返回的就是 MySQL 内部格式的字节数组包含 SRID 和 WKB。3.3 编译打包与替换插件改完代码后在mysqlreader模块目录下执行 Maven 打包cd datax/plugin/reader/mysqlreader mvn clean package -DskipTests打包完成后在target目录下会生成mysqlreader-xxx.jar。把这个 jar 替换到 DataX 安装目录的plugin/reader/mysqlreader/下注意保留原来的plugin.json和libs目录结构。如果你不想动源码还有一个取巧的办法在 DataX 的 job.json 里把 geometry 列配置成type: bytes。但实测这个办法对 MySQL Reader 不生效因为 Reader 端根本不认这个配置它只认自己的类型映射逻辑。所以还是得改代码。注意替换 jar 之前先备份原文件。如果 DataX 是集群部署每个节点都要替换。替换后建议先用一个只有几行数据的小表做验证不要直接上生产大表。4. 动手改 Writer让 Bytes 类型正确写入 geometry 列4.1 定位 MysqlWriter 的 PreparedStatement 填充逻辑Writer 端的代码在datax/plugin/writer/mysqlwriter/src/main/java/com/alibaba/datax/plugin/writer/mysqlwriter/MysqlWriter.java。找到内部类Task里的fillPreparedStatement方法或者叫doOneInsert。默认逻辑大概是private void fillPreparedStatement(PreparedStatement ps, Record record, ListColumn columns) throws SQLException { for (int i 0; i columns.size(); i) { Column column columns.get(i); switch (column.getType()) { case STRING: ps.setString(i 1, column.asString()); break; case LONG: ps.setLong(i 1, column.asLong()); break; // ... 其他类型 default: ps.setObject(i 1, column.getRawData()); } } }问题在于default分支。如果column.getType()是BYTES它可能会走setObject而 MySQL 驱动对setObject传入byte[]到 geometry 列的行为是不确定的。我们需要显式处理BYTES类型。4.2 增加 BYTES 类型到 setBytes 的映射改造后的代码private void fillPreparedStatement(PreparedStatement ps, Record record, ListColumn columns) throws SQLException { for (int i 0; i columns.size(); i) { Column column columns.get(i); switch (column.getType()) { case STRING: ps.setString(i 1, column.asString()); break; case LONG: ps.setLong(i 1, column.asLong()); break; case DOUBLE: ps.setDouble(i 1, column.asDouble()); break; case BOOLEAN: ps.setBoolean(i 1, column.asBoolean()); break; case DATE: ps.setTimestamp(i 1, new Timestamp(column.asDate().getTime())); break; case BYTES: byte[] rawBytes (byte[]) column.getRawData(); if (rawBytes null) { ps.setNull(i 1, Types.BINARY); } else { ps.setBytes(i 1, rawBytes); } break; default: ps.setObject(i 1, column.getRawData()); } } }关键点是case BYTES分支。column.getRawData()返回的是Object实际类型是byte[]强转后调用ps.setBytes。MySQL 驱动在收到setBytes时如果目标列是 geometry 类型它会直接把字节数组写入不做额外转换。前提是字节数组的格式必须是 MySQL 内部格式带 SRID 的 WKB而 Reader 端getBytes拿到的正好就是这个格式所以能无缝对接。如果目标列是POINT而不是GEOMETRYsetBytes同样有效因为 MySQL 内部对这两种类型的存储格式是一样的只是约束不同。4.3 目标表 DDL 与列类型对齐检查Writer 改完之后还要确认目标表的 DDL。如果源表是GEOMETRY目标表也必须是GEOMETRY或者对应的子类型。如果目标表建成了BLOB或者VARBINARY虽然setBytes也能写进去但数据就失去了空间语义后续没法用ST_AsText等函数查询。常见做法是目标表 DDL 和源表保持一致CREATE TABLE target_table ( id BIGINT NOT NULL, geom GEOMETRY DEFAULT NULL, name VARCHAR(255) DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;如果目标表是 Hive那又是另一回事。Hive 没有原生 geometry 类型通常用STRING存 WKT 或者BINARY存 WKB。这种情况下 Writer 端需要额外做一次ST_AsWKB或者ST_AsText转换但那就不是 DataX 插件层面能解决的了得在 SQL 里用SELECT ST_AsText(geom)提前转好。这篇笔记聚焦的是 MySQL 到 MySQL 的 geometry 同步跨异构存储的转换后面再说。提示建目标表时字符集建议用utf8mb4虽然 geometry 列本身不受字符集影响但同一张表里的其他字符串列可能会因为字符集不一致导致写入失败。5. 避坑与排查geometry 同步改造中最容易翻车的 5 个点5.1 现象任务不报错但目标表 geometry 列全是 null原因Reader 端没有改仍然走getString而 geometry 的 WKB 字节里包含0x00被字符串截断后变成空值Writer 收到空值就写 null。解决确认 Reader 端transportOneRecord方法里已经增加了 geometry 判断分支并且用的是resultSet.getBytes。改完后重新编译打包替换 jar 后重启 DataX 进程。验证方法是先跑一条SELECT geom FROM source_table LIMIT 1在 Reader 里打日志输出字节数组长度确认不是 0。5.2 现象Writer 报错 Cannot get geometry object from data you send to the GEOMETRY field原因Writer 端虽然走了setBytes但传入的字节数组不是 MySQL 内部格式。常见于 Reader 端用了ST_AsWKB(geom)查询返回的是纯 WKB 不带 SRID而 MySQL 的 geometry 列要求带 SRID 前缀。解决要么在 Reader 端直接SELECT geom拿内部格式要么在 Writer 端写入前手动补上 4 字节 SRID。补 SRID 的代码逻辑是取原始 WKB 的前 5 个字节判断字节序和类型然后在前面插入 4 字节的 SRID通常用 0 表示无参考系或者 4326 表示 WGS84。但更简单的做法是直接用SELECT geom让 MySQL 驱动返回内部格式。5.3 现象同步到一半任务失败日志显示 Data truncation: Cannot create a geometry object from data原因源表里有的 geometry 列值是 null或者包含非法几何数据。Reader 端getBytes返回 null 时如果 Writer 端没有处理 null 分支setBytes会报错。解决在 Writer 的case BYTES分支里增加 null 判断用ps.setNull(i 1, Types.BINARY)代替ps.setBytes。同时检查源表数据质量用SELECT COUNT(*) FROM source_table WHERE geom IS NULL OR ST_IsValid(geom) 0排查非法数据。5.4 现象小表同步正常大表同步时内存溢出原因geometry 字段的 WKB 数据可能很大尤其是MULTIPOLYGON类型一个字段可能几 MB。DataX 默认的channel和batchSize配置下大量 geometry 数据堆积在内存里导致 OOM。解决调小batchSize在 job.json 的setting.speed里把byte限制调低或者增加channel数量分散压力。另外可以在 Reader 端增加流式读取逻辑不要一次性把所有 Record 都缓存在内存里。实测把batchSize从 2048 降到 512同时channel从 4 增加到 8能有效缓解大 geometry 字段的 OOM 问题。5.5 现象改造后 MySQL 到 MySQL 正常但 MySQL 到 Oracle 或 PostgreSQL 失败原因不同数据库对 geometry 的二进制格式要求不同。Oracle 的SDO_GEOMETRY是自定义对象类型PostgreSQL 的 PostGIS 用的是 EWKB 格式和 MySQL 的内部格式不兼容。解决跨异构数据库同步 geometry 时不要走二进制透传而是在 Reader 端用ST_AsText转成 WKT 字符串Writer 端再用目标库的函数转回 geometry。比如 MySQL 到 PostgreSQLReader SQL 写成SELECT ST_AsText(geom) FROM source_tableWriter 端配置 PostgreSQL 的ST_GeomFromText函数。这种方式会损失一些精度和性能但兼容性最好。注意跨库同步时SRID 也要对齐。MySQL 里 SRID 4326 和 PostgreSQL 里 SRID 4326 虽然语义一样但二进制格式不同必须走 WKT 中转。6. 进阶技巧用 DataX 做增量 geometry 同步与数据校验改造完 Reader 和 Writer 只是第一步实际生产环境里还要解决增量同步和数据校验的问题。我一般会这么干。增量同步方面geometry 字段本身没有时间戳所以增量依赖业务表的主键或者更新时间字段。在 job.json 的 Reader SQL 里加上WHERE update_time ${last_sync_time}然后用 DataX 的调度工具传入变量。注意 geometry 字段在增量同步时同样要走改造后的 Bytes 分支不要因为加了 WHERE 条件就改回getString。数据校验方面同步完成后不能只看任务成功日志得实际比对源表和目标表的 geometry 数据。我常用的校验 SQL 是-- 在源库执行 SELECT id, ST_AsText(geom) AS wkt, ST_SRID(geom) AS srid FROM source_table WHERE update_time 2024-01-01 00:00:00; -- 在目标库执行同样的 SQL然后比对结果如果 WKT 和 SRID 都一致说明同步没问题。如果 WKT 一致但 SRID 不一致说明 Writer 端写入时 SRID 丢了需要检查 Reader 端是否用了ST_AsWKB而不是直接SELECT geom。还有一个进阶玩法是用 DataX 的transformer功能在 Reader 和 Writer 之间插入自定义转换逻辑。比如源表 SRID 是 4326目标表要求 3857可以在 transformer 里调用ST_Transform。但 DataX 的 transformer 对二进制类型支持有限实测直接传byte[]进去会报类型转换错误所以这个方案我试了一次就放弃了还是老老实实在 Reader SQL 里用ST_Transform(geom, 3857)提前转好。最后说一个我踩过的坑DataX 的 job.json 里column配置如果写了type: string即使 Reader 端改成了 BytesWriter 端也会因为配置强制转成 String。所以 job.json 里 geometry 列的 type 要么不写要么写type: bytes。这个细节坑了我一个下午血泪经验。希望帮到你。本文还有配套的精品资源点击获取