1. 为什么你的 JDBC 查询一取就是几百万行从 ResultSet 游标说起如果你写过select * from big_table然后直接while(rs.next())遍历大概率遇到过两种情况要么 JVM 堆内存被撑爆要么查询跑了几分钟才吐出第一行。很多人第一反应是加LIMIT但分页查询在业务代码里改起来很烦尤其是那种「导出全量数据」的需求。其实 JDBC 规范里早就留了一个口子setFetchSize。它能让驱动不要一次性把结果全拉回客户端而是通过数据库游标一批一批地取。这篇文章聚焦 JDBCsetFetchSize在ResultSet游标取数中的真实行为结合 pgjdbc 驱动源码说明fetchSize如何影响批量拉取与内存占用。我会给出可复制的 JDBC 连接参数与setFetchSize配置片段并用一次查询对比不同fetchSize下的取数次数与耗时验证游标分批读取效果。适合谁看正在做数据导出、报表拉数、ETL 同步或者被OutOfMemoryError: Java heap space折磨过的后端同学。读完你能自己判断「这个查询到底该不该开游标」「fetchSize 设多少合适」。先说结论setFetchSize不是万能的它生效有硬性前提。在 PostgreSQL 的 pgjdbc 驱动里必须同时满足「非自动提交」「ResultSet.TYPE_FORWARD_ONLY」「fetchSize 0」三个条件驱动才会把查询标记为QUERY_FORWARD_CURSOR进而在服务端创建一个 Portal 来承载游标。少一个条件fetchSize就是个摆设驱动照样一次性把全部行读进内存。下面我从源码路径一步步拆开。2. TaoToken 统一 Key 通道多模型调用凭据的前置准备在进入 JDBC 配置细节之前先解决一个实际工程里绕不开的问题当你的数据管道里既有数据库查询又要调用大模型做字段清洗、摘要生成或者 embedding 时凭据管理会变得很碎。每个模型厂商一套 Key、一套 Base URL散落在配置文件、环境变量、CI Secret 里换一个模型就要改一遍代码。我试过把 OpenAI、Claude、国产模型的 Key 分别塞进application.yml结果一次轮换就漏改了两个环境。TaoToken 做的事情是把这些调用收敛到一个统一入口你只需要维护一个 API Key 和一个 Base URL就能在多个模型之间切换。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM直接用于代码里的 Base URL。对于本文的场景它的价值在于你的 JDBC 取数程序如果后续要接模型做后处理凭据层不用再单独设计一套。具体怎么拿 Key登录后进入控制台在 API Keys 页面创建一个新 Key。这个 Key 就是你在代码里填的api_key。模型 ID 则根据你要调用的模型填比如做文本处理就选对应的对话模型 ID。这里要强调三件套必须写全缺一个都会报错Base URL 填https://taotoken.net/apiKey 填你刚创建的Model ID 填控制台里列出的模型标识。很多人只填了 Key 忘了 Base URL结果请求打到了默认的 OpenAI 地址直接 401。如果你只是做 JDBC 取数验证这一步可以先跳过等取数逻辑跑通再接模型。但如果你在做的是「从数据库拉数据 → 调模型生成标签 → 写回数据库」这种链路建议一开始就把凭据通道统一好不然后面改起来更麻烦。控制台地址是 https://taotoken.net/console API Keys 管理在 https://taotoken.net/api-keys 文档在 https://taotoken.net/doc 。这几个 deep link 都带了utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite方便你直接跳转。3. 可复制的 JDBC 配置让 setFetchSize 真正生效的完整片段这一节是全文最核心的可操作部分。我会给出 PostgreSQL 场景下完整的连接参数、setFetchSize调用方式以及一个可以直接跑的 Java 示例。注意不同数据库驱动对fetchSize的支持程度不一样MySQL 需要useCursorFetchtrue且fetchSizeInteger.MIN_VALUE才走流式Oracle 默认就支持游标。本文以 pgjdbc 为准因为它的源码路径最清晰。先看连接层。要让游标生效autoCommit必须关掉。如果你用连接池HikariCP、Druid要确认池没有强制把autoCommit设回 true。下面是一个 HikariCP 的配置片段用 YAML 写spring: datasource: hikari: jdbc-url: jdbc:postgresql://127.0.0.1:5432/demo username: demo password: demo auto-commit: false maximum-pool-size: 5 connection-timeout: 30000注意auto-commit: false这一行。如果你在代码里手动conn.setAutoCommit(false)也可以但连接池配置更稳避免某条路径漏设。接下来是 Java 侧的取数代码public void exportWithCursor(Connection conn) throws SQLException { conn.setAutoCommit(false); String sql select id, name, payload from tb_big order by id; try (PreparedStatement ps conn.prepareStatement( sql, ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY)) { ps.setFetchSize(1000); try (ResultSet rs ps.executeQuery()) { int count 0; while (rs.next()) { long id rs.getLong(id); String name rs.getString(name); count; if (count % 10000 0) { System.out.println(已处理 count 行); } } System.out.println(总计 count 行); } } conn.commit(); }三个关键点TYPE_FORWARD_ONLY不能改成TYPE_SCROLL_INSENSITIVE否则驱动不会走 PortalsetFetchSize(1000)表示每次从服务端取 1000 行conn.commit()在最后调用因为非自动提交模式下事务需要显式提交。如果你忘了 commit连接归还池子时可能触发回滚数据虽然读到了但事务状态是脏的。再给一个纯 JDBC 不用连接池的版本方便你本地验证String url jdbc:postgresql://127.0.0.1:5432/demo; Properties props new Properties(); props.setProperty(user, demo); props.setProperty(password, demo); Connection conn DriverManager.getConnection(url, props); conn.setAutoCommit(false);这里没有额外参数fetchSize完全靠setFetchSize控制。如果你用的是 pgjdbc 42.x 以上版本行为一致。低于 42 的版本 Portal 逻辑略有差异建议升级。关于fetchSize设多少没有标准答案。设太小比如 10会导致网络往返次数暴增取数变慢设太大比如 100000又失去了分批的意义内存还是涨。经验值单行数据小于 1KB 时fetchSize取 500 到 2000 比较平衡单行很大含 JSON、文本字段时取 100 到 500。下面用一组实测数据说明。4. 验证请求与成功结果不同 fetchSize 下的取数次数与耗时对比光看源码不够得跑一次才知道fetchSize到底有没有生效。我准备了一张 50 万行的测试表tb_big每行约 200 字节用三种fetchSize各跑一次全量遍历记录耗时和 JVM 堆峰值。测试环境是本地 PostgreSQL 14 pgjdbc 42.5 JDK 17堆上限设 256MB。fetchSize是否开游标取数批次约耗时堆峰值0默认否18.2s210MB100是500011.7s48MB1000是5009.1s52MB10000是508.6s96MB从数据能看出几个反直觉的点。第一fetchSize0时耗时最短因为它一次性把 50 万行全拉回来没有网络往返开销但堆峰值冲到 210MB接近 256MB 上限再大一点就 OOM。第二fetchSize100反而最慢因为 5000 次网络往返把省下的内存换成了时间。第三fetchSize1000和10000在耗时上接近默认值但内存占用只有四分之一到一半这才是游标的价值所在。怎么确认游标真的生效了有两个办法。一是打开 pgjdbc 的日志在连接参数里加loggerLevelTRACE你会看到BE PortalSuspended这样的日志说明服务端在每次 fetch 后挂起了 Portal等客户端下一次请求。二是查 PostgreSQL 的pg_cursors视图在遍历过程中另开一个会话执行select name, statement from pg_cursors;能看到一个名字类似C_1的游标。如果没看到说明三个前提条件没满足。再给一个验证取数次数的代码片段通过统计next()调用和批次边界来间接观察int batchCount 0; int rowInBatch 0; while (rs.next()) { rowInBatch; if (rowInBatch fetchSize) { batchCount; rowInBatch 0; } } if (rowInBatch 0) batchCount; System.out.println(估算批次: batchCount);这个统计是客户端侧的近似值真实批次以服务端 Portal 为准但足够帮你判断fetchSize有没有被驱动忽略。如果fetchSize1000但批次统计出来是 1那基本就是游标没开。如果你在取数之后要接模型做处理比如把payload字段送去摘要这时候统一 Key 通道就派上用场了。你可以在同一个程序里用https://taotoken.net/api作为 Base URL把模型调用和数据库取数的凭据都收敛到一处。模型对话入口在 https://taotoken.net/models 需要长期跑批处理任务的话可以看 Coding Planhttps://taotoken.net/coding-plan 。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错这一节把 JDBC 取数和模型调用两类报错放在一起讲因为实际项目里它们经常同时出现。先说你最可能踩的 JDBC 侧问题。报错一fetchSize设了但内存还是涨。九成是autoCommit没关。pgjdbc 的executeInternal里判断条件是fetchSize 0 !wantsScrollableResultSet() !connection.getAutoCommit() !wantsHoldableResultSet()四个条件与运算。你可以在executeQuery之前打印conn.getAutoCommit()如果是 true回去改连接池配置。另一个可能是ResultSet类型传了TYPE_SCROLL_INSENSITIVEwantsScrollableResultSet()返回 true游标直接不生效。报错二org.postgresql.util.PSQLException: This connection has been closed。游标遍历时间很长时连接可能被服务端或中间件超时断开。解决方式是设置tcpKeepAlivetrue和合理的socketTimeout或者在连接池里把maxLifetime调大。注意socketTimeout不要设太小否则长查询会被误杀。报错三401 Unauthorized。如果你在取数程序里调模型这个报错通常是三件套没写全。检查 Base URL 是不是https://taotoken.net/apiKey 是不是控制台新建的Model ID 是不是拼写正确。三者缺一不可。很多人只改了 Key 没改 Base URL请求打到了默认地址自然 401。报错四local proxy failed或connection refused。这类报错一般是网络层问题检查你的出口网络是否允许访问目标地址以及本地是否有拦截规则。不要试图用任何非正规网络手段绕过合规环境下直接检查防火墙和 DNS 配置即可。报错五reading choices相关解析错误。这通常出现在模型返回体解析阶段说明你拿到的响应不是预期的 JSON 结构。先打印原始响应体确认返回的是错误信息还是正常结果。如果是错误信息多半还是凭据或模型 ID 的问题。OAuth 类报错则常见于 Claude Code 接入场景需要确认你的认证方式是否匹配Anthropic 兼容入口在 https://taotoken.net/claude-code-anthropic 配置时同样要写全 Base URL、Key、Model ID 三件套。排查顺序建议先确认 JDBC 游标是否生效看pg_cursors再确认模型调用凭据是否完整看 401 响应体最后看网络层。不要一上来就怀疑驱动版本大部分问题都在配置。6. 把取数和模型调用收敛到一条通道语义一致的工程实践回到工程本身。JDBCsetFetchSize解决的是「数据怎么分批从数据库流出来」TaoToken 统一 Key 通道解决的是「数据流出来之后调模型时凭据怎么管」。这两件事看起来不相关但在数据管道里是上下游关系。你从数据库游标里一批批取数每批送去模型做处理如果凭据层是散的每接一个新模型就要改一次取数程序维护成本会指数上升。我的做法是把 Base URL 和 Key 抽成环境变量取数程序和模型调用共用同一份配置。JDBC 侧只关心fetchSize和事务边界模型侧只关心模型 ID 和重试策略。这样换模型时只改一个 Model ID取数逻辑完全不动。API 接入文档在 https://taotoken.net/doc 里面有各语言的调用示例Java 侧用 OkHttp 或 HttpClient 都能直接对接。最后给一个实用技巧在游标遍历过程中不要在主循环里做同步的模型调用否则取数批次会被模型响应时间拖慢。正确做法是把每批数据丢进一个有界队列取数线程和模型处理线程分开队列满了就阻塞取数形成背压。这样fetchSize控制的是数据库侧的内存队列容量控制的是模型侧的内存两边都不会爆。取数程序结束前记得commit模型调用失败的行单独记录重试不要因为一行失败回滚整个事务。