{"record":{"id":"ad9a5572c8e25f4e","repo":"mybatis/mybatis-3","slug":"sqlrunner-requires-an-instance-of-null-to-represen","errorCode":null,"errorMessage":"SqlRunner requires an instance of Null to represent typed null values for JDBC compatibility","messagePattern":"SqlRunner requires an instance of Null to represent typed null values for JDBC compatibility","errorType":"validation","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/jdbc/SqlRunner.java","lineNumber":219,"sourceCode":"    }\n  }\n\n  /**\n   * @deprecated Since 3.5.4, this method is deprecated. Please close the {@link Connection} outside of this class.\n   */\n  @Deprecated\n  public void closeConnection() {\n    try {\n      connection.close();\n    } catch (SQLException e) {\n      // ignore\n    }\n  }\n\n  private void setParameters(PreparedStatement ps, Object... args) throws SQLException {\n    for (int i = 0, n = args.length; i < n; i++) {\n      if (args[i] == null) {\n        throw new SQLException(\n            \"SqlRunner requires an instance of Null to represent typed null values for JDBC compatibility\");\n      }\n      if (args[i] instanceof Null) {\n        ((Null) args[i]).getTypeHandler().setParameter(ps, i + 1, null, ((Null) args[i]).getJdbcType());\n      } else {\n        TypeHandler typeHandler = typeHandlerRegistry.getTypeHandler(args[i].getClass());\n        if (typeHandler == null) {\n          throw new SQLException(\"SqlRunner could not find a TypeHandler instance for \" + args[i].getClass());\n        } else {\n          typeHandler.setParameter(ps, i + 1, args[i], null);\n        }\n      }\n    }\n  }\n\n  private List<Map<String, Object>> getResults(ResultSet rs) throws SQLException {\n    List<Map<String, Object>> list = new ArrayList<>();\n    List<String> columns = new ArrayList<>();","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/jdbc/SqlRunner.java#L201-L237","documentation":"SqlRunner.setParameters() throws SQLException when a raw null appears in the argument list. JDBC drivers need a concrete jdbcType to set NULL, and SqlRunner has no annotation/XML to read it from, so you must pass the sentinel object org.apache.ibatis.jdbc.SqlRunner.Null (e.g. SqlRunner.NULL) which carries a TypeHandler and jdbcType.","triggerScenarios":"Calling sqlRunner.update/insert/select with a plain Java null argument: runner.update(\"update users set nickname=? where id=?\", null, 1). Any null literal, null-valued variable, or uninitialized field passed as a vararg triggers it.","commonSituations":"Test fixtures inserting rows with nullable columns; passing a nullable POJO getter result directly; forgetting that SqlRunner's API differs from PreparedStatement.setNull(i, type).","solutions":["Replace the null argument with SqlRunner.NULL (VARCHAR) or new Null(JdbcType.NUMERIC) / other jdbc types as appropriate.","Where possible, avoid binding null by skipping the column from the INSERT statement.","Wrap nullable values at the call site: value == null ? SqlRunner.NULL : value."],"exampleFix":"// before\nrunner.update(\"update users set nickname=? where id=?\", null, 42);\n\n// after\nrunner.update(\"update users set nickname=? where id=?\", SqlRunner.NULL, 42);","handlingStrategy":"validation","validationCode":"// Wrap nullable values before passing to SqlRunner\nObject safe(Object v) {\n  return v == null ? SqlRunner.NULL : v;\n}\nrunner.update(\"update users set nickname=? where id=?\", safe(nickname), 42);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never pass raw null literals to SqlRunner varargs; use SqlRunner.NULL or new Null(JdbcType.X).","Pick the Null matching the column's JDBC type (e.g. Null.NUMERIC for numeric columns) to avoid driver-side type errors.","Remember SqlRunner is a test/utility class — production code should use mapper interfaces where jdbcType comes from XML."],"tags":["mybatis","jdbc","null-handling","sql-runner"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}