トランザクション

Bean のメソッドに @Transactional() を付けると、それをトランザクションの中で実行します。トランザクションは、メソッドの Future が完了するとコミットし、失敗するとロールバックします。TransactionTemplate は同じことをコードで行います。ルールは Spring のもので、Spring 自身と照合されています。304 のシナリオを、PostgreSQL 上で、スターターと Spring Boot 4.1 のアプリケーションの両方で実行し、CI がその結果を一つずつ比較しています。

使う理由

業務処理では、まとめて変わらなければならない複数の行を書くことがよくあります。注文とその在庫、2 つの口座間の振替などです。2 番目の書き込みが失敗したら、最初のものを取り消さなければなりません。トランザクションはそれを実現し、@Transactional を使えば、コミット、ロールバック、入れ子の呼び出しの参加は自分のコードではなくなります。

例

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

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

  // 一つのトランザクション: 在庫の行は注文が保存されるまでロックされたまま。
  // どの例外もすべてをロールバックする。
  @Transactional()
  Future<PurchaseOrder> place(int bookId) async {
    final row = (await stock.findByBookId(bookId))!;   // @Lock(pessimisticWrite)
    if (row.available == 0) {
      throw OutOfStock(bookId);                          // ロールバックする
    }
    row.available--;
    await stock.save(row);
    await audit.record('placed $bookId');                // 参加するかどうか: AuditLog を参照
    return orders.save(PurchaseOrder(bookId: bookId));
  }
}

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

  final AuditRepository entries;

  // 独自のトランザクション: 注文がロールバックしてもエントリーは残る。
  @Transactional(propagation: Propagation.requiresNew)
  Future<void> record(String text) => entries.save(AuditEntry(text: text));
}

@Transactional

属性 デフォルト 意味
transactionManager '' トランザクションマネージャーの Bean。名前または修飾子で。プライマリーのものなら空。
propagation Propagation.required すでに実行中のトランザクションとメソッドの関係。
isolation Isolation.defaultLevel ここで開始されるトランザクションの分離レベル。
timeout null ここで開始されるトランザクションが実行してよい最長時間。なしは null。
readOnly false ここで開始されるトランザクションが読み取りだけかどうか。PostgreSQL とメモリ上のストアはその中での書き込みを拒否する。
rollbackFor [] ロールバックする例外の型 (とそのサブタイプ)。スーパータイプが noRollbackFor にあっても。
noRollbackFor [] その後でトランザクションがコミットする例外の型 (とそのサブタイプ)。
label [] ログやツールのためのラベル。解釈されない。

クラスに付けると、自分の @Transactional を持たない各 public メソッドに適用されます。

使い方のルール

伝播

値 トランザクションの中で トランザクションの外で
required (デフォルト) 参加する 開始する
supports 参加する トランザクションなしで実行する
mandatory 参加する IllegalTransactionStateException
requiresNew それを保留して独自のものを開始する。外側のコミットされていない行は見えない 開始する
notSupported それを保留してオートコミットで実行する トランザクションなしで実行する
never IllegalTransactionStateException トランザクションなしで実行する
nested セーブポイントの中で実行する: 失敗するとそこまでロールバックし、外側は続く 開始する

参加して失敗したメソッドは、外側のトランザクションをロールバック専用にします。そのため外側のコミットは、外側のメソッドがエラーを捕まえていても UnexpectedRollbackException を投げます。これは Spring の動作で、よくある驚きの元です。

requiresNew と notSupported はプールから別の接続を取ります。pool.max-size=1 (メモリ上の SQLite データベース) では、それらをトランザクションの中で実行できません。

分離レベル

値 意味
defaultLevel ストアのもの: PostgreSQL は read committed、SQLite は serializable、メモリ上は read committed。
readUncommitted コミットされていない変更が見えることがある。PostgreSQL は read committed として実行する。
readCommitted コミットされた変更だけが見える。2 回読んだ行が異なることがある。
repeatableRead 2 回読んだ行は同じ。新しい行が現れることがある (PostgreSQL を除く。スナップショット)。
serializable 一つずつ順に実行したかのように。衝突すると一方が失敗する (CannotSerializeTransactionException)。

ストアが提供するレベルは一部です。PostgreSQL はすべて、SQLite は defaultLevel と serializable、メモリ上のストアは read committed だけです。ストアが提供しないレベルを求めると、トランザクションの開始時に失敗します (InvalidIsolationLevelException)。黙ってより弱いレベルになることは決してありません。

Spring との比較で測定した、PostgreSQL のレベルが示すもの:

read committed repeatable read serializable
ダーティリード なし なし なし
反復不能読み取り あり なし なし
ファントム あり なし なし
更新の喪失 (読み取り・変更・書き込み) 2 番目が上書きする 2 番目が失敗する (40001) 2 番目が失敗する
更新の喪失 (balance = balance + n) なし: 2 番目は待ってから加算する 2 番目が失敗する (40001) 2 番目が失敗する
書き込みスキュー あり あり 2 番目のコミットが失敗する (40001)

タイムアウトと読み取り専用

TransactionTemplate

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

  final TransactionTemplate transactions;   // 唯一のトランザクションマネージャーの上の Bean
  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();             // 例外を投げずにロールバックする
      return;
    }
    row.available += count;
    await stock.save(row);
  });
}

複数のトランザクションマネージャー

各データソースは独自のマネージャーを持ちます。プライマリーのものには transactionManager、各 spring.datasources.<name> には <name>TransactionManager (修飾子 <name>) です。名前で一つを選びます。

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

トランザクションがカバーするのは一つのマネージャーです。一つのメソッドで 2 つのデータベースを扱う処理は 2 つのトランザクションで、それぞれ個別にコミットされます。

トランザクションは await に従う

Spring は現在のトランザクションをスレッドローカルに保持します。Dart には一つのスレッドと多くの交互に実行されるタスクがあるため、トランザクションは Zone の中にあります。それはメソッドのすべての await に従い、同時に実行される 2 つのリクエストが一つを共有することは決してありません。

await なしでトランザクションの中で開始され、それが終わった後も実行中の処理は、データベースを使うと、トランザクションの外で実行される代わりに IllegalTransactionStateException で失敗します。

@Transactional()
Future<void> wrong() async {
  unawaited(books.save(Book(title: 'Late')));   // トランザクションより長く生き残ると失敗する
}

リポジトリとトランザクション

リポジトリの書き込みメソッド (save、saveAll、delete*、deleteBy) は、Spring の SimpleJdbcRepository が @Transactional であるのと同じく、そのストアの required のトランザクションの中で実行されます。saveAll と子を伴う集約はアトミックで、自分のトランザクションの中ではそれに参加します。読み取りメソッドは、実行中のトランザクションに参加するか、単独で実行されます。

Spring (Java) との対応

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

違い:

関連項目