
# 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 `await` through a `Zone`.
- **Everything is asynchronous.** Dart has one thread per isolate, so there is no blocking API.
- **The build knows more.** Derived query names, `@Query` texts and SpEL expressions are checked by the build, not at startup.

## Example

```dart
abstract interface class BookRepository implements ListCrudRepository<Book, int> {
  Future<List<Book>> findByTitleContaining(String part);
  Future<Book?> findFirstByOrderByYearAsc();
}
```

```java
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](stores.md); 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')`](database-functions.md) | A database function called by name. |
| No change streams in Spring Data JDBC | [`RowChange` streams](changes.md) on the stores that report changes | |

## @Query

- The parameters are matched by name without `@Param`.
- `{Entity}` and `{Entity.property}` placeholders are additions.
- `rowMapperClass` and `resultSetExtractorClass` are `rowMapper` and `resultSetExtractor`, 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.
- `@Query` needs a SQL store: the in-memory store refuses it at startup.

## The model

- References: `AggregateReference` as in Spring Data JDBC, plus `@Reference(Author) int authorId`, which Spring Data JDBC does not have.
- Foreign keys, `@OnDelete` (Hibernate's name), `@Unique` and `@UniqueConstraint` (JPA's names) are additions: Spring Data JDBC leaves the schema to you.
- A field whose type is an entity without `@MappedCollection` is a mapping error, where Spring Data JDBC takes it as a child.
- `@EnableDataAuditing` is 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`](session-hooks.md) beans |

## Paging

- `PageRequest.of` refuses 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 a `String` or an enum property. For any other property it is a plain order: a client could otherwise get a database error out of `?sort=id,ignorecase` on PostgreSQL. Spring Data JPA lowers `String` properties only. A sort name of a `@Query` method 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`) and `BigDecimal`: keep money as an `int` in minor units, never a `double`.
- MongoDB and other non-SQL stores.
- An `update` schema mode (by design: write a migration).
- A clean command for migrations (by design: the runner never drops anything).

## See also

- [Overview](index.md)
- [All properties](properties.md)
- [Transactions](transactions.md)
