SeaTunnel DuckDB 源连接器实战指南：基于 JDBC 读取 DuckDB 数据库文件

SeaTunnel DuckDB 源连接器实战指南基于 JDBC 读取 DuckDB 数据库文件【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel本文围绕 docs/zh/connectors/source/DuckDB.md 展开系统讲解 SeaTunnel 中 JDBC DuckDB 源连接器的原理与用法。DuckDB 是进程内embedded的 SQL OLAP 数据库其连接器对接的是本地数据库文件jdbc:duckdb:/path/to/database.db或内存数据库而非远程服务端。读完本文你将掌握该连接器的依赖部署、数据类型映射、全部源选项参数、并行读取拆分机制并能直接照搬 5 个可运行的 HOCON 配置示例完成单表、并行、多表读取任务。连接器概述DuckDB 源连接器是 SeaTunnel 中 JDBC 连接器 体系下的一个专用方言dialect实现。它通过 JDBC 驱动org.duckdb.DuckDBDriver读取 DuckDB 数据库中的数据由于 DuckDB 属于嵌入式 OLAP 数据库SeaTunnel 进程内直接打开本地.db文件即可查询不存在独立的服务端与网络监听端口。该连接器在仓库中的核心实现位于 seatunnel-connectors-v2/connector-jdbc 模块的internal/dialect/duckdb包下包括DuckDBDialect负责表路径解析、标识符引用quote等方言行为DuckDBTypeConverter/DuckDBTypeMapper负责 DuckDB 类型与 SeaTunnel 类型的双向转换DuckDBJdbcRowConverter负责 JDBC ResultSet 到 SeaTunnel 行数据的转换。从DatabaseIdentifier的定义DUCKDB DuckDB见 DatabaseIdentifier.java可以看到该连接器在 JDBC 连接器内部以DuckDB方言注册配置文件中source名称既可写Jdbc也可直接使用Jdbc加driver参数指定。支持版本与运行引擎支持 DuckDB 版本0.8.x / 0.9.x / 0.10.x / 1.x。支持的引擎Spark、Flink、SeaTunnel Zeta。说明不同 DuckDB 版本对应的驱动类一致org.duckdb.DuckDBDriver但驱动 jar 包版本需与本地数据库文件格式兼容。DuckDB 官方保证向前兼容读取但建议使用与生成.db文件相同或更高版本的驱动。依赖部署对于 Spark / Flink 引擎需要将 DuckDB JDBC 驱动 jar 包org.duckdb:duckdb_jdbc放置到${SEATUNNEL_HOME}/plugins/目录中。对于 SeaTunnel Zeta 引擎需要将 DuckDB JDBC 驱动 jar 包放置到${SEATUNNEL_HOME}/lib/目录中。SeaTunnel 的插件发现与类加载机制会从对应目录加载驱动具体原理可参考 plugin-discovery-and-class-loading.md。部署完成后建议通过本文并行边界示例中的properties参数附加 DuckDB 运行参数如threads、memory_limit进行验证。主要功能功能支持情况批处理Batch✅ 支持流处理Streaming❌ 不支持精确一次Exactly-Once✅ 支持列投影Column Projection✅ 支持通过 SQL 查询实现并行度Parallelism✅ 支持用户自定义拆分User-Defined Split✅ 支持连接器支持 SQL 查询因此天然可以通过select col1, col2 ...实现列投影效果仅将需要的字段下发到下游。支持的数据源信息数据源支持的版本驱动器网址Maven 下载DuckDB不同依赖版本具有不同的驱动程序类org.duckdb.DuckDBDriverjdbc:duckdb:/path/to/database.db在 Maven 中央仓库搜索org.duckdb:duckdb_jdbcURL 支持三种形态参见源码 DuckDBURLParser.java 中的解析正则^jdbc:duckdb:(?path[^?]*?)(?suffix\?.*)?$jdbc:duckdb:默认内存数据库jdbc:duckdb:/path/to/file.duckdb本地文件数据库jdbc:duckdb:memory:?optionvalue内存数据库并附加连接参数。数据类型映射DuckDB 与 SeaTunnel 的类型映射由 DuckDBTypeConverter.java 实现完整映射关系如下DuckDB 数据类型SeaTunnel 数据类型BOOLEANBOOLEANTINYINTTINYINTUTINYINTSMALLINTSMALLINTUSMALLINTINTEGERINTUINTEGERBIGINTBIGINTUBIGINTDECIMAL(20,0)HUGEINTDECIMAL(38,0)FLOATFLOATDOUBLEDOUBLEDECIMAL(x,y)精度 38DECIMAL(x,y)DECIMAL(x,y)精度 38DECIMAL(38,18)VARCHARCHARTEXTJSONUUIDINTERVALSTRINGDATEDATETIMETIMETIMESTAMPTIMESTAMP WITH TIME ZONETIMESTAMPBLOBARRAYSTRUCTMAPBYTES结合源码映射规则有几个值得注意的细节上限截断DuckDBTypeConverter中定义了MAX_PRECISION 38、MAX_SCALE 38。当 DECIMAL 的精度超过 38 时会被截断为DECIMAL(38, …)scale 为负数时会被钳制为 0超过 38 会被截断为 38。复杂类型退化ARRAY、STRUCT、MAP 在读取时映射为 STRING长度上限 65535并输出 WARN 日志提示可考虑 JSON 序列化BLOB 映射为 BYTES。这与文档表格中BLOB/ARRAY/STRUCT/MAP → BYTES的写法略有差异源码中 BLOB 走 BYTES复杂类型走 STRING实际以当前仓库 DuckDBTypeConverter.java 的实现为准。TIMESTAMP WITH TIME ZONE源码中映射为OFFSET_DATE_TIME_TYPE对应 SeaTunnel 的 TIMESTAMP_TZ测试用例 DuckDBTypeConverterTest.java 明确断言了这一行为。未知类型回退未识别的类型统一回退为 STRING 并记录 WARN 日志见 DuckDBTypeConverter.java保证任务不会因个别字段类型无法识别而中断。完整的转换行为均有对应的单元测试覆盖DuckDBTypeConverterTest.java包含各类整数、无符号类型、HUGEINT、DECIMAL 截断、UUID/JSON/INTERVAL、复杂类型回退等 30 余个用例。源选项Source Options以下选项定义于 JdbcSourceOptions.java 与 JdbcCommonOptions.java适用于 DuckDB 源名称类型是否必需默认值描述urlString是-JDBC 连接 URL例如jdbc:duckdb:/path/to/database.dbdriverString是-JDBC 驱动类名DuckDB 固定为org.duckdb.DuckDBDriverusernameString否-连接实例用户名passwordString否-连接实例密码queryString是-查询语句connection_check_timeout_secInt否30等待用于验证连接的数据库操作完成的时间秒partition_columnString否-并行分区列名仅支持数字类型主键且只能配置一列partition_lower_boundBigDecimal否-扫描的partition_column最小值未设置时 SeaTunnel 会查询数据库获取partition_upper_boundBigDecimal否-扫描的partition_column最大值未设置时 SeaTunnel 会查询数据库获取partition_numInt否作业并行度分区数量仅支持正整数fetch_sizeInt否0查询的行抓取大小通过减少数据库命中次数提升性能0 表示使用 JDBC 默认值propertiesMap否-附加连接配置参数。当 properties 与 URL 中参数相同时优先级由驱动实现决定——DuckDB 中 properties 优先于 URLtable_pathString否-表的完整路径可替代query例如main.table1table_listArray否-要读取的表列表可替代table_path支持每张表独立配置querywhere_conditionString否-所有表/查询的通用行过滤条件必须以where开头例如where id 100split.sizeInt否8096表的拆分大小行数读取时表被拆分为多个拆分common-options-否-源插件通用参数见 Source Common Options关键选项的源码级说明partition 系列选项partition_column、partition_lower_bound、partition_upper_bound、partition_num定义于 JdbcSourceOptions.java。上下界未配置时连接器会自动向数据库执行SELECT MIN(...)/SELECT MAX(...)获取边界值。split.size默认 8096定义于 JdbcSourceOptions.java。这是控制拆分粒度的推荐手段。table_list 的默认分区数当某个表未显式配置partition_num时JdbcSourceTableConfig.java 中定义了DEFAULT_PARTITION_NUMBER 10。同时当table_list中表数量超过 1 时源码会校验所有table_path必须唯一且非空否则抛出异常见 JdbcSourceTableConfig.java。fetch_size默认 0 表示使用 JDBC 驱动默认抓取行为设置为正数可减少大批量查询的往返次数。并行读取与拆分机制JDBC 源连接器支持从表中并行读取数据。SeaTunnel 使用特定规则将表数据拆分为多个拆分split交由多个读取器并行消费读取器的数量由parallelism选项决定。拆分键选择规则若配置了partition_column则使用该列计算拆分。该列必须属于支持的拆分数据类型。若partition_column为空SeaTunnel 会读取表 schema获取主键与唯一索引若主键/唯一索引包含多个列则选取其中第一个属于支持的拆分数据类型的列进行拆分。例如表主键为(guid, name varchar)由于guid不在支持类型中将回退使用name列拆分。支持的拆分数据类型StringNumberint、bigint、decimal 等Date与拆分相关的选项选项类型默认值说明split.sizeInt8096一个拆分包含多少行表在读取时被拆分为多个拆分partition_columnString-用于拆分数据的列名partition_upper_boundBigDecimal-扫描的partition_column最大值未设置时自动查询数据库获取partition_lower_boundBigDecimal-扫描的partition_column最小值未设置时自动查询数据库获取partition_numInt作业并行度需要拆分成多少个拆分仅支持正整数。不建议使用正确做法是通过split.size控制拆分数量提示如果表无法拆分例如表没有主键、没有唯一索引且未设置partition_column该表将以单并发方式运行。读取单表时使用table_path替代query可开启自动拆分读取多表时请使用table_list。任务示例以下示例均来自 DuckDB.md可直接复制运行示例中均使用/tmp/test.db数据库文件和user_events表需按实际环境调整。示例一简单查询在单并行度下查询user_events表的所有字段并输出到控制台。你也可以在query中指定字段以实现列投影# 定义运行时环境 env { parallelism 4 job.mode BATCH } source{ Jdbc { url jdbc:duckdb:/tmp/test.db driver org.duckdb.DuckDBDriver connection_check_timeout_sec 100 username duckdb password query select * from user_events limit 16 } } transform { # 转换插件配置可参考 https://seatunnel.apache.org/docs/transforms/sql } sink { Console {} }示例二通过 partition_column 并行以id列为分区键按split.size 10000拆分充分利用作业并行度读取全表env { parallelism 4 job.mode BATCH } source { Jdbc { url jdbc:duckdb:/tmp/test.db driver org.duckdb.DuckDBDriver connection_check_timeout_sec 100 username duckdb password query select * from user_events partition_column id split.size 10000 # 读取开始边界 #partition_lower_bound ... # 读取结束边界 #partition_upper_bound ... } } sink { Console {} }示例三通过主键或唯一索引并行配置table_path将开启自动拆分无需手动指定partition_column可配置split.*调整拆分策略env { parallelism 4 job.mode BATCH } source { Jdbc { url jdbc:duckdb:/tmp/test.db driver org.duckdb.DuckDBDriver connection_check_timeout_sec 100 username duckdb password table_path main.user_events query select * from main.user_events split.size 10000 } } sink { Console {} }注意table_path中的main是 DuckDB 的默认 schema。从 DuckDBDialect.java 的parse方法可以看到两段式路径如schema.table会被解析为默认数据库default下的schema.table单段路径如table则会补全为default.main.table。示例四并行边界显式指定读取的上下边界让数据读取更高效同时演示通过properties注入 DuckDB 运行时参数线程数与内存上限source { Jdbc { url jdbc:duckdb:/tmp/test.db driver org.duckdb.DuckDBDriver connection_check_timeout_sec 100 username duckdb password # 根据需要定义查询逻辑 query select * from user_events partition_column id # 读取开始边界 partition_lower_bound 1 # 读取结束边界 partition_upper_bound 500 partition_num 10 properties { threads4 memory_limit4GB } } }提示properties中配置的threads与memory_limit是 DuckDB 驱动的本地运行参数会被原样传递给 JDBC 驱动当properties与 URL 中参数冲突时DuckDB 驱动以properties为准。示例五多表读取配置table_list将开启自动拆分可配置split.*调整拆分策略。每张表可以独立指定query进行行/列过滤env { job.mode BATCH parallelism 4 } source { Jdbc { url jdbc:duckdb:/tmp/test.db driver org.duckdb.DuckDBDriver connection_check_timeout_sec 100 username duckdb password table_list [ { table_path main.table1 }, { table_path main.table2 # 使用查询过滤行和列 query select id, name from main.table2 where id 100 } ] #where_condition where id 100 #split.size 8096 } } sink { Console {} }where_condition是作用于table_list中所有表的通用过滤条件必须以where开头它与单表内的query过滤可以同时生效。使用table_list时需保证各table_path唯一且非空否则连接器会直接报错见 JdbcSourceTableConfig.java。测试验证仓库在 seatunnel-connectors-v2/connector-jdbc/src/test 下提供了完整的 DuckDB 方言测试可作为接入与排错参考DuckDBTypeConverterTest.java覆盖全部类型的正向/反向转换与截断行为DuckDBDialectTest.java验证表路径解析与标识符引用DuckDBSourceAndSinkTest.java验证完整的源/目标读写链路DuckDBConnectDryRunValidationTest.java验证连接校验dry run流程。常见问题与建议驱动加载失败ClassNotFoundException确认duckdb_jdbcjar 已按引擎类型放入plugins/Spark/Flink或lib/SeaTunnel Zeta。表无法并行读取检查表是否设置了主键/唯一索引或显式配置partition_column都不满足时将以单并发读取。DECIMAL 精度丢失当 DuckDB 列精度超过 38 时会被截断为DECIMAL(38,18)文档口径或DECIMAL(38,n)源码口径建表时尽量将精度控制在 38 以内。复杂类型ARRAY/STRUCT/MAP建议在查询中先使用 DuckDB 的to_json()等函数序列化后再读取避免读取为原始字符串。控制拆分数量优先使用split.size而非partition_num后者已被标注为不建议使用。变更记录DuckDB 源连接器属于 JDBC 连接器体系其历史变更可查阅 connector-jdbc 变更日志原文档通过ChangeLog /组件引用该文件。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考