kettle从入门到精通 第三十课 mysql 数据连接常用配置与 TaoToken 统一 Key 接入

1. Kettle 连 MySQL 总踩坑先把 JDBC 驱动和连接池参数理清楚Kettle 里做数据同步绕不开 MySQL 数据连接。很多人第一次配的时候界面上那一堆勾选框和参数看着就头大驱动放哪、URL 怎么写、字符集为什么乱码、连接池到底要不要开。这篇就按我实际做 ETL 的顺序把 Kettle MySQL 数据连接的常用配置项一个个拆开讲顺带把 API 调用统一走 TaoToken 的 Key 通道这件事也接进来让整条数据链路既能连库、也能调模型。先说清楚这篇适合谁如果你已经在用 KettlePentaho Data Integration简称 PDI做抽取转换或者正准备把 MySQL 作为源库/目标库那这篇的配置片段可以直接抄。Kettle 本身是个开源 ETL 工具负责把数据从 A 搬到 B 并做清洗MySQL 数据连接就是它跟数据库对话的入口。连接配不对后面所有转换步骤都是白搭。我见过最常见的三个问题一是mysql-connector-java的 jar 没放进lib目录点测试直接报找不到驱动二是 JDBC URL 里没带characterEncoding和serverTimezone中文变问号、时间差 8 小时三是连接池参数乱填批量插入慢得离谱。这些都会在下面给出可复制的配置。另外现在很多 ETL 流程里会插入一步「调大模型做字段清洗/分类」比如把商品标题丢给模型做类目归一。这类 API 调用如果每个脚本各写一套 Key管理起来很乱。我的做法是统一走 TaoToken 的 Key/API 通道Kettle 里用「JavaScript 代码」或「HTTP Client」步骤发请求Base URL 指向https://taotoken.net/apiKey 只维护一份。这样数据库连接和模型调用两件事在同一个转换里就能串起来。下面从驱动准备开始一步步到连接测试和报错排查中间会给出kettle.properties和数据库连接配置片段你照着改 IP、库名、账号就能用。2. 驱动、URL 与连接池Kettle MySQL 数据连接配置全流程2.1 把 MySQL 驱动放进 Kettle 的 lib 目录Kettle 不会自带 MySQL 驱动得手动放。去 MySQL 官网或 Maven 仓库下载mysql-connector-java版本建议 8.0.x比如mysql-connector-java-8.0.20.jar。下载完把它复制到 Kettle 安装目录下的lib文件夹# 假设 Kettle 装在 /opt/data-integration cp mysql-connector-java-8.0.20.jar /opt/data-integration/lib/Windows 下就是D:\pdi-ce-9.3\data-integration\lib\。放完重启 SpoonKettle 的图形界面否则类加载器不会重新扫描。这一步不做后面测试连接一定报No suitable driver found。2.2 新建数据库连接核心字段怎么填在 Spoon 里点「主对象树」→「数据库连接」→ 右键新建或者转换里双击「表输入」步骤新建连接。关键字段如下连接名称随便起比如mysql_etl_source。连接类型选MySQL。连接方式选Native (JDBC)。主机名称填 MySQL 的 IP本机就是127.0.0.1。数据库名称填具体的 schema比如etl_db。端口号默认3306。用户名密码按实际填。这里有个容易忽略的点Use Result Stream Cursor建议勾上。它的作用是让查询结果分块返回而不是一次性全塞进内存。处理大表的时候不勾这个Kettle 很容易 OOM。2.3 高级配置里的勾选项含义高级面板里那排勾选框我按实际影响说「支持布尔数据类型」勾上后Kettle 会把true/false转成 MySQL 的TINYINT(1)的1/0。不勾的话插入布尔值可能直接报类型错误。「Supports the timestamp data type」勾上时间戳能正确传递。MySQL 的TIMESTAMP和DATETIME行为不同这个勾选影响写入精度。「标识符使用引号括起来」当你的表名或列名跟 SQL 关键字撞了比如表名叫order勾上它Kettle 会加反引号避免语法错误。「强制标识符使用小写/大写字母」看你的库规范。Linux 下 MySQL 默认表名大小写敏感团队统一小写就勾小写。「默认模式名称」一般留空除非你连的库需要指定 schema 前缀。「连接成功后要执行的 SQL」这个挺实用比如每次连接后设置会话时区SET time_zone 08:00;多条用分号隔开。2.4 选项面板JDBC URL 参数逐个配选项面板里填的是拼到 JDBC URL 后面的参数这是最容易出乱码和时区问题的地方。常用的几个characterEncodingutf8指定字符编码中文库必填。useUnicodetrue配合它一起用。serverTimezoneAsia/Shanghai解决时间差 8 小时。rewriteBatchedStatementstrue批量插入性能提升明显做大批量写入一定开。useSSLfalse本地或内网连接关掉省得证书报错。allowPublicKeyRetrievaltrueMySQL 8 用 caching_sha2 认证时可能需要。defaultFetchSize1000和useCursorFetchtrue配合控制每次从库里取多少行大结果集友好。maxReconnects3和autoReconnecttrue让连接断了自动重连跑长任务时有用。nullCatalogMeansCurrenttrue避免某些驱动版本找不到表。把这些参数整理成一份可复制的配置放在kettle.properties里做全局默认路径是~/.kettle/kettle.propertiesLinux或C:\Users\你的用户名\.kettle\kettle.properties# Kettle 全局 MySQL 连接默认参数 MYSQL_DEFAULT_HOST127.0.0.1 MYSQL_DEFAULT_PORT3306 MYSQL_DEFAULT_DBetl_db MYSQL_JDBC_PARAMSuseUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalserewriteBatchedStatementstrueallowPublicKeyRetrievaltrue然后在数据库连接的「选项」里引用这些参数或者直接在自定义 JDBC URL 里拼jdbc:mysql://127.0.0.1:3306/etl_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalserewriteBatchedStatementstrue2.5 把 API 调用统一到 TaoToken 的 Key 通道ETL 流程里如果要调模型比如对地址做标准化、对评论做情感分类可以在转换里加一个「HTTP Client」或「JavaScript 代码」步骤。统一走 TaoToken 的好处是 Key 只维护一份Base URL 固定换模型只改 Model ID。配置三件套Base URLhttps://taotoken.net/apiAPI Key在控制台创建地址是https://taotoken.net/console/api-keysModel ID按你用的模型填比如对话类或代码类模型用 JavaScript 步骤发请求的示例// Kettle JavaScript 步骤调用 TaoToken 统一 API var apiKey 你的_TaoToken_Key; var baseUrl https://taotoken.net/api; var modelId 你的模型ID; var request new org.apache.commons.httpclient.methods.PostMethod(baseUrl /v1/chat/completions); request.setRequestHeader(Content-Type, application/json); request.setRequestHeader(Authorization, Bearer apiKey); var body JSON.stringify({ model: modelId, messages: [{ role: user, content: 把这条地址标准化 address_field }] }); request.setRequestBody(body); var client new org.apache.commons.httpclient.HttpClient(); var status client.executeMethod(request); var response request.getResponseBodyAsString();这样数据库连接负责读写TaoToken 负责模型调用两条链路在同一个转换里各司其职。Key 的管理集中在 TaoToken 控制台不用散落在各个 ktr 文件里。3. 可复制的 kettle.properties 与数据库连接配置片段这一节把上面散落的配置集中成可直接抄的片段。先看kettle.properties这个文件是 Kettle 的全局变量仓库放在用户目录的.kettle下。除了数据库参数我习惯把 TaoToken 的 Base URL 也放进去方便所有转换引用# MySQL 连接默认值 MYSQL_HOST127.0.0.1 MYSQL_PORT3306 MYSQL_DBetl_db MYSQL_USERetl_user MYSQL_JDBC_PARAMSuseUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalserewriteBatchedStatementstrueallowPublicKeyRetrievaltrueuseCursorFetchtruedefaultFetchSize1000 # TaoToken 统一 API 通道 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEY你的_TaoToken_Key TAOTOKEN_MODEL_ID你的模型ID数据库连接在 ktr 文件里是 XML 结构核心片段长这样你可以直接改字段值connection namemysql_etl_source/name server${MYSQL_HOST}/server typeMYSQL/type accessNative/access database${MYSQL_DB}/database port${MYSQL_PORT}/port username${MYSQL_USER}/username passwordEncrypted 你的加密密码/password attributes attributecodeSUPPORTS_BOOLEAN_DATA_TYPE/codeattributeY/attribute/attribute attributecodeSUPPORTS_TIMESTAMP_DATA_TYPE/codeattributeY/attribute/attribute attributecodeFORCE_IDENTIFIERS_TO_LOWERCASE/codeattributeN/attribute/attribute attributecodeQUOTE_ALL_FIELDS/codeattributeN/attribute/attribute attributecodeUSE_RESULT_STREAM_CURSOR/codeattributeY/attribute/attribute /attributes /connection注意密码字段是 Kettle 加密后的形式你在图形界面填完密码它会自动加密不用手写明文。如果要用变量引用把${MYSQL_HOST}这类占位符填进对应字段即可。连接池参数在「选项」里以键值对形式存在对应 XML 里的connection下的attributes或直接在 URL 里拼。我一般把连接池相关的都塞进 JDBC URL这样迁移 ktr 文件时不用重新点勾选框jdbc:mysql://${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DB}?${MYSQL_JDBC_PARAMS}如果你用 Cline 或 Claude Code 这类工具辅助写 Kettle 脚本也可以把 TaoToken 的配置写进它们的 settings。以 Cline 的 MCP 配置为例Base URL 填https://taotoken.net/apiKey 填控制台生成的Model ID 按需选。这样写脚本和调模型用的是同一套 Key省得来回切。对于长期跑编码任务或 Agent 流程的场景可以考虑用 Coding Plan把模型调用额度集中管理地址是https://taotoken.net/coding-plan。数据库连接这块不涉及额度但如果你在 ETL 里嵌了模型清洗步骤统一通道能省不少事。4. 连接测试与请求验证怎么确认真的通了配置填完别急着跑转换先点「测试」按钮。Kettle 会弹一个对话框显示连接是否成功以及 MySQL 版本。成功的话会看到类似Connected to MySQL 8.0.20的提示。这一步验证的是驱动加载、网络、账号密码、库名都对。如果测试通过再建一个最简单的转换验证数据能读出来拖一个「表输入」步骤写SELECT 1 AS test_col再拖一个「文本文件输出」或直接预览。预览能看到test_col 1说明查询链路通了。验证 TaoToken 通道可以在转换里加一个「JavaScript 代码」步骤发一个最简单的请求把返回打印到日志var apiKey ${TAOTOKEN_API_KEY}; var baseUrl ${TAOTOKEN_BASE_URL}; var request new org.apache.commons.httpclient.methods.PostMethod(baseUrl /v1/chat/completions); request.setRequestHeader(Content-Type, application/json); request.setRequestHeader(Authorization, Bearer apiKey); request.setRequestBody(JSON.stringify({ model: ${TAOTOKEN_MODEL_ID}, messages: [{ role: user, content: 回复 OK 两个字母 }] })); var client new org.apache.commons.httpclient.HttpClient(); var status client.executeMethod(request); var resp request.getResponseBodyAsString(); trans_Status status 200 ? CONTINUE_TRANSFORMATION : ERROR_TRANSFORMATION;跑起来后看日志状态码 200 且返回里有内容说明 Key 和 Base URL 都对。如果返回 401就是 Key 有问题返回 404多半是路径拼错了。数据库这边验证批量写入性能可以建一个「表输出」步骤插 1 万行测试数据对比开不开rewriteBatchedStatements的耗时。我实测下来开了之后批量插入能快好几倍尤其是行数多的时候。还有一个验证点字符集。往表里插一条带中文的记录再读出来看有没有乱码。如果显示问号回去检查characterEncoding和useUnicode是不是都配了以及数据库和表的字符集是不是utf8mb4。5. 常见报错排查401、驱动缺失、时区与连接池问题5.1 找不到驱动No suitable driver found报错原文一般是No suitable driver found for jdbc:mysql://...。原因就一个mysql-connector-java的 jar 没在 Kettle 的lib目录里或者放了没重启 Spoon。解决确认 jar 在lib下重启 Spoon。如果用的是 Kettle 9.x 配 MySQL 8驱动版本要 8.0.x5.x 的驱动连 MySQL 8 会报认证错误。5.2 认证失败Access denied 和 401数据库侧报Access denied for user etl_user%是账号权限或密码不对。检查 MySQL 里GRANT有没有给对密码有没有特殊字符被转义。TaoToken 侧报 401是 API Key 无效或没带Authorization头。检查 Key 是不是从https://taotoken.net/console/api-keys复制的完整串请求头格式是不是Bearer 你的Key。如果报local proxy failed通常是网络出口或代理配置问题检查 Kettle 所在机器的网络能不能访问https://taotoken.net/api。5.3 时区错乱时间差 8 小时现象是写进库的时间比实际少 8 小时或多 8 小时。原因是 JDBC 驱动和 MySQL 服务端时区不一致。解决URL 里加serverTimezoneAsia/Shanghai同时在「连接成功后执行的 SQL」里加SET time_zone 08:00;。两个都配上基本不会再错。5.4 读取结果报错reading choices 相关如果调模型返回的 JSON 解析时报reading choices之类的错说明返回结构跟你代码里取字段的路径对不上。先打印完整response看结构再按实际路径取choices[0].message.content。不同模型返回格式可能有差异别硬编码。5.5 连接池相关连接断开与重连长任务跑到一半报连接断开加autoReconnecttrue和maxReconnects3。但要注意autoReconnect在某些事务场景下不可靠更稳的做法是在转换里加错误处理步骤捕获后重试。useCursorFetchtrue配defaultFetchSize能减少大结果集的内存压力但如果你的 MySQL 版本或驱动不支持游标去掉这两个参数改用Use Result Stream Cursor勾选。5.6 OAuth 与 Codex auth.json 场景如果你在用 Codex 类的工具认证信息存在auth.json里路径通常是~/.codex/auth.json。要把它指向 TaoToken 通道需要改里面的 Base URL 和 Key 字段。配置三件套还是那三样Base URL 填https://taotoken.net/apiKey 填控制台生成的Model ID 按需选。改完重启工具生效。这一步和 Kettle 无关但如果你在 ETL 流程里调了 Codex 做代码生成就会碰到。排查顺序建议先测数据库连接再测模型通道最后跑完整转换。哪一步报错就盯哪一步别一上来就怀疑整个流程。6. 把 Key 和连接配置收拢到一处后续维护省一半事数据库连接和模型调用这两件事配一次不难难的是后面改。IP 换了、密码改了、模型换了如果配置散在十几个 ktr 文件里改起来就是灾难。我的做法是MySQL 的连接参数全部走kettle.properties变量TaoToken 的 Base URL 和 Key 也放进去ktr 文件里只引用变量名。这样换环境只改一个文件。TaoToken 的 Key 在控制台可以随时轮换地址是https://taotoken.net/console/api-keys。轮换后只改kettle.properties里的TAOTOKEN_API_KEY所有引用它的转换自动生效。接入文档在https://taotoken.net/doc里面有各语言的调用示例Kettle 里用 JavaScript 步骤的话参考 HTTP 那部分就行。如果你在 ETL 里嵌的模型调用比较重比如每天要跑几万条数据清洗可以看看 Coding Plan 的额度方案地址是https://taotoken.net/coding-plan。数据库连接本身不消耗额度但模型调用走统一通道后用量和账单都在一个地方看对账方便。最后留一个我踩过的坑Kettle 的「表输出」步骤默认是逐行提交批量写入一定要在步骤里勾「使用批量插入」并把批大小设成 1000 以上配合 URL 里的rewriteBatchedStatementstrue速度差别很大。这个和连接配置是两回事但经常一起用顺手提一句。