
# ロック

2 人のユーザーが同じ本を読み込み、両方が変更し、両方が保存します。ロックがなければ、2 番目の保存が最初のものを黙って上書きします。スターターは Spring Data と同じ 2 つの方法を提供します。保存時に衝突を検出する、`@Version` プロパティによる**楽観的ロック**と、トランザクションが終わるまで行を保持する、ファインダーに付ける `@Lock` による**悲観的ロック**です。

## 使う理由

- 衝突がまれなときは `@Version` を使います。ユーザーがフォームでレコードを編集し、衝突は「誰かがこれを変更しました。再読み込みしてください」と表示されます。ユーザーが考えている間、何も保持されません。
- 読み取りとそれに続く書き込みが、一つの短いトランザクションの中で交錯してはならないときは `@Lock` を使います。在庫から品物を取る、作業キュー、カウンターなどです。

## 例

```dart
@Table('stock')
class Stock {
  Stock({this.id, required this.bookId, required this.available});

  @Id()
  int? id;
  int bookId;
  int available;

  @Version()
  int version = 0;        // 保存のたびに上がる
}

abstract interface class StockRepository implements ListCrudRepository<Stock, int> {
  // FOR UPDATE: 行はトランザクションが終わるまでロックされたまま。
  @Lock(LockMode.pessimisticWrite)
  Future<Stock?> findByBookId(int bookId);

  // 作業キュー: 他のワーカーが保持する行はスキップし、最大 2 秒待つ。
  @Lock(LockMode.pessimisticWrite, timeout: Duration(seconds: 2), skipLocked: true)
  Future<List<Stock>> findTop10ByAvailableGreaterThan(int available);
}

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

  final StockRepository stock;
  final OrderRepository orders;

  @Transactional()          // @Lock のファインダーはトランザクションの中でだけ動く
  Future<void> place(int bookId) async {
    final row = (await stock.findByBookId(bookId))!;
    row.available--;
    await stock.save(row);
    await orders.save(PurchaseOrder(bookId: bookId));
  }
}
```

## @Version

- 新規のエンティティ (バージョン `0`、または nullable なバージョンなら `null`) は、バージョン `1` で挿入されます。
- 読み込んだエンティティは `... where id = ? and version = ?` で更新され、そのバージョンが上がります。一致する行がない場合 (その間に別の保存が割り込んだか、行が削除された)、`save` は `OptimisticLockingFailureException` を投げます。
- `delete(entity)` も同じ方法でバージョンをチェックします。`deleteById` はバージョンを持たないため、チェックできません。
- 集約の子 (`@MappedCollection`) はルートのバージョンでカバーされます。
- 型は `int`、`int?`、`DateTime?` です。バージョンが挿入と更新をどう決めるかは [エンティティ](entities.md) にあります。

衝突は、リトライのコードが捕まえる型である `ConcurrencyFailureException` です。Web アプリケーションでは 409 で応答されます ([Web アプリケーションで](web.md) を参照)。

```dart
try {
  await books.save(edited);
} on OptimisticLockingFailureException {
  // 読み込んだ後に誰かが本を保存した: 再読み込みしてユーザーに示す
}
```

## @Lock

| 属性 | デフォルト | 意味 |
|---|---|---|
| `value` | (必須) | `LockMode.pessimisticWrite` (排他的、`FOR UPDATE`) または `LockMode.pessimisticRead` (共有、`FOR SHARE`: 他者は読めるが変更はできない)。 |
| `timeout` | `null` | ロックを待つ最長時間。ストアのデフォルトには `null`、即座に失敗させるには `Duration.zero` (`NOWAIT`)。 |
| `skipLocked` | `false` | 別のトランザクションが保持する行を除外する (`SKIP LOCKED`)。作業キュー向け。 |

- `@Lock` は派生の `find` メソッドと `findById` に適用されます。`@Query` メソッドに付けるとビルドエラーです。
- **トランザクションの中でだけ。** そのストアのトランザクションの外で呼ばれた `@Lock` メソッドは、即座に `IllegalTransactionStateException` で失敗します。ロックなしで動くことは決してありません。(Spring はそれをオートコミットで実行し、ロックはすぐに解放されます。)
- 得られないロックは `CannotAcquireLockException` を投げます。

## 各ストアのロックの方法

| | PostgreSQL | SQLite | メモリ上 |
|---|---|---|---|
| 粒度 | 行 | データベース全体 | 行 |
| `pessimisticWrite` | `FOR UPDATE` | `BEGIN IMMEDIATE` | 排他的な行ロック |
| `pessimisticRead` | `FOR SHARE` | `BEGIN IMMEDIATE` | 共有の行ロック |
| `timeout: Duration.zero` | `NOWAIT` | 無視される: ビジータイムアウトが適用される | 即座に失敗する |
| より長い `timeout` | クエリの前に `SET LOCAL lock_timeout` | 無視される: ビジータイムアウトが適用される | 指定した待機 |
| デフォルトの待機 | サーバーのもの | `spring.datasource.sqlite.busy-timeout` (5000 ms) | `spring.data.memory.lock-timeout` (10s) |
| `skipLocked` | `SKIP LOCKED` (ゼロのタイムアウトより優先される) | 無視される (データベース全体が保持される) | 保持されている行をスキップする |
| デッドロック | `DeadlockLoserDataAccessException` (`40P01`) | | 検出される |

- SQLite には行ロックがありません。`@Lock` のクエリはトランザクションの開始時にデータベースの書き込みロックを取るため、そのトランザクションの最初の文でなければなりません。PostgreSQL にはそうしたルールはありません。
- メモリ上のストアは独自の行ロック (デッドロック検出付きの read committed) を持ち、リポジトリのストアのトランザクションがそれを保持します。

## Spring (Java) との対応

```java
@Lock(LockMode.PESSIMISTIC_WRITE)
Optional<Stock> findByBookId(long bookId);
```

`timeout` と `skipLocked` はここでの拡張です。Spring はクエリのヒントでそれらを設定します。トランザクションの外での `@Lock` のクエリは、ここではエラーです。

## 関連項目

- [トランザクション](transactions.md)
- [エラー](errors.md)
- [エンティティ](entities.md)
