jdbcclient: JdbcClient on Spring Framework 7.0.10 / Boot 4.1.2, with twelve real transcripts

Parameters, row mapping, single/optional/list, generated keys, batch via NamedParameterJdbcTemplate (JdbcClient has none),
exception translation, transactions, an unclosed stream() exhausting a 2-connection pool, withMaxRows truncating silently,
and spring.jdbc.template.* reaching the auto-configured JdbcClient. JdbcClient API diffed across 6.1.0, 6.2.19 and 7.0.0.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b5n3PRbPkUsiJybTeg
This commit is contained in:
Ankur Mhatre
2026-11-18 21:25:30 +05:30
co-authored by Claude Sonnet 5.5
parent 260c8a692f
commit fc8bc933d5
38 changed files with 1158 additions and 0 deletions
+8
View File
@@ -0,0 +1,8 @@
findBySku("MS-002") JdbcClient == JdbcTemplate: true
findBySku("NOPE") both Optional.empty: true
findInStockCheaperThan(4000) rows: 3, identical: true
findBySkus([KB-001, WC-005]) rows: 2, identical: true
updateStock(1, 99) rows updated by each: 1
First row returned by findBySku("MS-002"):
Product[id=2, sku=MS-002, name=Wireless Mouse, price=1299.50, inStock=true, createdOn=2026-02-14, stockCount=40]
+28
View File
@@ -0,0 +1,28 @@
methods on JdbcClient and its three spec interfaces, read by reflection (21 names):
JdbcClient.create
JdbcClient.sql
MappedQuerySpec.list
MappedQuerySpec.optional
MappedQuerySpec.set
MappedQuerySpec.single
MappedQuerySpec.stream
ResultQuerySpec.listOfRows
ResultQuerySpec.optionalValue
ResultQuerySpec.rowSet
ResultQuerySpec.singleColumn
ResultQuerySpec.singleRow
ResultQuerySpec.singleValue
StatementSpec.param
StatementSpec.paramSource
StatementSpec.params
StatementSpec.query
StatementSpec.update
StatementSpec.withFetchSize
StatementSpec.withMaxRows
StatementSpec.withQueryTimeout
any method with 'batch' in its name: false
beans of type JdbcClient in the Boot context: 1 ([jdbcClient])
implementation class: org.springframework.jdbc.core.simple.DefaultJdbcClient
beans Boot also provides: JdbcTemplate=true NamedParameterJdbcTemplate=true
+15
View File
@@ -0,0 +1,15 @@
1 .param(v).param(v) ? placeholders -> [Mechanical Keyboard]
2 .param(1, v) by index -> [Mechanical Keyboard]
3 .params(List.of(..)) ? placeholders -> [Wireless Mouse, Headset]
4 .param("sku", v) :named -> [Mechanical Keyboard]
5 .params(Map.of(..)) :named -> [Mechanical Keyboard]
6 .paramSource(record) :named, record -> [Mechanical Keyboard]
7 :p used twice, one .param("p", 10) :named -> [KB-001, MS-002]
8 IN (:skus) with a 3-element list expanded -> [KB-001, WC-005] (NOPE matched nothing)
9 LIKE :q with "%o%" wildcard in value -> [Mechanical Keyboard, Wireless Mouse, Monitor 27 inch]
10 :named and ? in one statement -> java.lang.IllegalStateException: Configure either named or indexed parameters, not both
11 typo in the parameter name (:sku, supplied skuu) -> org.springframework.dao.InvalidDataAccessApiUsageException: No value supplied for the SQL parameter 'sku': No value registered for key 'sku'
12 two ? but one value -> org.springframework.dao.DataIntegrityViolationException: PreparedStatementCallback; SQL [SELECT name FROM product WHERE sku = ? AND in_stock = ?]; Parameter "#2" is not set; SQL statement: SELECT name FROM product WHERE sku = ? AND in_stock = ? [90012-240] [root cause: JdbcSQLDataException: Parameter "#2" is not set; SQL statement: SELECT name FROM product WHERE sku = ? AND in_stock = ? [90012-240]]
13 .param("sku", null) -> ran, rows: 0 (= NULL is never true)
.param("sku", null, Types.VARCHAR) -> ran, rows: 0 (= NULL is never true)
+20
View File
@@ -0,0 +1,20 @@
1 SELECT * into the Product record (in_stock -> inStock, created_on -> createdOn, stock_count -> stockCount):
Product[id=1, sku=KB-001, name=Mechanical Keyboard, price=4999.00, inStock=true, createdOn=2026-01-10, stockCount=12]
Product[id=2, sku=MS-002, name=Wireless Mouse, price=1299.50, inStock=true, createdOn=2026-02-14, stockCount=40]
Product[id=3, sku=MN-003, name=Monitor 27 inch, price=18999.00, inStock=false, createdOn=2026-03-01, stockCount=0]
Product[id=4, sku=HS-004, name=Headset, price=2499.00, inStock=true, createdOn=2026-03-22, stockCount=7]
Product[id=5, sku=WC-005, name=Webcam, price=3199.00, inStock=true, createdOn=2026-04-05, stockCount=3]
2 a record with fewer components than columns: Slim[sku=KB-001, name=Mechanical Keyboard]
3 a JavaBean with setters for three of the seven columns: Bean[sku=KB-001, price=4999.00, inStock=true]
4 a single column to a simple type: [12, 40, 0, 7, 3] and Wireless Mouse
5 a RowMapper lambda: MS-002 costs 1299.50
6 record asks for colourName, SELECT has no such column: org.springframework.jdbc.BadSqlGrammarException: PreparedStatementCallback; bad SQL grammar [SELECT sku FROM product WHERE id = 1] [root cause: JdbcSQLSyntaxErrorException: Column "colourName" not found [42122-240]]
7 record asks for primitive int missingCol, no such column: org.springframework.jdbc.BadSqlGrammarException: PreparedStatementCallback; bad SQL grammar [SELECT sku FROM product WHERE id = 1] [root cause: JdbcSQLSyntaxErrorException: Column "missingCol" not found [42122-240]]
8 VARCHAR column into a LocalDate component: org.springframework.dao.DataIntegrityViolationException: PreparedStatementCallback; SQL [SELECT sku, name FROM product WHERE id = 1]; Cannot parse "DATE" constant "Mechanical Keyboard" [22007-240] [root cause: NumberFormatException: Error at index 0 in: "Mechanical Keyb"]
9 SQL NULL into the primitive int stockCount: org.springframework.core.convert.ConversionFailedException: Failed to convert from type [null] to type [int] for value [null] [root cause: IllegalArgumentException: A null value cannot be assigned to a primitive type]
the same NULL into Integer stockCount: NullBoxed[sku=KB-001, stockCount=null]
10 untyped listOfRows(): keys as the driver returns them: [SKU, IN_STOCK], value classes: [String, Boolean]
lookup is case-insensitive: row.get("sku") = KB-001
+14
View File
@@ -0,0 +1,14 @@
0 rows 1 row 4 rows
list() [] [Mechanical Keyboard] 4 items
single() EmptyResult.. Mechanical Keyboard IncorrectResultSize..
optional() Optional.empty Optional[Mechanical Keyboard] IncorrectResultSize..
set() [] [Mechanical Keyboard] 4 items
single() on 0 rows: org.springframework.dao.EmptyResultDataAccessException: Incorrect result size: expected 1, actual 0
single() on 4 rows: org.springframework.dao.IncorrectResultSizeDataAccessException: Incorrect result size: expected 1, actual 4
EmptyResultDataAccessException extends IncorrectResultSizeDataAccessException: true
untyped singleValue() of COUNT(*): 5 (Long)
untyped optionalValue() with no row: Optional.empty
optional() over SELECT MAX(price) with no matching rows: Optional.empty
single() over the same query: org.springframework.dao.TypeMismatchDataAccessException: Result value is null but no null value expected
+5
View File
@@ -0,0 +1,5 @@
insert via paramSource(record) and update(keys, "id"): generated id = 6
update(keys) with no column names: key columns = [ID, CREATED_ON]
update(keys, "id"): key columns = [ID], id = 8
a row inserted without created_on / in_stock / stock_count got the column defaults: in_stock=true stock_count=0 created_on=today: true
rows now in the table: 8
+5
View File
@@ -0,0 +1,5 @@
2000 inserts into in-memory H2 (no network round trip, so the gap understates a real database):
a loop of jdbc.sql(..).update() : finished (timing varies per run, not asserted)
one NamedParameterJdbcTemplate.batchUpdate: finished, 2000 result codes returned
loop took more than batch (indicative, one run): true
rows in the table after the batch: 2005 (5 seed rows + 2000)
+5
View File
@@ -0,0 +1,5 @@
duplicate unique value -> DuplicateKeyException (database said SQLState 23505)
NULL into a NOT NULL column -> DataIntegrityViolationException (database said SQLState 23502)
CHECK constraint violated -> DataIntegrityViolationException (database said SQLState 23513)
typo in the SQL -> BadSqlGrammarException (database said SQLState 42001)
all four are unchecked DataAccessException subclasses: true
+7
View File
@@ -0,0 +1,7 @@
start: keyboard(1)=12 webcam(5)=3
@Transactional move of 5 from webcam to keyboard -> DataIntegrityViolationException
after: keyboard(1)=12 webcam(5)=3 (both UPDATEs rolled back)
same body, no @Transactional -> DataIntegrityViolationException
after: keyboard(1)=17 webcam(5)=3 (the first UPDATE had already committed)
TransactionTemplate, UPDATE then RuntimeException -> IllegalStateException; mouse(2)=40 (was 40)
inside a transaction a later SELECT sees the earlier UPDATE: 55; after commit: 55
+8
View File
@@ -0,0 +1,8 @@
Hikari pool: maximum-pool-size=2, connection-timeout=500 ms
rows in the table, via count(): 5
two streamAll() calls left open, then one ordinary count():
-> CannotGetJdbcConnectionException after about 500 ms
root cause: HikariPool-N - Connection is not available, request timed out after 500ms (...)
after closing both streams, count() works again: 5
try-with-resources: names of rows 1..2: [Mechanical Keyboard, Wireless Mouse]
and the connection is back: count() = 5
+4
View File
@@ -0,0 +1,4 @@
5 rows in the table
list() -> 5 rows
withMaxRows(2).list() -> 2 rows [KB-001, MS-002] (no warning, no exception)
a query that would run for minutes with withQueryTimeout(1) -> QueryTimeoutException (about 1 s)
@@ -0,0 +1,2 @@
spring.jdbc.template.max-rows=2 in application properties, 5 rows in the table
auto-configured JdbcClient: SELECT sku FROM product -> 2 rows
+15
View File
@@ -0,0 +1,15 @@
public signatures of JdbcClient + StatementSpec + ResultQuerySpec + MappedQuerySpec, diffed between releases
6.1.0: 40 signatures
6.2.0: 41 signatures
6.1.0 -> 6.2.0:
> public default Optional<Object> optionalValue();
6.2.19: 41 signatures
6.2.0 -> 6.2.19: no change
7.0.0: 45 signatures
6.2.19 -> 7.0.0:
> public abstract JdbcClient$StatementSpec withFetchSize(int);
> public abstract JdbcClient$StatementSpec withMaxRows(int);
> public abstract JdbcClient$StatementSpec withQueryTimeout(int);
> public static JdbcClient create(org.springframework.jdbc.core.namedparam.NamedParameterJdbcOperations, org.springframework.core.convert.ConversionService);
7.0.10: 45 signatures
7.0.0 -> 7.0.10: no change
@@ -0,0 +1,8 @@
DefaultJdbcClient (spring-jdbc 7.0.10), fields and constructors:
private final NamedParameterJdbcOperations namedParamOps;
private final ConversionService conversionService;
private final Map<Class<?>, RowMapper<?>> rowMapperCache;
public DefaultJdbcClient(javax.sql.DataSource);
public DefaultJdbcClient(JdbcOperations);
public DefaultJdbcClient(NamedParameterJdbcOperations, ConversionService);
public JdbcClient$StatementSpec sql(String);