spring-projects/spring-framework

spring-jdbc

Active contributors: Juergen Hoeller, Sam Brannen

Purpose

spring-jdbc provides a thin abstraction over JDBC: the JdbcTemplate family of classes that eliminate boilerplate (resource cleanup, exception handling, parameter binding) while letting you keep direct control of SQL. It also delivers JDBC-flavored exception translation (SQLException → Spring's DataAccessException hierarchy) and connection-management utilities.

Directory layout

spring-jdbc/
└── src/main/java/org/springframework/jdbc/
    ├── core/
    │   ├── JdbcTemplate.java
    │   ├── JdbcOperations.java                    # interface
    │   ├── PreparedStatementCallback.java
    │   ├── RowMapper.java
    │   ├── namedparam/                            # NamedParameterJdbcTemplate
    │   ├── simple/                                # SimpleJdbcInsert, SimpleJdbcCall
    │   ├── support/                               # KeyHolder, GeneratedKeyHolder
    │   └── …
    ├── datasource/                                # DataSource utilities, transaction-aware wrappers
    │   ├── DriverManagerDataSource.java
    │   ├── DataSourceTransactionManager.java
    │   ├── DataSourceUtils.java
    │   ├── embedded/                              # H2, Derby, HSQLDB embedded support
    │   ├── init/                                  # ScriptUtils for executing SQL scripts
    │   └── lookup/                                # JNDI / mapping data sources
    ├── object/                                    # Higher-level "operation object" abstractions
    └── support/
        ├── SQLErrorCodeSQLExceptionTranslator.java
        ├── SQLStateSQLExceptionTranslator.java
        └── …

Key abstractions

Type	File	Role
`JdbcTemplate`	`spring-jdbc/src/main/java/org/springframework/jdbc/core/JdbcTemplate.java`	The core SQL-by-positional-args template
`NamedParameterJdbcTemplate`	`spring-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/NamedParameterJdbcTemplate.java`	SQL with `:name` placeholders
`SimpleJdbcInsert` / `SimpleJdbcCall`	`spring-jdbc/src/main/java/org/springframework/jdbc/core/simple/`	Metadata-driven inserts and stored-procedure calls
`RowMapper<T>`	`spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java`	Maps a `ResultSet` row to a Java object
`BeanPropertyRowMapper`	`spring-jdbc/src/main/java/org/springframework/jdbc/core/BeanPropertyRowMapper.java`	Reflection-based mapping to bean properties
`DataSourceUtils`	`spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DataSourceUtils.java`	Connection acquisition with transaction awareness
`DataSourceTransactionManager`	`spring-jdbc/src/main/java/org/springframework/jdbc/datasource/DataSourceTransactionManager.java`	`PlatformTransactionManager` for JDBC
`SQLExceptionTranslator`	`spring-jdbc/src/main/java/org/springframework/jdbc/support/SQLExceptionTranslator.java`	Maps `SQLException` to `DataAccessException`
`EmbeddedDatabaseBuilder`	`spring-jdbc/src/main/java/org/springframework/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.java`	Bootstraps in-memory H2/HSQLDB/Derby

How it works

Template method pattern

JdbcTemplate is built around the template method pattern: the template handles open/close, the caller supplies the work.

sequenceDiagram
    participant App
    participant Tpl as JdbcTemplate
    participant DS as DataSource
    participant Conn as Connection
    participant PS as PreparedStatement
    App->>Tpl: query(sql, rowMapper)
    Tpl->>DS: getConnection (via DataSourceUtils — transaction-aware)
    DS-->>Tpl: Connection
    Tpl->>Conn: prepareStatement(sql)
    Conn-->>Tpl: PreparedStatement
    Tpl->>PS: setParameter / executeQuery
    PS-->>Tpl: ResultSet
    Tpl->>Tpl: rowMapper.mapRow per row
    Tpl-->>App: List<T>
    Tpl->>Conn: close (or release if transactional)

If a transaction is active, DataSourceUtils returns the bound connection rather than opening a new one. That's how JdbcTemplate participates in @Transactional boundaries managed by DataSourceTransactionManager.

Exception translation

SQLException carries vendor-specific error codes. Spring translates them via SQLErrorCodeSQLExceptionTranslator, which reads org/springframework/jdbc/support/sql-error-codes.xml (a vendor-keyed mapping) and produces a typed DataAccessException. The hierarchy:

DataAccessException
├── DataAccessResourceFailureException
├── DataIntegrityViolationException
├── DuplicateKeyException
├── DeadlockLoserDataAccessException
├── BadSqlGrammarException
├── CannotAcquireLockException
└── ...

The translator falls back to SQLStateSQLExceptionTranslator for vendors not covered.

Embedded database support

EmbeddedDatabaseBuilder wires up H2, HSQLDB, or Derby in-memory and runs initialization scripts. Heavily used in tests.

Integration points

Depends on: spring-beans, spring-core, spring-tx.
Used by: spring-orm (Hibernate uses Spring's exception translator), spring-r2dbc shares conceptual peers, all data-access-using application code.
Related: spring-tx for transaction management; transactions and JDBC operations together require both modules.

Entry points for modification

Add support for a new database — Append to org/springframework/jdbc/support/sql-error-codes.xml. No code change needed for new vendor error codes.
Custom row mapping — Implement RowMapper<T> or use DataClassRowMapper (records/data classes).
Custom statement creation — Use PreparedStatementCreator and PreparedStatementSetter for precise control.

Notable internals

SqlParameterSource / MapSqlParameterSource / BeanPropertySqlParameterSource — Three flavors of named-parameter binding for NamedParameterJdbcTemplate.
KeyHolder — Captures RETURNING ... / generated-key results from inserts.
ScriptUtils — Runs SQL scripts; honors comments, terminators, separators. Used by EmbeddedDatabaseBuilder.