Differences from Spring
spring_boot_starter_data follows Spring Data JDBC and Spring Boot: the same annotations, interfaces, query grammar, transaction rules and property names where they make sense. This page lists every place where it does not, and why.
Why
When you port a Spring application, or follow a Spring Data tutorial, you need to know where the behaviour is not the one you expect. Most differences come from three facts:
- Dart is not Java. There is no reflection at run time, no overloading, no checked exceptions and no threads: the build writes the repositories, methods have distinct names, every exception rolls back, and transactions follow
awaitthrough aZone. - Everything is asynchronous. Dart has one thread per isolate, so there is no blocking API.
- The build knows more. Derived query names,
@Querytexts and SpEL expressions are checked by the build, not at startup.
Example
abstract interface class BookRepository implements ListCrudRepository<Book, int> {
Future<List<Book>> findByTitleContaining(String part);
Future<Book?> findFirstByOrderByYearAsc();
}
interface BookRepository extends ListCrudRepository<Book, Long> {
List<Book> findByTitleContaining(String part);
Optional<Book> findFirstByOrderByYearAsc();
}
Repositories
| Spring Data | Here | Why |
|---|---|---|
Repository |
DataRepository |
@Repository is the stereotype annotation. |
@NoRepositoryBean |
not needed | A generic interface is never a bean. |
@EnableJdbcRepositories |
not needed | Every repository interface of the scanned code is a bean. |
Synchronous results, Optional |
Future or Stream, nullable values |
Dart is asynchronous; null safety replaces Optional. |
findAll(Sort), findAll(Pageable) |
findAllSorted(Sort), findAllPaged(Pageable) |
No overloading. |
deleteAll(Iterable) |
deleteAllOf(Iterable) |
No overloading. |
Sort.Order |
SortOrder |
@Order orders beans. |
| Query names checked at startup | checked by the build | The generator parses them. |
The database per package (jdbcOperationsRef) |
@UseDataSource('name') per repository |
Simpler with properties. |
| One store per module | @UseStore('memory'), @UseStore('jdbc') |
One starter, several stores. |
| A feature a module lacks does not exist there | A store declares its capabilities; a repository that needs more fails at startup | The same repository interface runs on several stores. |
@Procedure(procedureName = "name") (Spring Data JPA only) |
@Procedure('name') |
A database function called by name. |
| No change streams in Spring Data JDBC | RowChange streams on the stores that report changes |
@Query
- The parameters are matched by name without
@Param. {Entity}and{Entity.property}placeholders are additions.rowMapperClassandresultSetExtractorClassarerowMapperandresultSetExtractor, given as functions.- The text, the parameters, misspelled tables and columns, and SpEL expressions are checked by the build. SpEL is compiled to Dart where possible.
name:(named queries) is not supported yet.@Queryneeds a SQL store: the in-memory store refuses it at startup.
The model
- References:
AggregateReferenceas in Spring Data JDBC, plus@Reference(Author) int authorId, which Spring Data JDBC does not have. - Foreign keys,
@OnDelete(Hibernate's name),@Uniqueand@UniqueConstraint(JPA's names) are additions: Spring Data JDBC leaves the schema to you. - A field whose type is an entity without
@MappedCollectionis a mapping error, where Spring Data JDBC takes it as a child. @EnableDataAuditingis Spring's@EnableJdbcAuditing.
Transactions
| Spring | Here | Why |
|---|---|---|
@Transactional("manager") |
@Transactional(transactionManager: 'manager') |
Dart cannot mix an optional positional parameter with named ones. |
| Checked exceptions commit | every exception rolls back; list the ones to commit in noRollbackFor |
Dart has no checked exceptions. |
A @Lock query outside a transaction runs in autocommit |
it fails with IllegalTransactionStateException |
An unlocked "locking" read is a bug. |
| Thread-bound transactions | Zone-bound: they follow await; work started without await that outlives the transaction fails |
Dart has no threads. |
A synchronous @Transactional method |
stops the start | The transaction covers the Future. |
PostgreSQL 40001, 40P01, 55P03, 25006 give CannotAcquireLockException, PessimisticLockingFailureException, UncategorizedSQLException (Spring 7's JdbcTemplate) |
CannotSerializeTransactionException, DeadlockLoserDataAccessException, CannotAcquireLockException, InvalidDataAccessResourceUsageException |
The finer classes of Spring's PostgreSQL error-code table, with the same supertypes. |
The rest is measured against Spring: 304 scenarios (propagation, rollback rules, isolation, locks, versions, timeouts) run on PostgreSQL in the starter and in a Spring Boot 4.1 application, and a CI job compares the outcomes. The table above is what remains, on purpose.
Databases and configuration
| Spring Boot | Here |
|---|---|
| A JDBC driver on the classpath | the sqlite3 or postgres package, wired by the generator |
HikariCP, spring.datasource.hikari.* |
the starter's pool, spring.datasource.pool.* |
| A second database in code | spring.datasources.<name>.* |
Flyway, spring.flyway.* |
the starter's runner with Flyway's naming, spring.sql.migration.* |
spring.jpa.hibernate.ddl-auto |
spring.data.jdbc.schema (none, validate, create, create-drop; no update), validate by default |
SpringApplication.run |
runApplicationAsync with a SQL database: the schema is set up on a connection, which Dart cannot wait for without await |
| Values never masked in logs | secret-looking names masked |
DataSourceTransactionManager.prepareTransactionalConnection to override, DataSource adapters |
JdbcSessionHook beans |
Paging
PageRequest.ofrefuses an offset past 2^53 - 1, so an offset never wraps.- The in-memory store and SQLite order text by code units; PostgreSQL by its collation, as in Spring.
- An order that ignores case (
SortOrder.ignoreCase,?sort=name,ignorecase) lowers the column only for aStringor an enum property. For any other property it is a plain order: a client could otherwise get a database error out of?sort=id,ignorecaseon PostgreSQL. Spring Data JPA lowersStringproperties only. A sort name of a@Querymethod that is no property of the entity is still lowered as asked.
Testing
@DataTest replaces @DataJdbcTest with @AutoConfigureTestDatabase: it is transactional by itself, the test database is always an in-memory SQLite one (replaceDatabase: false keeps yours), and a failing @Commit test is rolled back.
Not supported yet
- Named queries (
@Query(name:)). - Custom converters (
@ReadingConverter,@WritingConverter) andBigDecimal: keep money as anintin minor units, never adouble. - MongoDB and other non-SQL stores.
- An
updateschema mode (by design: write a migration). - A clean command for migrations (by design: the runner never drops anything).