
# トランザクション

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

## 使う理由

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

## 例

```dart
@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 メソッドに適用されます。

### 使い方のルール

- **Bean のプロキシを通して動きます。** 別の Bean からの呼び出しはトランザクションの中で実行されますが、クラスの中での `this` を通した呼び出しはそうなりません (Spring のプロキシのルール)。
- **メソッドは `Future` を返します。** トランザクションは、それが完了するまでをカバーします。同期的なメソッドや `Stream` を返すメソッドは起動を止めます。
- **すべての例外がロールバックします。** Dart にはチェック例外がないため、スターターは、Spring がチェック例外の後にするようには、どの例外の後でもコミットしません。コミットすべきものは `noRollbackFor` に列挙してください。`rollbackFor` と `noRollbackFor` の両方が一致する場合は、Spring と同じく、例外のクラスに最も近いエントリーが優先されます。ジェネレーターは、列挙した各型について型のテストと型階層での深さを書きます。

## 伝播

| 値 | トランザクションの中で | トランザクションの外で |
|---|---|---|
| `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`) |

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

- `timeout` を超えて実行されたトランザクションはロールバック専用にされ、その文はキャンセルされます。そのコミットは `UnexpectedRollbackException` を投げます。PostgreSQL では文はサーバーでキャンセルされ (`QueryTimeoutException`)、接続は使える状態のままです。
- `spring.jdbc.template.query-timeout` は、トランザクションの中でも外でも、`JdbcTemplate` の Bean の各文を制限します。
- `timeout`、`isolation`、`readOnly` は、そのメソッドで開始されるトランザクションにだけ適用されます。参加するメソッドは外側の設定を保ちます。

## TransactionTemplate

```dart
@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);
  });
}
```

- `execute(action)` は、トランザクションがコミットした後にアクションの結果を返します。`executeWithoutResult(action)` は何も返しません。
- `TransactionTemplate(manager, [definition])` は別の設定のものを作ります: `TransactionDefinition(propagation:, isolation:, timeout:, readOnly:, name:)`。
- `transactionTemplate` の Bean は、トランザクションマネージャーが一つの場合に存在します。

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

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

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

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

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

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

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

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

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

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

## Spring (Java) との対応

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

違い:

- 位置引数の `value` ではなく `transactionManager: 'x'` です。Dart では任意の位置引数と名前付き引数を混ぜられないためです。
- デフォルトでは、すべての例外がロールバックします。
- トランザクションの外での `@Lock` のクエリは、オートコミットで実行される代わりに失敗します。
- トランザクションはスレッドではなく `Zone` に結び付けられます。

## 関連項目

- [ロック](locks.md)
- [データソース](data-sources.md)
- [エラー](errors.md)
