Spring Data Relational

Spring Data R2DBC applies Domain-Driven Design (DDD) principles to R2DBC database drivers. It provides high-level abstractions for storing and querying aggregates, primarily through a template approach or via Repository interfaces.

Key features include:

• Configuration Support: Java-based @Configuration classes for R2DBC driver instances.
• R2dbcEntityTemplate: A central class for entity-bound operations, providing integrated object mapping between database rows and POJOs for common CRUD operations.
• Object Mapping: Feature-rich mapping integrated with Spring's Conversion Service, supporting both annotation-based metadata and extensible formats.
• Repository Support: Automatic implementation of Repository interfaces, including support for custom query methods.

Recommendation: For most tasks, use R2dbcEntityTemplate for ad-hoc CRUD operations or the Repository support for standard data access patterns.

If you do not provide explicit mapping metadata (like annotations), MappingR2dbcConverter uses a set of default conventions:

• Naming: The short Java class name is mapped to the table name, and field names are mapped to column names using a specific strategy (e.g., com.bigbank.SavingsAccount maps to SAVINGS_ACCOUNT, and firstName maps to FIRST_NAME). You can customize this with a NamingStrategy.
• Identifiers: By default, derived table and column names are used with database-specific quotes (making them case-sensitive). To use plain (unquoted) identifiers, use R2dbcMappingContext.forPlainIdentifiers(...) or set R2dbcMappingContext.setForceQuote(false).
• Nested Objects: Arbitrarily nested objects are not supported by convention. Use the @Embedded annotation for value objects that should map to columns in the same table.
• Object Creation: The converter prefers a single non-zero-argument constructor whose argument names match the top-level column names. If no such constructor exists, it falls back to a zero-argument constructor. If multiple non-zero-argument constructors exist, an exception is thrown.
• Fields vs Properties: The converter uses object fields directly; it does not use public JavaBean properties.

Spring Data JDBC is designed around Domain-Driven Design (DDD) principles, specifically the concepts of Aggregates, Aggregate Roots, and Repositories. Understanding these is critical because Spring Data JDBC's persistence model differs from traditional relational database patterns.

Key Concepts

• Aggregate: A cluster of domain objects (entities) that are treated as a single unit for data changes. An aggregate guarantees consistency for all its internal properties during atomic operations. For example, an Order and its OrderItems form an aggregate where the Order ensures the total count of items is always consistent with the actual items present.
• Aggregate Root: Every aggregate has exactly one root entity. This is the only entity through which the aggregate can be manipulated. All atomic changes to the aggregate must occur via methods on this root.
• Repository: An abstraction representing a collection of aggregates. In Spring Data JDBC, you should maintain one Repository per Aggregate Root.

Relationship Rules

1. Internal Consistency: Entities reachable from an aggregate root are considered part of that aggregate.
2. Foreign Keys: Spring Data JDBC assumes that only the aggregate root holds a foreign key to tables storing non-root entities within the same aggregate. No other entity should point toward these non-root entities.
3. Cross-Aggregate References: References between different aggregates are not guaranteed to be consistent immediately; they are eventually consistent.

WARNING

In the current implementation, Spring Data JDBC handles updates to entities referenced from an aggregate root by deleting and recreating them.

All references within an aggregate result in a foreign key relationship in the database. By default, the foreign key column name is the table name of the referencing entity.

• Composite IDs: If the referenced ID is an @Embedded id, the back reference uses multiple columns named <table-name>_<column-name> (e.g., PERSON_FIRST_NAME).
• Customizing Naming:
  • You can use DefaultNamingStrategy.setForeignKeyNaming(ForeignKeyNaming.IGNORE_RENAMING) to use the entity name instead of the table name.
  • For List and Map, an additional column is required for the index or key, named using the foreign key column name plus a _KEY suffix.
  • For full control, implement NamingStrategy.getReverseColumnName(RelationalPersistentEntity<?> owner).
• Annotation Override: For List and Map, you can use @MappedCollection(idColumn="your_column_name", keyColumn="your_key_column_name") to specify column names explicitly.