Transactions

@Transactional() on a bean method runs it in a transaction: the transaction commits when the method's Future completes, and rolls back when it fails. TransactionTemplate does the same in code. The rules are Spring's, and they are checked against Spring itself: 304 scenarios run on PostgreSQL in the starter and in a Spring Boot 4.1 application, and the CI compares their outcomes one by one.

Why

A business operation often writes several rows that must change together: an order and its stock, a transfer between two accounts. If the second write fails, the first must be undone. A transaction gives you that, and with @Transactional the commit, the rollback and the joining of nested calls are not your code.

Example

@Service()
class Checkout {
  Checkout(this.stock, this.orders, this.audit);

  final StockRepository stock;
  final OrderRepository orders;
  final AuditLog audit;

  // One transaction: the stock row stays locked until the order is saved;
  // any exception rolls everything back.
  @Transactional()
  Future<PurchaseOrder> place(int bookId) async {
    final row = (await stock.findByBookId(bookId))!;   // @Lock(pessimisticWrite)
    if (row.available == 0) {
      throw OutOfStock(bookId);                          // rolls back
    }
    row.available--;
    await stock.save(row);
    await audit.record('placed $bookId');                // joins, or not: see AuditLog
    return orders.save(PurchaseOrder(bookId: bookId));
  }
}

@Service()
class AuditLog {
  AuditLog(this.entries);

  final AuditRepository entries;

  // Its own transaction: the entry is kept even when the order rolls back.
  @Transactional(propagation: Propagation.requiresNew)
  Future<void> record(String text) => entries.save(AuditEntry(text: text));
}

@Transactional

Attribute Default Meaning
transactionManager '' The transaction manager bean, by name or qualifier; empty for the primary one.
propagation Propagation.required How the method relates to a transaction already running.
isolation Isolation.defaultLevel The isolation level of a transaction started here.
timeout null The longest a transaction started here may run; null for none.
readOnly false Whether a transaction started here only reads; PostgreSQL and the in-memory store refuse writes in it.
rollbackFor [] Exception types (and subtypes) that roll back, also when a supertype is in noRollbackFor.
noRollbackFor [] Exception types (and subtypes) after which the transaction commits.
label [] Labels for logs and tools; not interpreted.

On a class, it applies to each public method without its own @Transactional.

Rules of use

Propagation

Value Within a transaction Without one
required (default) joins it starts one
supports joins it runs without
mandatory joins it IllegalTransactionStateException
requiresNew sets it aside and starts its own; does not see the outer's uncommitted rows starts one
notSupported sets it aside and runs in autocommit runs without
never IllegalTransactionStateException runs without
nested runs in a savepoint: a failure rolls back to it and the outer goes on starts one

A method that joins and fails marks the outer transaction rollback-only. The outer commit then throws UnexpectedRollbackException, even when the outer method caught the error. This is Spring's behaviour, and a common surprise.

requiresNew and notSupported take another connection from the pool: with pool.max-size=1 (an in-memory SQLite database) they cannot run inside a transaction.

Isolation

Value Means
defaultLevel The store's: PostgreSQL read committed, SQLite serializable, in memory read committed.
readUncommitted May see uncommitted changes. PostgreSQL runs it as read committed.
readCommitted Sees only committed changes; a row read twice may differ.
repeatableRead A row read twice is the same; new rows may appear, except in PostgreSQL (a snapshot).
serializable As if one after the other; a conflict fails one (CannotSerializeTransactionException).

A store offers some levels: PostgreSQL all of them, SQLite defaultLevel and serializable, the in-memory store read committed only. Asking for a level the store does not offer fails when the transaction starts (InvalidIsolationLevelException), never silently with a weaker one.

What PostgreSQL's levels show, measured by the comparison with Spring:

read committed repeatable read serializable
dirty read no no no
non-repeatable read yes no no
phantom yes no no
lost update, read-modify-write the second overwrites the second fails (40001) the second fails
lost update, balance = balance + n none: the second waits, then adds the second fails (40001) the second fails
write skew yes yes the second commit fails (40001)

Timeouts and read-only

TransactionTemplate

@Service()
class Restock {
  Restock(this.transactions, this.stock);

  final TransactionTemplate transactions;   // a bean over the only transaction manager
  final StockRepository stock;

  Future<void> add(int bookId, int count) => transactions.executeWithoutResult((status) async {
    final row = (await stock.findByBookId(bookId))!;
    if (count <= 0) {
      status.setRollbackOnly();             // roll back without throwing
      return;
    }
    row.available += count;
    await stock.save(row);
  });
}

Several transaction managers

Each data source has its own manager: transactionManager for the primary one, <name>TransactionManager (qualified <name>) for each spring.datasources.<name>. Choose one by name:

@Transactional(transactionManager: 'stats')
Future<void> visit(String page) => visits.save(Visit(page: page));

A transaction covers one manager. Work on two databases in one method is two transactions, each committed on its own.

The transaction follows await

Spring keeps the current transaction in a thread-local. Dart has one thread and many interleaved tasks, so the transaction lives in a Zone: it follows every await of the method, and two requests running at the same time never share one.

Work started inside the transaction without await, and still running after it ended, fails with IllegalTransactionStateException when it uses the database, instead of running outside the transaction:

@Transactional()
Future<void> wrong() async {
  unawaited(books.save(Book(title: 'Late')));   // fails if it outlives the transaction
}

Repositories and transactions

The write methods of a repository (save, saveAll, delete*, deleteBy) run in a required transaction of its store, as Spring's SimpleJdbcRepository is @Transactional: saveAll and an aggregate with its children are atomic, and inside your transaction they join it. The read methods join a running transaction, or run on their own.

In Spring (Java)

@Transactional(propagation = Propagation.REQUIRES_NEW, noRollbackFor = NotifyFailed.class)
public void record(String text) { ... }

The differences:

See also