TDSQL 报错 Proxy ERROR: CURSOR_TYPE_READ_ONLY is not support yet 的排查与配置修正

1. 这个报错到底卡在哪一步TDSQL 是腾讯云推出的分布式数据库产品兼容 MySQL 协议很多团队在迁移或新建业务时都会选它。但当你用 JDBC 驱动连上 TDSQL 的 Proxy 接入层后可能会在日志里看到这样一行Proxy ERROR: CURSOR_TYPE_READ_ONLY is not support yet这个报错的意思是客户端向 Proxy 请求了一个「只读游标」类型的结果集但 TDSQL 的 Proxy 层目前还不支持这种游标模式。它不是一个网络问题也不是权限问题而是驱动和代理之间的协议兼容性缺口。谁最容易踩到这个坑三类人一是从原生 MySQL 迁移到 TDSQL、沿用了旧连接串的开发者二是用了 ORM 框架比如 MyBatis、Hibernate默认开启了流式查询或游标 fetch 的项目三是在数据同步、大批量导出场景里手动设置了useCursorFetchtrue的同学。这些场景的共同点是客户端主动要求「服务端游标」而 TDSQL Proxy 只认普通结果集。我试过在一个 Spring Boot 项目里复现这个问题连接串里带了useCursorFetchtrue一执行分页查询就报这个错。下面把定位思路和修正配置一步步拆开讲你可以直接照着改。2. 动手前先把 TaoToken 的接入信息准备好在改连接配置之前如果你还需要一个稳定的模型对话或编码辅助环境来对照排查可以先把 TaoToken 的入口配好。它在这里的角色是帮你快速验证 SQL 片段、生成连接参数对照、或者让 coding agent 直接读你的报错日志给出修改建议。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址不带 UTM直接用于代码里https://taotoken.net/api如果你只是想让模型帮你分析这段报错用模型对话页最省事https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite如果你打算长期用 coding agent 来改 JDBC 配置、跑回归建议走 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite需要生成 API Key 时在这里操作https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code 用户走这个入口https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite这些链接先收好后面排查到驱动参数时你可以直接把报错和连接串丢给模型对话让它帮你比对差异。3. 可复制的连接配置修正片段核心思路只有一句话把客户端主动要求服务端游标的参数关掉让结果集走普通模式。3.1 JDBC 连接串修正原始有问题的连接串通常长这样jdbc:mysql://tdsql-proxy-host:3306/your_db?useCursorFetchtrueuseServerPrepStmtstrue修正后jdbc:mysql://tdsql-proxy-host:3306/your_db?useCursorFetchfalseuseServerPrepStmtsfalseserverTimezoneGMT%2B8关键点三个useCursorFetchfalse这是直接触发CURSOR_TYPE_READ_ONLY的开关必须关。useServerPrepStmtsfalse服务端预处理语句在某些 Proxy 版本下也会联动游标行为一并关掉更稳。serverTimezoneGMT%2B8TDSQL 环境里时区不显式指定容易出别的乱子顺手补上。3.2 代码里动态移除游标参数如果你用的是连接池HikariCP、Druid参数可能写在配置类里。参考下面这段逻辑在数据源初始化时把游标相关属性摘掉if (mysql.equalsIgnoreCase(db.getPluginId())) { dbMeta.getAttributes().remove(EXTRA_OPTION_MYSQL.useCursorFetch); if (!db.getAttributes().containsKey(EXTRA_OPTION_MYSQL.serverTimezone)) { dbMeta.getAttributes().put(EXTRA_OPTION_MYSQL.serverTimezone, GMT8); } }这段代码的作用是识别到 MySQL 系插件时强制移除useCursorFetch扩展属性并兜底设置时区。它适合放在数据源元信息构建阶段避免参数从上层透传下来。3.3 MyBatis 流式查询的替代写法如果你原本用ResultHandler或CursorT做流式查询改成普通分页select idselectLargeData resultTypeYourEntity SELECT * FROM your_table WHERE id #{lastId} ORDER BY id LIMIT #{pageSize} /select用「游标分页」代替「服务端游标」既绕开了 Proxy 限制又不会一次性把全表拉进内存。3.4 参数对照表参数报错时取值修正后取值作用useCursorFetchtruefalse关闭服务端游标请求useServerPrepStmtstruefalse关闭服务端预处理serverTimezone未设置GMT8固定时区defaultFetchSize1000不设置避免触发 fetch 模式注意不同 TDSQL 版本对 Proxy 的支持范围有差异改完参数后务必在测试环境跑一遍完整查询链路不要直接上生产。4. 验证请求是否真的修好了改完配置不能只看「没报错」要做三步验证。4.1 最小复现脚本先用一个最简单的 JDBC 程序确认String url jdbc:mysql://tdsql-proxy-host:3306/test_db?useCursorFetchfalseuseServerPrepStmtsfalseserverTimezoneGMT%2B8; try (Connection conn DriverManager.getConnection(url, user, password); Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(SELECT id, name FROM test_table LIMIT 10)) { while (rs.next()) { System.out.println(rs.getLong(id) - rs.getString(name)); } }如果这段跑通且日志里不再出现CURSOR_TYPE_READ_ONLY说明连接层已经对了。4.2 打开驱动日志确认游标类型在连接串里临时加上loggercom.mysql.cj.log.StandardLoggerprofileSQLtrue观察输出里结果集的 fetch 模式。修正后应该看到普通结果集而不是READ_ONLY游标。4.3 在业务查询上回归拿你实际报错的那条 SQL在测试环境用修正后的数据源跑一遍。重点看三个指标查询是否返回完整数据、分页是否正常、连接池有没有因为参数变更出现连接泄漏。提示如果验证时还报别的 Proxy 错误把完整日志贴到模型对话里让它帮你比对参数差异比逐行翻文档快得多。5. 本篇常见错排查5.1 改了连接串还是报同样的错大概率是参数没生效。检查顺序连接池配置类是否覆盖了连接串参数 → 是否有多个数据源指向同一个库 → 环境变量里是否还有旧的useCursorFetchtrue。用SHOW VARIABLES看不到客户端参数得从应用侧打印实际生效的 URL。5.2 报错消失但查询结果变少这是把useCursorFetch关掉后某些 ORM 的流式逻辑失效导致的。检查你的 Mapper 是否依赖Cursor返回值改成普通List接收或者用LIMIT分页。5.3 时区相关报错跟着出现serverTimezone写成GMT8在 URL 里需要转义成GMT%2B8否则会被解析成空格。这个坑很隐蔽报错信息通常和时区无关但连接就是建不起来。5.4 其他驱动版本差异MySQL Connector/J 8.x 和 5.x 对游标参数的处理不同。8.x 里useCursorFetch默认 false但如果你从旧项目复制了连接串可能带着 true。建议统一升级到 8.0.28 以上并在连接串里显式写死修正后的参数。5.5 Proxy 版本兼容性确认如果所有参数都改对了还是报错联系 TDSQL 运维确认 Proxy 版本。部分早期版本对CURSOR_TYPE_READ_ONLY的支持是硬缺失只能靠客户端规避没有服务端开关。6. 后续接入与工具分流排查完这个报错如果你想把「报错日志 → 参数修正 → 回归验证」这条链路固化下来可以按用途选入口需要生成和管理 API Key 来跑自动化验证脚本走 API Keys 页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite需要对照完整接入参数和示例走接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite只是想让模型帮你分析某段 JDBC 配置或报错堆栈用模型对话最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite打算长期用 coding agent 维护数据源配置、跑回归测试选 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后留一个我踩过的坑改完useCursorFetch后别忘了同步改连接池的connectionInitSql有些池子会在建连时执行初始化语句如果那里还带着游标相关设置等于白改。把连接串、池配置、ORM 三层都过一遍这个报错基本就绝迹了。