Skip to content

JDBC-事务与批处理 ​

[TOC]

事务控制 ​

数据库事务(Transaction) 是访问并更新数据库的最小逻辑工作单元,具备原子性(Atomicity)、一致性(Consistency)、隔离性(Isolation)和持久性(Durability) 四大 ACID 特性。

在 JDBC 架构中,事务的生命周期与物理数据库连接(java.sql.Connection)严格绑定。同一个事务内的所有 SQL 语句必须通过同一个 Connection 实例发送执行;一旦跨越多个独立的 Connection 实例,底层数据库服务端会将其识别为多个互不相关的并发会话,无法通过本地事务保证原子性。

自动提交与手动事务机制 ​

JDBC 规范通过控制 Connection 会话的自动提交(Auto-Commit) 状态,在单语句独立事务与多语句组合事务之间进行切换。

自动提交(默认) ​

当通过 DriverManager 或数据源新创建一个 Connection 实例时,规范默认将其置于自动提交模式(即 autoCommit 属性为 true)。

在此模式下,应用程序向数据库发送的每一条独立 DML 语句(INSERT、UPDATE、DELETE)都会被数据库引擎自动包裹在一个隐式事务中,语句执行完毕的瞬间立即自动提交落盘。一旦遇到需要多条更新语句协同完成的业务场景(如银行转账需先后执行“扣减转出方余额”与“增加转入方余额”两条 UPDATE 语句),若第一条扣款语句自动提交成功后,第二条加款语句因网络中断或代码异常未能执行,第一条语句已提交的数据将无法撤销,直接破坏业务数据的一致性。

手动事务 ​

为了将多条 SQL 语句纳入同一个原子工作单元,必须在执行业务 SQL 之前显式关闭自动提交模式:

  1. 开启事务边界:调用连接对象的自动提交设置方法传入 false,底层驱动会向数据库服务端发送开启手动事务指令(如 MySQL 的 SET autocommit=0),相当于显式开启了一个事务块(BEGIN / START TRANSACTION)。

  2. 正常提交持久化:当同一连接下的所有 DML 语句均执行成功且未发生业务异常时,显式触发提交操作,通知数据库服务端将当前事务缓冲区(Redo/Undo Log)中的所有变更永久刷新并释放行锁。

  3. 异常整体回滚:若事务块内任意一条 SQL 抛出 SQLException 或业务逻辑抛出运行时异常,必须在 catch 代码块中显式捕获并触发回滚操作,由数据库利用 Undo Log 撤销当前事务自开启以来所做的全部数据修改。

会话绑定与连接池状态污染陷阱 ​

在工程实践中编写手动事务代码时,存在两个高频边界陷阱:

  1. 跨 DAO 方法连接分裂陷阱:在分层架构中,一个业务层(Service)方法往往会先后调用多个数据访问层(DAO)方法。如果每个 DAO 方法内部都各自调用 DriverManager.getConnection 获取新连接,那么扣款和加款实际上运行在两条不同的 TCP 物理连接上,外层业务方法即便捕获异常也无法回滚已由另一条连接提交的数据。要使事务生效,必须通过方法参数传递或 ThreadLocal 线程本地变量,确保同一事务链路中的所有 DAO 操作共享同一个 Connection 实例。

  2. 连接池会话状态污染陷阱:在使用数据库连接池的生产环境中,调用 conn.close() 并不会真正断开物理连接,而是将该连接对象归还给连接池供后续线程复用。如果在事务结束后未将 autoCommit 恢复为默认的 true 就直接归还连接,下一个从池中借出该连接的线程在执行普通单条更新时,会因为连接仍处于 autoCommit = false 状态且未显式调用 commit 而导致数据迟迟无法落盘,甚至长时间持有行锁引发死锁。因此,必须在 finally 代码块中先恢复自动提交状态再关闭连接:

    java
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.PreparedStatement;
    import java.sql.SQLException;
    
    public class TransferTransactionDemo {
    
      public static void main(String[] args) {
        String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
        String debitSql = "UPDATE t_user SET balance = balance - ? WHERE username = ?";
        String creditSql = "UPDATE t_user SET balance = balance + ? WHERE username = ?";
    
        Connection conn = null;
        try {
          conn = DriverManager.getConnection(url, "root", "123456");
    
          // 1. 关闭自动提交模式,开启手动事务边界
          conn.setAutoCommit(false);
    
          // 2. 在同一 Connection 会话下执行扣款与加款操作
          try (PreparedStatement debitStmt = conn.prepareStatement(debitSql);
             PreparedStatement creditStmt = conn.prepareStatement(creditSql)) {
    
            debitStmt.setDouble(1, 200.00);
            debitStmt.setString(2, "Alice");
            debitStmt.executeUpdate();
    
            // 3. 模拟业务执行中途发生运行时异常
            int error = 1 / 0;
    
            creditStmt.setDouble(1, 200.00);
            creditStmt.setString(2, "Bob");
            creditStmt.executeUpdate();
          }
    
          // 4. 所有语句执行无误后显式提交事务,将变更持久化落盘
          conn.commit();
        } catch (Exception e) {
          // 5. 捕获任何异常时回滚整个事务,撤销当前事务内未提交的修改
          if (conn != null) {
            try {
              conn.rollback();
              System.out.println("检测到异常,事务已安全回滚");
            } catch (SQLException ex) {
              ex.printStackTrace();
            }
          }
        } finally {
          // 6. 关闭或归还连接前恢复默认自动提交状态,防止污染连接池会话
          if (conn != null) {
            try {
              conn.setAutoCommit(true);
              conn.close();
            } catch (SQLException e) {
              e.printStackTrace();
            }
          }
        }
      }
    }

保存点局部回滚机制 ​

在复杂的多阶段长事务中,有时并不希望因为某个非核心分支步骤失败而将前面已经成功完成的主干操作全部作废(例如创建订单主记录并扣减基础库存成功后,尝试扣减附加赠品库存失败,此时只需放弃赠品步骤而保留主订单)。

image-20261031110844289

JDBC 3.0 引入了 java.sql.Savepoint(事务保存点)接口,允许在当前活跃事务的 Undo Log 时间线上打入具名或匿名的逻辑检查点标记(对应 SQL 指令 SAVEPOINT sp_name):

  1. 局部撤销变更:当后续非核心分支发生异常时,将目标 Savepoint 实例传入带参的 rollback(Savepoint) 方法。数据库仅会回滚该保存点创建之后执行的 DML 变更,而在该保存点创建之前执行的 SQL 修改依然保留在当前未提交事务中。

  2. 主事务仍需最终提交:回滚到保存点并不会结束整个事务。局部回滚处理完毕后,外层主流程依然需要显式调用 conn.commit(),才能使保存点之前保留下来的修改以及局部回滚后新执行的补偿操作真正持久化生效:

    java
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.PreparedStatement;
    import java.sql.SQLException;
    import java.sql.Savepoint;
    
    public class SavepointRollbackDemo {
    
      public static void main(String[] args) {
        String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
        String updateSql = "UPDATE t_user SET balance = balance - ? WHERE username = ?";
    
        try (Connection conn = DriverManager.getConnection(url, "root", "123456");
           PreparedStatement pstmt = conn.prepareStatement(updateSql)) {
    
          // 1. 开启手动事务并执行第一阶段核心扣款操作
          conn.setAutoCommit(false);
          pstmt.setDouble(1, 100.00);
          pstmt.setString(2, "Alice");
          pstmt.executeUpdate();
    
          // 2. 在第一阶段完成后设立事务保存点标记
          Savepoint spAfterFirstDebit = conn.setSavepoint("SP_AFTER_FIRST_DEBIT");
    
          try {
            // 3. 执行第二阶段附加操作并模拟业务校验失败
            pstmt.setDouble(1, 50.00);
            pstmt.setString(2, "Alice");
            pstmt.executeUpdate();
            throw new RuntimeException("附加优惠扣减校验失败"); // 模拟失败
          } catch (RuntimeException e) {
            // 4. 仅回滚保存点之后的第二阶段修改,保留第一阶段成果
            conn.rollback(spAfterFirstDebit);
            System.out.println("已局部回滚至保存点: " + e.getMessage());
          }
    
          // 5. 提交主事务,第一阶段扣款正式生效
          conn.commit();
        } catch (SQLException e) {
          e.printStackTrace();
        }
      }
    }

事务隔离级别与并发控制 ​

当多个数据库连接会话并发读写同一张表的数据时,若缺乏隔离控制,不同事务之间的交叉执行会引发三类典型的读一致性异常。

并发读一致性异常 ​

根据事务间相互干扰的严重程度,并发读一致性异常分为以下三种:

  • 脏读(Dirty Read):事务 A 读取到了事务 B 已修改但尚未提交的临时数据;随后事务 B 因异常执行了回滚,导致事务 A 读到的数据在数据库中根本不存在。
  • 不可重复读(Non-Repeatable Read):事务 A 在同一事务内先后两次读取同一行记录,在此期间事务 B 修改并提交了该行记录的字段值,导致事务 A 前后两次读取同一行得到的结果不一致(侧重于 UPDATE 引发的单行值变化)。
  • 幻读(Phantom Read):事务 A 按某个范围条件查询记录集,在此期间事务 B 在该范围内插入或删除并提交了新的记录行,导致事务 A 再次按相同条件查询时发现多出或少了几行“幽灵记录”(侧重于 INSERT / DELETE 引发的结果集行数变化)。

标准隔离级别映射 ​

为了在数据一致性与并发吞吐量之间进行权衡,java.sql.Connection 接口定义了四个标准整型常量,分别映射 SQL 标准的四种事务隔离级别(隔离强度由低到高,并发性能由高到低):

  1. TRANSACTION_READ_UNCOMMITTED(读未提交,常量值 1):最低隔离级别,允许读取其他并发事务未提交的修改,无法防御脏读、不可重复读与幻读。

  2. TRANSACTION_READ_COMMITTED(读已提交,常量值 2):基于语句级一致性视图(MVCC ReadView),保证只能读取其他事务已经提交的数据,消除了脏读,但仍可能出现不可重复读与幻读。这是 Oracle、PostgreSQL 和 SQL Server 数据库的默认隔离级别。

  3. TRANSACTION_REPEATABLE_READ(可重复读,常量值 4):在事务首次读取时固定一致性快照视图(或加行级读锁),保证同一事务内多次读取同一行记录的结果完全一致,消除了脏读与不可重复读。这是 MySQL InnoDB 存储引擎的默认隔离级别(InnoDB 同时结合 MVCC 与 Next-Key Lock 临键锁在很大程度上解决了幻读)。

  4. TRANSACTION_SERIALIZABLE(串行化,常量值 8):最高隔离级别,强制所有读写事务通过加锁排队串行执行,彻底消除脏读、不可重复读与幻读,但并发性能最低。

image-20261031110921126

会话隔离级别切换 ​

在 JDBC 中,开发者可以在开启手动事务之前动态查看或调整当前 Connection 会话的隔离级别(底层驱动会向数据库发送 SET SESSION TRANSACTION ISOLATION LEVEL ... 指令):

java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class TransactionIsolationDemo {

  public static void main(String[] args) {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";

    try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
      // 1. 查询当前数据库连接默认的事务隔离级别常量值
      int defaultLevel = conn.getTransactionIsolation();
      System.out.println("默认隔离级别常量值: " + defaultLevel);

      // 2. 在开启事务前将当前会话隔离级别切换为读已提交(READ COMMITTED)
      conn.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);
      conn.setAutoCommit(false);

      // 3. 验证切换后的当前会话隔离级别并提交事务
      System.out.println("切换后隔离级别常量值: " + conn.getTransactionIsolation());
      conn.commit();
    } catch (SQLException e) {
      e.printStackTrace();
    }
  }
}

API: Connection ​

语句创建 ​

  • createStatement():静态语句对象创建。创建用于向数据库发送静态 SQL 语句的 Statement 对象,支持指定结果集的滚动类型、并发修改模式与事务提交后的游标保持策略。

    • Statement:(),默认语句对象创建。创建一个默认配置(仅向前滚动 TYPE_FORWARD_ONLY、只读并发 CONCUR_READ_ONLY)的 Statement 实例。
    • Statement:(int resultSetType, int resultSetConcurrency),指定类型与并发度创建。创建生成指定滚动类型(如双向滚动)和并发模式(如可更新结果集)的 Statement 实例。
    • Statement:(int resultSetType, int resultSetConcurrency, int resultSetHoldability),指定完整结果集属性创建。在指定结果集类型与并发模式的基础上,显式指定事务提交后结果集游标是否保持打开(Holdability)。
  • prepareStatement():预编译语句对象创建。创建带 ? 占位符的预编译 SQL 语句对象 PreparedStatement,支持主键自动回填以及自定义结果集属性。

    • PreparedStatement:(String sql),标准预编译创建。使用包含参数占位符的 SQL 语句创建默认结果集属性的 PreparedStatement 实例。
    • PreparedStatement:(String sql, int autoGeneratedKeys),自增主键回填创建。创建预编译语句对象,并通过 Statement.RETURN_GENERATED_KEYS 或 NO_GENERATED_KEYS 控制是否检索数据库自动生成的主键。
    • PreparedStatement:(String sql, int[] columnIndexes),按列索引回填创建。创建预编译语句对象,指定在执行插入后需要通过 getGeneratedKeys() 返回的目标自增列索引数组。
    • PreparedStatement:(String sql, String[] columnNames),按列名回填创建。创建预编译语句对象,指定在执行插入后需要通过 getGeneratedKeys() 返回的目标自增列名称数组。
    • PreparedStatement:(String sql, int resultSetType, int resultSetConcurrency),指定结果集类型与并发创建。创建生成特定滚动类型与并发修改模式的 PreparedStatement 实例。
    • PreparedStatement:(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability),指定完整结果集属性创建。创建具备指定滚动类型、并发模式及游标保持策略的 PreparedStatement 实例。
  • prepareCall():存储过程调用对象创建。创建用于调用数据库存储过程或函数的 CallableStatement 对象。

    • CallableStatement:(String sql),默认存储过程调用创建。使用标准 JDBC 存储过程转义语法(如 {call proc_name(?, ?)})创建默认配置的 CallableStatement 实例。
    • CallableStatement:(String sql, int resultSetType, int resultSetConcurrency),指定结果集类型与并发创建。创建返回特定滚动类型与并发模式结果集的 CallableStatement 实例。
    • CallableStatement:(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability),指定完整结果集属性创建。创建具备指定滚动类型、并发模式及游标保持策略的 CallableStatement 实例。
  • String nativeSQL():(String sql),原生方言语法转换。将包含标准 JDBC 转义语法(如 {fn ...}、{d ...})的 SQL 字符串翻译为底层目标数据库的原生 SQL 方言字符串并返回。

注意事项:

  1. 除非业务明确需要双向滚动或直接通过结果集更新数据,否则应优先使用无参 createStatement() 或单参数 prepareStatement(String sql),避免因开启高级游标特性带来额外的数据库内存与性能开销。
  2. MySQL 驱动默认在客户端模拟预编译,若需开启真正的数据库服务端预编译,需在 JDBC URL 中显式添加 useServerPrepStmts=true 参数。
java
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class ConnectionStatementDemo {

  // 1. 建立数据库连接并演示各类 SQL 语句执行对象的创建
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
      // 2. 将包含 JDBC 转义语法的 SQL 转换为底层数据库原生方言
      String nativeSql = conn.nativeSQL("SELECT {fn NOW()}");
      System.out.println("转换后的原生 SQL: " + nativeSql);

      // 3. 创建支持双向滚动与只读并发模式的静态 Statement 对象
      try (Statement stmt = conn.createStatement(
          ResultSet.TYPE_SCROLL_INSENSITIVE,
          ResultSet.CONCUR_READ_ONLY)) {
        System.out.println("创建 Statement 成功: " + stmt);
      }

      // 4. 创建支持返回自增主键的预编译 PreparedStatement 对象
      String insertSql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
      try (PreparedStatement pstmt = conn.prepareStatement(
          insertSql, Statement.RETURN_GENERATED_KEYS)) {
        System.out.println("创建 PreparedStatement 成功: " + pstmt);
      }

      // 5. 创建用于调用数据库存储过程的 CallableStatement 对象
      try (CallableStatement cstmt = conn.prepareCall("{call sp_query_user(?)}")) {
        System.out.println("创建 CallableStatement 成功: " + cstmt);
      }
    }
  }
}

事务控制 ​

  • final int Connection.TRANSACTION_NONE:不支持事务常量。常量值为 0,标识当前底层数据源不支持事务机制。

  • final int Connection.TRANSACTION_READ_UNCOMMITTED:读未提交隔离常量。常量值为 1,允许读取其他事务尚未提交的脏数据,无法避免脏读、不可重复读与幻读。

  • final int Connection.TRANSACTION_READ_COMMITTED:读已提交隔离常量。常量值为 2,仅允许读取其他事务已提交的数据,可避免脏读,但仍可能出现不可重复读与幻读(Oracle、PostgreSQL 默认级别)。

  • final int Connection.TRANSACTION_REPEATABLE_READ:可重复读隔离常量。常量值为 4,保证同一事务内多次读取同一行记录的结果一致,可避免脏读与不可重复读(MySQL InnoDB 默认级别)。

  • final int Connection.TRANSACTION_SERIALIZABLE:串行化隔离常量。常量值为 8,最高事务隔离级别,强制事务串行执行以彻底规避脏读、不可重复读与幻读,但并发性能最低。

  • void setAutoCommit():(boolean autoCommit),自动提交模式设置。开启或关闭当前连接的事务自动提交模式;设为 false 时将开启手动事务,后续 DML 操作需显式调用 commit() 才会持久化。

  • boolean getAutoCommit():(),自动提交状态获取。检索当前 Connection 对象是否处于事务自动提交模式(新创建的连接默认返回 true)。

  • void commit():(),事务正式提交。使自上次提交或回滚以来在当前事务中执行的所有数据更改永久生效,并释放当前 Connection 持有的数据库锁。

  • rollback():事务数据回滚。撤销当前事务中的全部更改,或局部回滚至指定的事务保存点(Savepoint)。

    • void:(),全量事务回滚。撤销当前事务中的所有未提交更改,并释放当前连接持有的所有数据库锁,只能在 autoCommit 为 false 时调用。
    • void:(Savepoint savepoint),保存点局部回滚。撤销在设置给定 Savepoint 保存点之后执行的所有数据更改,保留该保存点之前的事务操作。
  • void setTransactionIsolation():(int level),事务隔离级别设置。将当前连接的事务隔离级别修改为指定的 Connection.TRANSACTION_* 常量值。

  • int getTransactionIsolation():(),事务隔离级别获取。获取当前连接会话正在生效的事务隔离级别常量值。

  • setSavepoint():事务保存点创建。在当前手动事务内部设置一个回滚标记点,以便后续通过 rollback(Savepoint) 实现细粒度的局部事务回滚。

    • Savepoint:(),匿名保存点创建。在当前事务中创建一个未命名的保存点并返回代表该节点的 Savepoint 实例。
    • Savepoint:(String name),命名保存点创建。在当前事务中创建一个具有指定名称的保存点并返回对应的 Savepoint 实例。
  • void releaseSavepoint():(Savepoint savepoint),事务保存点释放。从当前事务中移除指定的 Savepoint 保存点对象;释放后若再次针对该保存点执行回滚将抛出 SQLException。

注意事项:

  1. 当连接处于自动提交模式(getAutoCommit() == true)时,直接调用 commit()、rollback() 或 setSavepoint() 均会抛出 SQLException。
  2. 若在未完成手动事务期间调用 setAutoCommit(true) 切换回自动提交模式,JDBC 规范要求底层驱动自动将该连接上挂起的事务立即提交。
java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.sql.Savepoint;

public class ConnectionTransactionDemo {

  // 1. 演示事务隔离级别配置、保存点回滚与手动提交
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
      // 2. 设置事务隔离级别为读已提交并关闭自动提交模式
      conn.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);
      conn.setAutoCommit(false);
      System.out.println("自动提交状态: " + conn.getAutoCommit() + ", 隔离级别: " + conn.getTransactionIsolation());

      String sql = "UPDATE t_user SET balance = balance - ? WHERE username = ?";
      try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
        pstmt.setDouble(1, 100.00);
        pstmt.setString(2, "Alice");
        pstmt.executeUpdate();

        // 3. 在第一阶段更新完成后创建命名事务保存点
        Savepoint sp = conn.setSavepoint("STAGE_ONE");

        pstmt.setDouble(1, 200.00);
        pstmt.setString(2, "Bob");
        pstmt.executeUpdate();

        // 4. 局部回滚至保存点并释放该保存点资源
        conn.rollback(sp);
        conn.releaseSavepoint(sp);

        // 5. 正式提交保存点之前的事务更改
        conn.commit();
      } catch (SQLException e) {
        // 6. 发生异常时全量回滚当前事务
        conn.rollback();
        throw e;
      }
    }
  }
}

会话配置 ​

  • DatabaseMetaData getMetaData():(),数据库元数据获取。返回封装了底层数据库产品信息、驱动版本、表结构定义及功能支持情况的 DatabaseMetaData 对象。

  • void setReadOnly():(boolean readOnly),只读会话模式设置。将当前连接设置为只读模式,作为驱动与数据库启用只读查询优化或路由至只读从库的提示。

  • boolean isReadOnly():(),只读会话状态查询。判断当前 Connection 对象是否处于只读模式。

  • void setCatalog():(String catalog),数据库目录设置。设置当前连接操作的子数据库(Catalog)名称;在 MySQL 中对应切换具体的 Database。

  • String getCatalog():(),数据库目录获取。获取当前连接正在生效的 Catalog 名称。

  • void setSchema():(String schema),数据库模式设置。设置当前连接默认访问的命名空间模式(Schema)名称。

  • String getSchema():(),数据库模式获取。获取当前连接正在生效的 Schema 名称。

  • void setHoldability():(int holdability),游标保持策略设置。修改当前连接创建的 ResultSet 在调用 commit() 提交事务后的默认游标保持策略(HOLD_CURSORS_OVER_COMMIT 或 CLOSE_CURSORS_AT_COMMIT)。

  • int getHoldability():(),游标保持策略获取。获取当前连接默认的 ResultSet 游标保持性常量。

  • setClientInfo():客户端元数据写入。向连接会话写入客户端上下文信息(如应用名称、主机名、调用方用户),便于数据库服务端在会话监控视图或审计日志中追踪连接来源。

    • void:(String name, String value),单属性元数据设置。按指定的属性名与属性值设置单条客户端追踪信息,失败时抛出 SQLClientInfoException。
    • void:(Properties properties),集合元数据批量替换。使用给定的 Properties 集合完整替换当前连接的全部客户端属性,未包含在集合中的已有属性将被清空。
  • getClientInfo():客户端元数据读取。读取当前连接已配置的客户端追踪属性。

    • String:(String name),按名称读取客户端属性。返回指定客户端信息属性名称对应的字符串值。
    • Properties:(),读取全部客户端属性。返回包含当前连接所有受支持客户端信息键值对的 Properties 集合。
  • void setTypeMap():(Map<String, Class<?>> map),自定义类型映射设置。安装自定义 SQL 结构化类型(UDT)名称与 Java SQLData 实现类之间的映射字典表。

  • Map<String, Class<?>> getTypeMap():(),自定义类型映射获取。获取当前连接绑定的 SQL 自定义类型映射表 Map。

注意事项:

  1. setReadOnly(boolean) 不能在事务执行中途调用,必须在事务开启前切换,否则会抛出 SQLException。
  2. 在 MySQL 中,Catalog 等价于数据库名(Database),而 getSchema() 默认返回 null;在 PostgreSQL 或 Oracle 中,则主要通过 Schema 区分同一实例下的不同逻辑命名空间。
java
import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;

public class ConnectionSessionDemo {

  // 1. 演示连接会话上下文配置与数据库元数据读取
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
      // 2. 获取底层数据库的全局元数据对象
      DatabaseMetaData metaData = conn.getMetaData();
      System.out.println("数据库产品名: " + metaData.getDatabaseProductName());

      // 3. 查看并配置当前连接会话的 Catalog 与只读模式
      conn.setCatalog("test_db");
      conn.setReadOnly(true);
      System.out.println("当前 Catalog: " + conn.getCatalog() + ", 是否只读: " + conn.isReadOnly());

      // 4. 配置结果集可保持性并写入客户端应用追踪信息
      conn.setHoldability(ResultSet.CLOSE_CURSORS_AT_COMMIT);
      conn.setClientInfo("ApplicationName", "OrderService");
      System.out.println("客户端应用标识: " + conn.getClientInfo("ApplicationName"));
    }
  }
}

类型工厂 ​

  • Clob createClob():(),字符大对象创建。创建并返回一个初始为空的 Clob(Character Large Object)实例,用于向数据库写入超长文本数据。

  • Blob createBlob():(),二进制大对象创建。创建并返回一个初始为空的 Blob(Binary Large Object)实例,用于向数据库写入二进制字节数组或流数据。

  • NClob createNClob():(),国家字符集大对象创建。创建并返回一个初始为空的 NClob 实例,用于存储基于国家字符集(如 UTF-16/Unicode)的大文本数据。

  • SQLXML createSQLXML():(),XML 类型对象创建。创建并返回一个初始为空的 SQLXML 实例,用于读写数据库原生的 XML 字段类型。

  • Array createArrayOf():(String typeName, Object[] elements),SQL 数组对象创建。将给定的 Java 对象数组封装为对应数据库元素类型名称 typeName 的 java.sql.Array 实例。

  • Struct createStruct():(String typeName, Object[] attributes),SQL 结构体对象创建。使用给定的属性数组创建映射数据库指定自定义复合类型 typeName 的 Struct 实例。

注意事项:

  1. 通过工厂方法创建的 Clob、Blob、NClob 与 SQLXML 对象在内存中持有数据缓冲区,使用完毕后应主动调用其 free() 方法释放底层资源。
  2. MySQL 数据库原生不支持 SQL 标准数组与複合结构体类型,因此在 MySQL 驱动上调用 createArrayOf() 或 createStruct() 会直接抛出 SQLFeatureNotSupportedException。
java
import java.sql.Blob;
import java.sql.Clob;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.NClob;
import java.sql.SQLException;
import java.sql.SQLXML;

public class ConnectionFactoryDemo {

  // 1. 演示使用 Connection 工厂方法创建 LOB 与 XML 类型对象
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
      // 2. 创建并填充字符大对象 Clob 与宽字符大对象 NClob
      Clob clob = conn.createClob();
      clob.setString(1, "长文本内容示例");
      NClob nClob = conn.createNClob();
      nClob.setString(1, "多语言宽字符内容");

      // 3. 创建并填充二进制大对象 Blob 与 SQLXML 实例
      Blob blob = conn.createBlob();
      blob.setBytes(1, new byte[]{1, 2, 3, 4});
      SQLXML sqlxml = conn.createSQLXML();
      sqlxml.setString("<config><env>prod</env></config>");

      // 4. 使用完毕后主动释放大对象底层内存资源
      System.out.println("Clob 长度: " + clob.length() + ", Blob 长度: " + blob.length());
      clob.free();
      nClob.free();
      blob.free();
      sqlxml.free();
    }
  }
}

状态管理 ​

  • void close():(),物理连接关闭。立即释放当前 Connection 对象的数据库会话与底层 JDBC 资源(若是由连接池代理的 Connection,则将其归还至连接池中复用)。

  • boolean isClosed():(),连接关闭状态判断。检查当前 Connection 对象是否已被调用 close() 关闭;该判断仅检查本地状态标记,不能用于探测网络异常断开。

  • boolean isValid():(int timeout),连接存活探测。向数据库发送轻量级探测包(如 MySQL PING 命令)以验证连接是否真实有效;参数 timeout 指定等待验证响应的最大秒数(0 表示不限制)。

  • void abort():(Executor executor),连接强制终止。使用给定的异步线程池 Executor 强制终止并销毁出现挂起或死锁的物理连接,即使当前连接正在执行 SQL 操作也会立即标记为关闭。

  • void setNetworkTimeout():(Executor executor, int milliseconds),网络读写超时设置。设置当前连接等待数据库网络 I/O 响应的最大毫秒数;超时触发后将由传入的 Executor 异步关闭该连接。

  • int getNetworkTimeout():(),网络读写超时获取。返回当前连接配置的底层 Socket 等待响应的最大毫秒数。

  • SQLWarning getWarnings():(),连接告警链获取。返回当前连接会话上报告的第一个 SQLWarning 告警对象;后续告警可通过 SQLWarning.getNextWarning() 链式遍历。

  • void clearWarnings():(),连接告警清空。清除当前 Connection 对象上累积的所有 SQLWarning 告警记录。

  • void beginRequest():(),请求边界开启。自 JDK 9 引入的 default 默认方法,向驱动提示一个独立业务请求工作单元的开始,供连接池或驱动执行会话级初始化与状态绑定。

  • void endRequest():(),请求边界结束。自 JDK 9 引入的 default 默认方法,向驱动提示当前业务请求工作单元已结束,便于驱动回收请求级临时资源。

  • setShardingKeyIfValid():分片键有效性校验设置。自 JDK 9 引入的 default 默认方法,在给定的超时秒数内验证分片键是否属于当前物理连接所指向的数据分片,验证通过则绑定该分片键并返回 true。

    • boolean:(ShardingKey shardingKey, int timeout),单层分片键校验绑定。在 timeout 秒内验证并绑定主分片键 shardingKey。
    • boolean:(ShardingKey shardingKey, ShardingKey superShardingKey, int timeout),双层分片键校验绑定。在 timeout 秒内同时验证并绑定子分片键 shardingKey 与超分片键 superShardingKey。
  • setShardingKey():分片键直接设置。自 JDK 9 引入的 default 默认方法,将指定的分片键设置为当前连接会话的路由上下文。

    • void:(ShardingKey shardingKey),单层分片键绑定。为当前连接直接设置主分片键 shardingKey。
    • void:(ShardingKey shardingKey, ShardingKey superShardingKey),双层分片键绑定。为当前连接同时设置子分片键 shardingKey 与超分片键 superShardingKey。

注意事项:

  1. 永远不要使用 !conn.isClosed() 来校验连接池中的连接是否可用,因为当数据库服务端主动断开空闲连接或网络闪断时,客户端未调用过 close(),isClosed() 依然返回 false;必须调用 conn.isValid(timeout) 发起实际网络探测。
  2. 在已经关闭的 Connection 上重复调用 close() 方法是幂等安全的(空操作),不会抛出异常。
java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.SQLWarning;
import java.util.concurrent.Executors;

public class ConnectionLifecycleDemo {

  // 1. 演示数据库连接有效性探测、超时控制与告警清理
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    Connection conn = DriverManager.getConnection(url, "root", "123456");

    // 2. 设置底层 Socket 网络超时时间并校验连接存活状态
    conn.setNetworkTimeout(Executors.newSingleThreadExecutor(), 5000);
    boolean valid = conn.isValid(3);
    System.out.println("网络超时毫秒数: " + conn.getNetworkTimeout() + ", 连接是否有效: " + valid);

    // 3. 检查并清空当前连接会话累积的 SQLWarning 告警链
    SQLWarning warning = conn.getWarnings();
    if (warning == null) {
      conn.clearWarnings();
    }

    // 4. 显式关闭物理连接并验证关闭状态
    conn.close();
    System.out.println("连接是否已关闭: " + conn.isClosed());
  }
}

继承: Wrapper ​

isWrapperFor, unwrap

批处理 ​

当需要向数据库一次性插入或更新数千乃至数万条记录时,如果在循环体内逐条调用 executeUpdate 发送 SQL 语句,每一条记录都会经历一次独立的“客户端发送请求 → 服务端解析执行 → 独立事务刷盘 → 返回响应报文”完整周期,高频的网络往返延迟(RTT)与磁盘 I/O 会使执行耗时呈线性暴增。

JDBC 批处理(Batch Processing)机制通过在客户端 JVM 内存中开辟批处理缓冲区,将多条 SQL 语句或多组预编译参数预先累积打包,到达设定阈值后再通过单次网络请求集中提交给数据库服务端处理,从而大幅削减网络通信开销与事务提交次数。

批处理缓冲与执行流程 ​

JDBC 在父接口 Statement 与子接口 PreparedStatement 中均提供了批处理支持。一次完整的批处理生命周期由三个核心阶段构成:

  1. 追加至本地批处理队列:在循环中构造完一条静态 SQL 或绑定完一组 ? 占位符参数后,将其追加到语句对象内部的本地批处理集合中。此阶段仅发生 JVM 内存操作,不会产生任何网络 I/O。

  2. 批量打包发送执行:当本地集合中的任务累积到指定批次阈值(如 500 或 1000 条)时,触发批量发送指令。驱动将缓冲区中的所有任务打包发送给数据库服务端执行,并按添加顺序返回每条语句受影响行数组成的 int[] 数组。

  3. 清空本地批处理缓存:每批次发送执行完毕后,必须立即清空语句对象内部的本地批处理列表,释放已处理的参数对象引用,防止下一批次数据继续叠加或引发 JVM 堆内存溢出(OutOfMemoryError)。

image-20261104122131854

异构静态语句批处理 ​

通过基础接口 Statement 执行批处理时,每次向队列中追加的是一条完整的静态 SQL 字符串。

由于不需要预先固定 SQL 模板,Statement 批处理的优势在于支持将多条语法结构不同、操作目标表不同的异构 DML 语句(如同时包含 INSERT、UPDATE 和 DELETE)混合放入同一个批次中发送;缺点是无法预编译复用执行计划,且存在 SQL 注入风险:

java
import com.hspedu.jdbc.utils.JDBCUtils;
import java.sql.Connection;
import java.sql.Statement;

public class StatementBatchDemo {

  public static void main(String[] args) throws Exception {
    Connection conn = JDBCUtils.getConnection();
    Statement stmt = conn.createStatement();

    // 1. 将多条结构不同的静态 DML 语句依次追加到 Statement 批处理队列
    stmt.addBatch("INSERT INTO t_user (username, balance) VALUES ('Frank', 1000.00)");
    stmt.addBatch("UPDATE t_user SET balance = balance + 200.00 WHERE username = 'Alice'");
    stmt.addBatch("DELETE FROM t_user WHERE username = 'Bob'");

    // 2. 一次性批量发送所有语句,返回每条语句受影响行数组成的 int 数组
    int[] affectedCounts = stmt.executeBatch();
    System.out.println("批量执行语句数: " + affectedCounts.length);

    // 3. 清空批处理队列并释放连接资源
    stmt.clearBatch();
    JDBCUtils.close(null, stmt, conn);
  }
}

同构预编译参数批处理 ​

通过 PreparedStatement 执行批处理时,SQL 语法模板在创建语句对象时已经预先固定,每次向批处理队列中追加的仅仅是一组绑定好的占位符参数快照。

这种模式专用于向同一张表批量写入或更新海量同构数据,不仅消除了 SQL 注入隐患,还能配合数据库驱动实现底层的语法合并重写优化,是生产环境批量数据落盘的标准方案。

驱动层源码与重写机制 ​

在使用 MySQL 驱动(mysql-connector-j)编写 PreparedStatement 批处理代码时,若仅调用批处理 API 而未调整 JDBC URL 连接参数,往往会发现执行耗时与传统的逐条循环插入几乎没有差别。理解这一现象需要深入 ClientPreparedStatement 的底层源码实现。

image-20261104122223601

batchedArgs 懒加载缓冲 ​

在 MySQL 驱动的实现类 ClientPreparedStatement(继承自 StatementImpl)中,内部声明了一个 List<Object> batchedArgs 成员变量,专门用于存储批处理参数:

  1. 初始空引用:当调用 conn.prepareStatement(sql) 创建实例时,batchedArgs 默认为 null,不会提前占用集合内存。

  2. 首次追加初始化:当第一次调用 addBatch() 时,源码内部会检测 batchedArgs == null,此时才懒加载实例化一个 ArrayList<Object> 容器,并将当前行绑定的参数快照克隆封装后存入该列表中。

  3. 清理引用:当调用 clearBatch() 时,底层直接调用 this.batchedArgs.clear() 将 ArrayList 中的所有参数快照引用清空:

java
public class ClientPreparedStatement extends StatementImpl implements PreparedStatement {

  protected List<Object> batchedArgs;

  // 1. 将当前已绑定的占位符参数快照封装追加到本地批处理集合
  @Override
  public void addBatch() throws SQLException {
    // 2. 首次调用时懒加载初始化 ArrayList 容器
    if (this.batchedArgs == null) {
      this.batchedArgs = new ArrayList<Object>();
    }
    // 3. 将当前参数绑定对象克隆后存入 batchedArgs 列表
    this.batchedArgs.add(this.query.getQueryBindings().clone());
  }

  @Override
  protected int[] executeBatchInternal() throws SQLException {
    if (this.batchedArgs == null || this.batchedArgs.size() == 0) {
      return new int[0];
    }
    // 4. 若开启 rewriteBatchedStatements 且为 INSERT 语句,合并重写为多值插入单次发送
    if (this.rewriteBatchedStatements.getValue() && isInsertStatement()) {
      return executeBatchedInserts(batchTimeout);
    }
    // 5. 默认未开启重写时,退化为遍历 batchedArgs 列表逐条串行发送给服务端
    return executeBatchSerially(batchTimeout);
  }

  // 6. 清空本地批处理参数集合,释放已累积的参数对象引用
  @Override
  public void clearBatch() throws SQLException {
    if (this.batchedArgs != null) {
      this.batchedArgs.clear();
    }
  }
}

串行发送与多值重写分支 ​

如上述 executeBatchInternal 源码所示,MySQL 驱动在触发批量发送时存在两条性能悬殊的执行分支,完全取决于 JDBC URL 中是否配置了 rewriteBatchedStatements=true 参数(默认值为 false):

  1. 默认串行发送分支(executeBatchSerially):当未配置 rewriteBatchedStatements=true 时,驱动进入 executeBatchSerially 方法。该方法内部仅通过一个 for 循环遍历 batchedArgs 集合,将每一组参数还原为一条独立的 INSERT 语句,依然逐条通过 TCP Socket 发送给 MySQL 服务端并逐次等待响应。这意味着 1000 条记录仍然会产生 1000 次网络往返,批处理形同虚设。

  2. 多值语法重写分支(executeBatchedInserts):当在 JDBC URL 中显式添加 rewriteBatchedStatements=true 后,驱动会拦截标准 INSERT 语句并进入 executeBatchedInserts 方法。驱动在客户端内存中将原本 1000 条独立的单值插入语句,自动拼接重写为 1 条包含 1000 组括号值的多值插入语句(Multi-Values Insert),通过单次网络数据包一次性提交给 MySQL 服务端解析执行,将网络往返开销直接压缩为原来的千分之一:

sql
-- 1. rewriteBatchedStatements=false 时:驱动遍历列表逐条发送独立的单值 INSERT 语句
INSERT INTO t_user (username, balance)
    VALUES ('User_1', 500.00);
INSERT INTO t_user (username, balance)
    VALUES ('User_2', 500.00);

-- 2. rewriteBatchedStatements=true 时:驱动自动将批处理参数合并重写为单条多值 INSERT
INSERT INTO t_user (username, balance)
    VALUES ('User_1', 500.00),
           ('User_2', 500.00),
           ('User_3', 500.00);

对于非 INSERT 类的批量 UPDATE 或 DELETE 语句,开启 rewriteBatchedStatements=true 后,驱动则会调用 executePreparedBatchAsMultiStatement,将多条更新语句使用分号(;)拼接在同一个网络报文中一次性发送给服务端,同样能够省去多次网络往返耗时。

高性能批处理实践 ​

在生产环境中实现最高吞吐量的批量写入,需要将开启重写参数、手动事务控制与分段批次清理三项机制结合使用。

基准耗时对比 ​

首先确保在 mysql.properties(或 druid.properties)的数据库 URL 中追加了批处理重写参数:

properties
# 在连接 URL 中开启 rewriteBatchedStatements=true 激活驱动层多值 SQL 重写
url=jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&rewriteBatchedStatements=true

下面通过向 t_user 表连续写入 5000 条记录,对比“传统逐条执行”与“开启重写 + 手动事务 + 每 1000 条分批刷写”的真实性能表现:

java
package com.hspedu.jdbc.batch;

import com.hspedu.jdbc.utils.JDBCUtils;
import java.sql.Connection;
import java.sql.PreparedStatement;

public class BatchPerformanceDemo {

  // 1. 传统逐条执行模式:5000 次网络往返与 5000 次独立事务自动提交
  public static void noBatch() throws Exception {
    Connection conn = JDBCUtils.getConnection();
    String sql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
    PreparedStatement pstmt = conn.prepareStatement(sql);

    long start = System.currentTimeMillis();
    for (int i = 1; i <= 5000; i++) {
      // 2. 每次循环直接调用 executeUpdate 向数据库发起单条同步网络请求
      pstmt.setString(1, "User_" + i);
      pstmt.setDouble(2, 100.00);
      pstmt.executeUpdate();
    }
    long end = System.currentTimeMillis();
    System.out.println("传统逐条插入 5000 条耗时(ms): " + (end - start));

    JDBCUtils.close(null, pstmt, conn);
  }

  // 3. 批处理优化模式(需在 URL 配置 rewriteBatchedStatements=true)
  public static void batchWithTransaction() throws Exception {
    Connection conn = JDBCUtils.getConnection();
    String sql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
    // 4. 开启手动事务,避免每批次执行后立即触发磁盘刷盘
    conn.setAutoCommit(false);
    PreparedStatement pstmt = conn.prepareStatement(sql);

    long start = System.currentTimeMillis();
    for (int i = 1; i <= 5000; i++) {
      pstmt.setString(1, "User_" + i);
      pstmt.setDouble(2, 100.00);
      // 5. 将绑定好的参数加入本地 batchedArgs 列表,不产生网络 I/O
      pstmt.addBatch();

      // 6. 每满 1000 条集中发送一次重写后的多值 INSERT,并清空本地列表防 OOM
      if (i % 1000 == 0) {
        pstmt.executeBatch();
        pstmt.clearBatch();
      }
    }

    // 7. 处理剩余未满 1000 条的尾批数据并统一提交事务
    pstmt.executeBatch();
    pstmt.clearBatch();
    conn.commit();
    long end = System.currentTimeMillis();
    System.out.println("批处理插入 5000 条耗时(ms): " + (end - start));

    conn.setAutoCommit(true);
    JDBCUtils.close(null, pstmt, conn);
  }
}

在本地 MySQL 测试环境下,传统逐条插入 5000 条记录通常耗时 6000 至 15000 毫秒;而开启 rewriteBatchedStatements=true 并配合手动事务分批执行后,5000 条记录的写入耗时可骤降至 50 至 120 毫秒,性能提升达百倍以上。

批处理边界与注意事项 ​

在编写 PreparedStatement 批处理逻辑时,需注意以下三个底层约束:

  1. SQL 语法规范约束:MySQL 驱动在解析 INSERT 语句以判断是否可进行多值合并重写时,对 SQL 模板格式有严格要求——必须使用标准的 VALUES 关键字(早期驱动版本若简写为 VALUE 会导致重写识别失败),且语句末尾严禁书写分号(;),否则拼接多值括号时会触发 SQL 语法错误。

  2. 单次网络报文大小上限:切勿将数十万条记录全部 addBatch 后只调用一次 executeBatch。因为重写后的巨型多值 INSERT 语句一旦超过 MySQL 服务端配置的 max_allowed_packet 报文体积上限(默认通常为 4MB 至 64MB),服务端会直接拒绝接收并抛出 PacketTooBigException 异常。工程上将分批大小(Batch Size)控制在 500 至 2000 条之间最佳。

  3. 尾批遗漏陷阱:当待写入的总记录数不能被批次大小(如 1000)整除时(例如共有 5300 条数据),循环体内的 if (i % 1000 == 0) 只会触发前 5000 条数据的发送,最后 300 条数据仍滞留在 batchedArgs 列表中。因此必须在 for 循环结束之后,固定追加一次兜底的批量执行与清空调用。

API: Statement ​

语句执行 ​

  • final int Statement.RETURN_GENERATED_KEYS:返回自增主键常量。常量值为 1,指示驱动在执行 INSERT 语句后检索数据库自动生成的主键值,以供后续调用 getGeneratedKeys() 获取。

  • final int Statement.NO_GENERATED_KEYS:忽略自增主键常量。常量值为 2,指示驱动在执行更新语句后无需采集数据库自动生成的主键信息。

  • ResultSet executeQuery():(String sql),静态查询语句执行。执行返回单个结果集的静态 SQL 查询语句(如 SELECT),并返回封装了查询数据的 ResultSet 对象(永远不会返回 null)。

  • executeUpdate():静态更新语句执行。执行 INSERT、UPDATE、DELETE 等 DML 数据操作语句(返回受影响的行数),或执行 CREATE、ALTER 等无返回值的 DDL 语句(返回 0)。

    • int:(String sql),标准更新执行。执行给定的静态 DML 或 DDL 语句并返回受影响的行数。
    • int:(String sql, int autoGeneratedKeys),带主键回填配置更新。执行给定的静态更新语句,并通过 Statement.RETURN_GENERATED_KEYS 或 NO_GENERATED_KEYS 设置是否检索数据库自动生成的主键。
    • int:(String sql, int[] columnIndexes),按列索引回填更新。执行更新语句,并指定需要采集返回的自增主键所在的目标列索引数组(从 1 开始)。
    • int:(String sql, String[] columnNames),按列名回填更新。执行更新语句,并指定需要采集返回的自增主键所在的目标列名称数组。
  • executeLargeUpdate():超大行数更新执行。自 JDK 8 引入的 default 默认方法,适用于单次 DML 更新受影响行数超过 Integer.MAX_VALUE 的海量数据场景,返回 long 类型的更新计数。

    • long:(String sql),标准大行数更新。执行给定的静态 DML 或 DDL 语句并返回 long 类型的受影响行数。
    • long:(String sql, int autoGeneratedKeys),带主键标志大行数更新。执行大行数更新语句并指定是否检索自动生成的主键。
    • long:(String sql, int[] columnIndexes),按列索引回填大行数更新。执行大行数更新语句并指定需要返回自增值的目标列索引数组。
    • long:(String sql, String[] columnNames),按列名回填大行数更新。执行大行数更新语句并指定需要返回自增值的目标列名称数组。
  • execute():通用动态语句执行。执行任意类型的静态 SQL 语句(尤其适用于事先未知 SQL 类型或会返回多个结果集/更新计数的动态场景);若第一个结果为 ResultSet 则返回 true,若为更新计数或无结果则返回 false。

    • boolean:(String sql),标准通用执行。执行任意静态 SQL 语句并返回首个结果是否为 ResultSet 的布尔标志。
    • boolean:(String sql, int autoGeneratedKeys),带主键标志通用执行。执行任意静态 SQL 语句并设置是否捕获自动生成的主键。
    • boolean:(String sql, int[] columnIndexes),按列索引回填通用执行。执行任意静态 SQL 语句并指定需返回自增值的列索引数组。
    • boolean:(String sql, String[] columnNames),按列名回填通用执行。执行任意静态 SQL 语句并指定需返回自增值的列名称数组。
  • ResultSet getGeneratedKeys():(),自增主键结果集获取。获取执行此 Statement 对象后由数据库自动生成的所有主键值组成的 ResultSet 对象;若未生成任何键则返回空的 ResultSet。

注意事项:

  1. 同一个 Statement 实例在同一时刻默认只能打开一个 ResultSet 对象;若直接调用该 Statement 执行下一条 SQL,前一个尚未关闭的 ResultSet 会被底层驱动隐式关闭。
  2. Statement 直接拼接 SQL 字符串极易引发 SQL 注入风险,且无法复用预编译执行计划;凡是涉及外部传入参数的 SQL,均应改用子接口 PreparedStatement。
java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class StatementExecuteDemo {

  // 1. 建立数据库连接并创建静态 Statement 执行对象
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456");
       Statement stmt = conn.createStatement()) {

      // 2. 执行 DML 插入语句并指定返回数据库自动生成的主键
      String insertSql = "INSERT INTO t_user (username, balance) VALUES ('Charlie', 800.00)";
      int rows = stmt.executeUpdate(insertSql, Statement.RETURN_GENERATED_KEYS);
      System.out.println("插入受影响行数: " + rows);

      // 3. 获取并遍历刚刚生成的自增主键值
      try (ResultSet keys = stmt.getGeneratedKeys()) {
        if (keys.next()) {
          System.out.println("生成的自增主键 ID: " + keys.getLong(1));
        }
      }

      // 4. 执行 DQL 查询语句并读取结果集
      String querySql = "SELECT id, username, balance FROM t_user WHERE username = 'Charlie'";
      try (ResultSet rs = stmt.executeQuery(querySql)) {
        while (rs.next()) {
          System.out.println("查询结果: " + rs.getString("username") + " -> " + rs.getDouble("balance"));
        }
      }

      // 5. 使用通用 execute 方法执行任意 SQL 并判断返回结果类型
      boolean isResultSet = stmt.execute("DELETE FROM t_user WHERE username = 'Charlie'");
      System.out.println("是否为查询结果集: " + isResultSet);
    }
  }
}

批量处理 ​

  • final int Statement.SUCCESS_NO_INFO:未知行数成功常量。常量值为 -2,作为 executeBatch() 返回数组中的元素值,表示该条批处理指令已执行成功,但底层驱动无法获知其具体受影响的行数。

  • final int Statement.EXECUTE_FAILED:批处理执行失败常量。常量值为 -3,作为 executeBatch() 或 BatchUpdateException.getUpdateCounts() 数组中的元素值,表示该条批处理指令执行失败(仅在驱动遇到错误后仍继续执行后续批处理指令时出现)。

  • void addBatch():(String sql),批处理指令追加。将给定的静态 DML 或 DDL 语句添加到当前 Statement 对象的本地批处理命令列表中(严禁添加返回结果集的 SELECT 语句)。

  • void clearBatch():(),批处理队列清空。清空当前 Statement 对象本地批处理命令列表中已缓存的所有 SQL 语句。

  • int[] executeBatch():(),批量指令提交执行。将当前批处理队列中的所有 SQL 命令一次性提交给数据库执行;若全部执行成功,则按添加顺序返回每条命令对应的更新计数数组。

  • long[] executeLargeBatch():(),大行数批量提交执行。自 JDK 8 引入的 default 默认方法,当批处理中单条语句受影响行数可能超过 Integer.MAX_VALUE 时调用,返回 long[] 类型的更新计数数组。

注意事项:

  1. 执行批量插入或更新时,建议先调用 conn.setAutoCommit(false) 关闭自动提交,待 executeBatch() 完成后再统一调用 conn.commit(),从而避免每条语句单独开启和提交事务带来的磁盘刷盘开销。
  2. 若批处理队列中某一条语句执行失败,驱动会抛出 BatchUpdateException(SQLException 的子类),可通过调用该异常对象的 getUpdateCounts() 方法排查异常发生前各语句的执行状态。
java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Arrays;

public class StatementBatchDemo {

  // 1. 建立数据库连接并关闭自动提交以提升批处理事务性能
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&rewriteBatchedStatements=true";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456");
       Statement stmt = conn.createStatement()) {
      conn.setAutoCommit(false);

      // 2. 向 Statement 批处理缓存队列中添加多条静态 SQL 语句
      stmt.addBatch("INSERT INTO t_user (username, balance) VALUES ('Dave', 300.00)");
      stmt.addBatch("INSERT INTO t_user (username, balance) VALUES ('Eve', 450.00)");
      stmt.addBatch("UPDATE t_user SET balance = balance + 50.00 WHERE username = 'Dave'");

      // 3. 一次性将批处理队列发送至数据库执行并获取各语句更新计数数组
      int[] updateCounts = stmt.executeBatch();
      conn.commit();
      System.out.println("批处理各语句受影响行数: " + Arrays.toString(updateCounts));

      // 4. 清空当前 Statement 中残留的批处理指令列表
      stmt.clearBatch();
    }
  }
}

多结果集遍历 ​

  • final int Statement.CLOSE_CURRENT_RESULT:关闭当前结果集常量。常量值为 1,传递给 getMoreResults(int) 时,指示驱动在移动到下一个结果时自动关闭当前打开的 ResultSet 对象。

  • final int Statement.KEEP_CURRENT_RESULT:保留当前结果集常量。常量值为 2,传递给 getMoreResults(int) 时,指示驱动在移动到下一个结果时不关闭当前打开的 ResultSet 对象。

  • final int Statement.CLOSE_ALL_RESULTS:关闭历史结果集常量。常量值为 3,传递给 getMoreResults(int) 时,指示驱动在移动到下一个结果时一次性关闭此前通过 KEEP_CURRENT_RESULT 保留的所有已打开 ResultSet 对象。

  • ResultSet getResultSet():(),当前结果集提取。以 ResultSet 对象的形式获取 execute() 执行后的当前结果;若当前结果是一个更新计数或已无更多结果,则返回 null(每个结果只能调用一次该方法)。

  • int getUpdateCount():(),当前更新计数提取。以 int 行数的形式获取 execute() 执行后的当前结果;若当前结果是一个 ResultSet 对象或已无更多结果,则返回 -1(每个结果只能调用一次该方法)。

  • long getLargeUpdateCount():(),当前大行数计数提取。自 JDK 8 引入的 default 默认方法,以 long 类型返回当前结果的更新行数;若当前结果为 ResultSet 或已无更多结果则返回 -1L。

  • getMoreResults():下一结果游标推进。将此 Statement 对象移动到下一个执行结果;若下一个结果是 ResultSet 对象则返回 true,若为更新计数或已无更多结果则返回 false。

    • boolean:(),默认关闭推进。移动到下一个执行结果,并隐式关闭通过 getResultSet() 获取的当前 ResultSet(等价于传入 CLOSE_CURRENT_RESULT)。
    • boolean:(int current),指定保留策略推进。移动到下一个执行结果,并根据传入的 CLOSE_CURRENT_RESULT、KEEP_CURRENT_RESULT 或 CLOSE_ALL_RESULTS 常量处理此前已打开的 ResultSet。

注意事项:

  1. 判断多结果集是否全部遍历完毕的标准终止条件为:((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))。
  2. MySQL 驱动默认禁止在一次 execute() 调用中用分号分隔执行多条 SQL 语句;若需使用多语句混合执行与多结果集遍历,必须在 JDBC URL 中显式开启 allowMultiQueries=true。
java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class StatementMultiResultDemo {

  // 1. 开启 allowMultiQueries 参数以支持单次执行多条混合 SQL 语句
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&allowMultiQueries=true";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456");
       Statement stmt = conn.createStatement()) {

      // 2. 一次性发送包含更新与查询的复合 SQL 语句
      String multiSql = "UPDATE t_user SET balance = balance + 10.00 WHERE id = 1; "
          + "SELECT id, username, balance FROM t_user WHERE id = 1;";
      boolean hasResultSet = stmt.execute(multiSql);

      // 3. 循环遍历所有返回结果(当不再有结果集且更新计数为 -1 时终止)
      while (true) {
        if (hasResultSet) {
          try (ResultSet rs = stmt.getResultSet()) {
            while (rs.next()) {
              System.out.println("查询结果集记录: " + rs.getString("username"));
            }
          }
        } else {
          int updateCount = stmt.getUpdateCount();
          if (updateCount == -1) {
            break;
          }
          System.out.println("DML 更新受影响行数: " + updateCount);
        }

        // 4. 移动至下一个执行结果并自动关闭当前已处理的 ResultSet
        hasResultSet = stmt.getMoreResults(Statement.CLOSE_CURRENT_RESULT);
      }
    }
  }
}

执行参数配置 ​

  • void setQueryTimeout():(int seconds),语句执行超时设置。设置驱动等待單条 SQL 语句执行完成的最大秒数(设为 0 表示不限制);若超出该时间仍未完成,将抛出 SQLTimeoutException。

  • int getQueryTimeout():(),语句执行超时获取。返回当前配置的等待 SQL 执行完成的最大秒数。

  • void setMaxRows():(int max),结果集最大行数设置。设置此 Statement 生成的任何 ResultSet 对象最多可包含的记录行数上限(设为 0 表示不限制),超出上限的行将被静默丢弃。

  • int getMaxRows():(),结果集最大行数获取。获取当前 Statement 生成的结果集所允许的最大记录行数。

  • void setLargeMaxRows():(long max),超大结果集行数上限设置。自 JDK 8 引入的 default 默认方法,设置结果集允许包含的最大行数上限(支持超过 Integer.MAX_VALUE 的 long 值)。

  • long getLargeMaxRows():(),超大结果集行数上限获取。自 JDK 8 引入的 default 默认方法,返回当前配置的结果集最大行数上限(long 类型)。

  • void setMaxFieldSize():(int max),单列最大字节数设置。设置结果集中单个字符或二进制列值允许返回的最大字节数限制(仅适用于 BINARY、VARBINARY、CHAR、VARCHAR 等类型,设为 0 表示不限制)。

  • int getMaxFieldSize():(),单列最大字节数获取。获取当前针对单列返回值所限制的最大字节数。

  • void setFetchSize():(int rows),网络预取行数设置。向 JDBC 驱动提供性能提示,指定当 ResultSet 需要更多行数据时每次从数据库服务器批量抓取的行数。

  • int getFetchSize():(),网络预取行数获取。返回当前配置的每次从数据库抓取的结果集行数。

  • void setFetchDirection():(int direction),游标抓取方向设置。向驱动提示后续处理 ResultSet 数据行的遍历方向(可选值为 ResultSet.FETCH_FORWARD、FETCH_REVERSE 或 FETCH_UNKNOWN)。

  • int getFetchDirection():(),游标抓取方向获取。获取当前配置的默认结果集行抓取方向常量。

  • int getResultSetType():(),结果集滚动类型获取。返回由此 Statement 对象生成的 ResultSet 的滚动类型常量(如 ResultSet.TYPE_FORWARD_ONLY)。

  • int getResultSetConcurrency():(),结果集并发模式获取。返回由此 Statement 对象生成的 ResultSet 的并发修改模式常量(如 ResultSet.CONCUR_READ_ONLY)。

  • int getResultSetHoldability():(),结果集游标保持性获取。返回由此 Statement 对象生成的 ResultSet 在事务提交后的游标保持策略常量。

  • void setEscapeProcessing():(boolean enable),转义语法扫描开关。启用或禁用驱动在将 SQL 发送至数据库之前的标准 JDBC 转义语法({...})解析器(默认开启)。

  • void setCursorName():(String name),定位更新游标命名。设置后续 executeQuery 生成的结果集所使用的底层 SQL 游标名称,用于配合 WHERE CURRENT OF <cursorName> 执行定位更新或删除。

  • String enquoteLiteral():(String val),字符串字面量转义封装。自 JDK 9 引入的 default 默认方法,将传入的字符串用单引号包裹,并自动将内部包含的所有单引号转义为双单引号(''),防止静态 SQL 拼接语法错误或注入。

  • String enquoteIdentifier():(String identifier, boolean alwaysQuote),数据库标识符转义封装。自 JDK 9 引入的 default 默认方法,校验并返回合法的 SQL 标识符(如动态表名或列名),根据 alwaysQuote 参数或特殊字符情况自动包裹双引号。

  • String enquoteNCharLiteral():(String val),国家字符集字面量转义。自 JDK 9 引入的 default 默认方法,将传入的字符串转换为符合 SQL 标准的国家字符集字面量格式(即 N'...')并转义内部单引号。

  • boolean isSimpleIdentifier():(String identifier),简单标识符校验。自 JDK 9 引入的 default 默认方法,判断给定的字符串是否为无需引号包裹的标准简单 SQL 标识符(仅由字母开头并包含字母、数字和下划线)。

注意事项:

  1. MySQL 驱动在默认情况下执行 executeQuery() 时会将整个查询结果集一次性全部读入客户端内存中;当查询百万级大表为防止 OOM 内存溢出时,必须调用 stmt.setFetchSize(Integer.MIN_VALUE) 开启流式结果集逐行读取,或在连接 URL 中配置 useCursorFetch=true 后再设置正整数的 fetchSize。
  2. enquoteIdentifier() 与 enquoteLiteral() 对于无法使用 ? 占位符的动态表名、动态 ORDER BY 列名等场景非常实用,能够有效阻断标识符层面的 SQL 注入。
java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class StatementConfigDemo {

  // 1. 演示 Statement 执行超时、行数限制、抓取大小与安全转义配置
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456");
       Statement stmt = conn.createStatement()) {

      // 2. 设置 SQL 执行超时秒数、单列最大字节数与结果集最大返回行数
      stmt.setQueryTimeout(5);
      stmt.setMaxFieldSize(1024);
      stmt.setMaxRows(50);
      System.out.println("超时秒数: " + stmt.getQueryTimeout() + ", 最大行数: " + stmt.getMaxRows());

      // 3. 配置结果集游标抓取方向与每次网络交互预取的行数
      stmt.setFetchDirection(ResultSet.FETCH_FORWARD);
      stmt.setFetchSize(20);
      System.out.println("预取行数: " + stmt.getFetchSize() + ", 结果集类型: " + stmt.getResultSetType());

      // 4. 使用 JDK 9 引入的转义辅助方法安全构造动态标识符与字符串字面量
      String safeColumn = stmt.enquoteIdentifier("username", false);
      String safeValue = stmt.enquoteLiteral("Alice");
      System.out.println("安全转义条件: " + safeColumn + " = " + safeValue);
    }
  }
}

生命周期管理 ​

  • void close():(),语句对象关闭。立即释放当前 Statement 对象的数据库游标与底层 JDBC 资源,并同时隐式关闭由该对象打开的所有 ResultSet 结果集。

  • boolean isClosed():(),关闭状态判断。检查当前 Statement 对象是否已被调用 close() 关闭。

  • void cancel():(),异步中断执行。当另一个线程正在执行该 Statement 的耗时 SQL 时,可由监控线程调用此方法向数据库服务端发送中断请求以取消正在运行的 SQL 语句。

  • void closeOnCompletion():(),结果集联动关闭开启。自 JDK 7 引入,声明当此 Statement 生成的所有依赖 ResultSet 对象全部被关闭时,自动触发关闭当前 Statement 对象。

  • boolean isCloseOnCompletion():(),联动关闭状态查询。判断当前 Statement 是否已启用当结果集关闭时自动随之关闭的联动策略。

  • void setPoolable():(boolean poolable),语句池化状态设置。向语句池(Statement Pool)管理器提供提示,指定当前语句对象是否允许被缓存复用(Statement 默认为 false,PreparedStatement 默认为 true)。

  • boolean isPoolable():(),语句池化状态获取。返回当前 Statement 对象是否具备可池化缓存标记。

  • Connection getConnection():(),所属连接对象获取。返回创建了当前 Statement 实例的父级 Connection 连接对象。

  • SQLWarning getWarnings():(),语句执行告警获取。获取当前 Statement 执行期间数据库报告的第一个 SQLWarning 告警对象;每次执行新 SQL 时会自动清空上一次的告警。

  • void clearWarnings():(),语句执行告警清空。显式清除当前 Statement 对象上记录的所有 SQLWarning 告警链。

注意事项:

  1. 当方法需要将查询得到的 ResultSet 直接作为返回值交给上层调用者遍历时,不能在方法内部使用 try-with-resources 关闭 Statement(否则返回的 ResultSet 会立刻失效);此时应在返回前调用 stmt.closeOnCompletion(),这样当上层调用者关闭 ResultSet 时,底层的 Statement 便会自动随之关闭。
  2. cancel() 方法要求底层驱动和目标数据库同时支持异步网络取消指令,且必须从不同于正在执行 SQL 的另一个独立线程发起调用。
java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class StatementLifecycleDemo {

  // 1. 演示 Statement 关联关闭策略、池化提示与资源释放
  public static void main(String[] args) throws SQLException {
    String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
    try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
      Statement stmt = conn.createStatement();

      // 2. 开启语句池化缓存提示并校验其所属的 Connection 对象
      stmt.setPoolable(true);
      System.out.println("是否允许池化: " + stmt.isPoolable() + ", 所属连接: " + stmt.getConnection());

      // 3. 启用结果集关闭联动策略:当关联的 ResultSet 关闭时自动关闭当前 Statement
      stmt.closeOnCompletion();
      System.out.println("是否启用自动关联关闭: " + stmt.isCloseOnCompletion());

      try (ResultSet rs = stmt.executeQuery("SELECT id, username FROM t_user")) {
        if (rs.next()) {
          System.out.println("读取首行用户: " + rs.getString("username"));
        }
      }

      // 4. 验证 ResultSet 关闭后 Statement 是否已随之自动关闭
      System.out.println("ResultSet 关闭后 Statement 是否已关闭: " + stmt.isClosed());
    }
  }
}

继承: Wrapper ​

isWrapperFor, unwrap