Spring Data JDBC & R2DBC

@Query in Spring Data JDBC takes plain, database-specific SQL. Spring Data JPA's @Query defaults to JPQL (an entity-oriented query language). Spring Data JDBC has no JPQL, so you always write real SQL.

R2DBC is a non-blocking (reactive) database access layer. It has no lazy loading or @OneToMany/@ManyToOne relations because lazy loading would need a hidden blocking call. You fetch related rows with explicit extra queries yourself.

R2dbcRepository is Spring Data's reactive repository for relational databases. Its methods return reactive types: Mono<T> for zero-or-one result and Flux<T> for many, instead of blocking values or List.

AggregateReference<T, ID> is a typed link to another aggregate root by its id only. It stores the foreign-key id in a column but does NOT load the target object — reading gives you just getId(); you fetch the referenced aggregate separately if you need it.

Register an R2dbcTransactionManager (a ReactiveTransactionManager). Then either annotate a method returning Mono/Flux with @Transactional, or wrap the pipeline programmatically with TransactionalOperator.transactional(...). Commit happens on completion, rollback on an error signal.

Spring Data JDBC loads the whole aggregate immediately (no proxies) and returns plain objects with no persistence context tracking them. Changing a field does nothing until you explicitly call save(); there is no automatic flush.

Names come from the NamingStrategy. The default uses the class and property names as-is — no automatic snake_case. Property firstName maps to column firstName, not first_name, unless you override it.

@MappedCollection maps a collection field on the root to a separate child table. Its idColumn is the foreign key back to the parent, and keyColumn holds the list index or map key so ordered/keyed collections round-trip correctly.

@Embedded flattens a value object's properties into columns of the owner's table instead of a separate table. prefix adds a string before each embedded column name; onEmpty (USE_NULL or USE_EMPTY) decides whether an all-null embedded reads back as null or as an empty object.

Bind arguments with named parameters :name plus @Param. A collection bound to an IN (:ids) clause expands to multiple placeholders. Write queries need @Modifying and return void, int/long (rows affected), or boolean.

A RowMapper turns one ResultSet row into an object via mapRow(rs, rowNum). You attach it with @Query(rowMapperClass = X.class) or rowMapperRef="beanName". Use one when the default entity mapping cannot produce your shape, like a custom DTO from a join.

Either run separate reactive queries and combine them (flatMap/zip), or write a JOIN in a @Query and map the flat rows into a DTO with a custom converter, or use DatabaseClient for raw control. There is no automatic association mapping.

R2dbcEntityTemplate is a mid-level helper that maps entities to/from rows using a fluent, type-safe API (select/insert/update/delete with Query and Criteria). Use it for dynamic queries a derived repository method cannot express.

On updating a root, Spring Data JDBC deletes all its existing child rows and re-inserts the current ones, because it can't tell which children changed. This can churn auto-generated child ids and cause extra DELETE/INSERT SQL.

JdbcAggregateTemplate is the lower-level engine behind Spring Data JDBC repositories. It offers programmatic aggregate operations, insert, update, save, delete, findById, findAll, count, without declaring a repository interface. Use it for dynamic or fine-grained control over persistence.

The transactional connection is stored in the Reactor subscriber Context, which travels with the reactive chain regardless of which thread runs each step. Anything that starts a new, separate subscription (a fresh subscribe, a detached publisher, or blocking code) escapes that Context and the transaction.

DatabaseClient is the low-level fluent API: databaseClient.sql("...").bind("name", value).map(row -> ...).all() (or .one()/.first()/.rowsUpdated()). It runs raw SQL with named parameter binding and manual row mapping, returning Mono/Flux.

save() looks at the entity's @Id: if it is null (or 0 for primitives) the entity is treated as new and INSERTed; otherwise it is UPDATEd. With a manually assigned id, save() wrongly does an UPDATE that affects zero rows.

By default save() treats an entity as new (INSERT) when its @Id is null (or 0 for a primitive), otherwise UPDATE. With ids you assign yourself, a non-null id looks 'existing', so you implement Persistable.isNew(), add a @Version field, or set the id in a callback.

Spring Data JDBC doesn't track loaded entities. Loading the same row twice returns two distinct objects; there's no dirty checking, no lazy loading, no identity map. You load a whole aggregate and save the whole aggregate explicitly, and cross-aggregate links use AggregateReference (id only).

R2DBC drivers do database I/O without blocking threads: results are Publishers demanded via backpressure over a small pooled set of connections. A transaction pins one connection for its whole span, so long chains hold connections; and one blocking call on an event-loop thread can stall the entire app.

Reactive transactions are managed by R2dbcTransactionManager and bound to the Reactor subscriber context, not to a thread. Use @Transactional on a method returning Mono/Flux, or TransactionalOperator, so the commit/rollback follows the reactive chain.

Register a NamingStrategy bean and override its methods. Beyond getTableName and getColumnName, you can override getSchema (schema prefix), getReverseColumnName (back-reference FK in child tables) and getKeyColumn (list index / map key column).

Use @Query repositories for declarative CRUD and hand SQL reads. Use JdbcAggregateTemplate for programmatic aggregate operations and explicit insert/update control. Use NamedParameterJdbcTemplate for raw SQL that has no aggregate mapping, like reports or bulk operations.