MariaDB JDBC驱动3.0.4版本setFetchSize调用报invalid fetch size错误

报错触发场景 #

从MariaDB JDBC驱动2.7.2版本升级到3.0.4版本时，调用setFetchSize(Integer.MIN_VALUE)会抛出如下异常：

java.sql.SQLSyntaxErrorException: (conn=27489500) invalid fetch size

问题根因 #

• 该报错是3.x大版本移除历史非标准兼容逻辑导致的设计内行为，不属于版本bug。
• 1.4.0版本之前的MariaDB JDBC驱动未遵循JDBC规范实现结果集拉取逻辑，仅认可Statement.setFetchSize(Integer.MIN_VALUE)作为触发流式逐行拉取的特殊标识；1.4.0版本上线了符合JDBC规范的实现，支持传入≥0的正整数设置拉取批次大小，其中setFetchSize(1)和旧写法Integer.MIN_VALUE效果完全等价，当时开发团队出于向下兼容考虑暂时保留了对Integer.MIN_VALUE的支持。
• 3.0大版本迭代时，团队清理了大量不符合JDBC规范的历史兼容代码，其中就包括对Integer.MIN_VALUE这个非标准入参的支持，该变更属于3.0.0版本的破坏性升级项，仅在大版本升级的不兼容变更列表中公示，没有在3.0.4这类补丁版本的发布说明中重复提及，因此容易被升级用户忽略。
• JDBC官方规范明确要求setFetchSize方法的入参取值必须≥0，Integer.MIN_VALUE属于早期驱动自定义的特殊值，本来就不在长期兼容承诺范围内。

官方推荐处理方案 #

• 直接替换为setFetchSize(1)即可，这是官方推荐的符合JDBC规范的流式查询写法，在1.4.0之后的所有正式版本（包括2.x、3.x全系列）都能稳定生效，效果和旧的Integer.MIN_VALUE完全一致，不会出现功能差异。
• 如果业务场景需要平衡内存占用和查询性能，可以根据实际情况将fetchSize设置为大于1的正整数（比如setFetchSize(500)/setFetchSize(1000)），驱动会按照设定的批次大小从服务端拉取结果，相比逐行拉取能减少网络交互次数，提升查询效率。
• 注意事项：3.x版本中要让fetchSize配置生效，需要确保Statement使用的是ResultSet.TYPE_FORWARD_ONLY类型，且关闭结果集并发更新能力，否则配置的fetchSize会被驱动忽略，回退为全量加载结果集到内存的模式。

内容的提问来源于stack exchange，提问作者Mr_Thorynque