
# エラー

どのストアとドライバーも同じ例外を投げます。重複キーは、メモリ上でも、SQLite でも、PostgreSQL でも `DuplicateKeyException` です。例外は Spring の `DataAccessException` の階層に従うため、スーパータイプを捕まえるコード (リトライのための `ConcurrencyFailureException`、409 で応答するための `DataIntegrityViolationException`) は、データベースにかかわらず動きます。

## 使う理由

SQLite のエラーコード、PostgreSQL の SQL ステート、メモリ上のチェックは、同じことを 3 つの方法で表します。一つの階層に変換すれば、サービスは「このタイトルはすでにある」や「他の誰かがこの行を変更した」を一度だけ扱えばよく、メモリ上のストアでのテストは本番と同じものを投げます。

## 例

```dart
@Service()
class Authors {
  Authors(this.authors);

  final AuthorRepository authors;

  Future<Author> register(String name) async {
    try {
      return await authors.save(Author(name: name));     // name は @Unique
    } on DuplicateKeyException {
      throw NameTaken(name);
    }
  }

  // 別のトランザクションのせいで失敗したものをリトライする。
  Future<T> retrying<T>(Future<T> Function() work) async {
    for (var attempt = 1;; attempt++) {
      try {
        return await work();
      } on ConcurrencyFailureException {
        if (attempt == 3) rethrow;
      }
    }
  }
}
```

## データアクセスの例外

| 例外 | 親 | タイミング |
|---|---|---|
| `DataAccessException` | | ルート。抽象。 |
| `TransientDataAccessException` | `DataAccessException` | 再試行すれば成功するかもしれない。 |
| `NonTransientDataAccessException` | `DataAccessException` | 再び失敗する。 |
| `DataIntegrityViolationException` | non-transient | 制約: 存在しない参照先の集約、`NOT NULL`、チェック。 |
| `DuplicateKeyException` | `DataIntegrityViolationException` | 主キーまたは一意キーが使われている。 |
| `IncorrectResultSizeDataAccessException` | non-transient | 一つが期待されるところで複数の行。 |
| `EmptyResultDataAccessException` | `IncorrectResultSizeDataAccessException` | 一つが必要なところで行がない。 |
| `IncorrectUpdateSemanticsDataAccessException` | `InvalidDataAccessResourceUsageException` | 行がなくなった `@Version` のないエンティティについて、`save` がどの行も更新しなかった。 |
| `InvalidDataAccessResourceUsageException` | non-transient | リソースの誤った使用: 読み取り専用のトランザクションでの書き込み。 |
| `PermissionDeniedDataAccessException` | non-transient | 権限がない、または書き込む行を行レベルセキュリティのポリシーが拒否したために、データベースがステートメントを拒否した (PostgreSQL の `42501`)。 |
| `BadSqlGrammarException` | `InvalidDataAccessResourceUsageException` | 誤った SQL: 構文、不明なテーブルや列。 |
| `InvalidDataAccessApiUsageException` | non-transient | API の誤った使用。 |
| `InvalidDataArgumentException` | `InvalidDataAccessApiUsageException` | 呼び出し元の値の拒否: テキストの中の NUL、長すぎる `In` のリスト、データベースが拒否する `LIKE` のパターン。 |
| `PropertyReferenceException` | `InvalidDataAccessApiUsageException` | エンティティにないソートのプロパティ。 |
| `DataAccessResourceFailureException` | non-transient | データベースに到達できない: 失われた接続、認証、存在しないデータベース。 |
| `ConcurrencyFailureException` | transient | 別のトランザクションが邪魔をした: リトライする。 |
| `OptimisticLockingFailureException` | `ConcurrencyFailureException` | `@Version` の衝突。 |
| `PessimisticLockingFailureException` | `ConcurrencyFailureException` | ロックの問題。 |
| `CannotAcquireLockException` | `PessimisticLockingFailureException` | 時間内に得られなかったロック (`NOWAIT`、タイムアウト、SQLite のビジー)。 |
| `DeadlockLoserDataAccessException` | `PessimisticLockingFailureException` | デッドロックの犠牲者に選ばれた。 |
| `CannotSerializeTransactionException` | `PessimisticLockingFailureException` | `repeatableRead` や `serializable` のもとでの直列化の失敗。 |
| `QueryTimeoutException` | transient | タイムアウトを超えた文。 |
| `InvalidPagingRequestException` | `ArgumentError` | 負のページ、1 未満のサイズ、2^53 - 1 を超えるオフセット。 |
| `MappingException` | `InvalidDataAccessApiUsageException` | マッピングできないエンティティ: `@Id` も `@Version` もない、エンティティ型のフィールド、誤った `@Reference` の型。 |

メッセージはデータベースのメッセージを持ち、バインドされた値やパスワードは決して持ちません。

## トランザクションの例外

| 例外 | タイミング |
|---|---|
| `IllegalTransactionStateException` | トランザクションのない `mandatory`、トランザクションの中の `never`、トランザクションの外の `@Lock` のクエリ、トランザクションより長く生き残った処理。 |
| `UnexpectedRollbackException` | コミットが、ロールバック専用とされたトランザクションを見つけた (参加したメソッドの失敗、タイムアウト)。 |
| `TransactionSystemException` | コミットやロールバック自体が失敗した。`applicationException` はメソッドのエラーを持つ。 |
| `TransactionTimedOutException` | トランザクションがタイムアウトを超えて実行された。 |
| `CannotCreateTransactionException` | トランザクションを開始できなかった。 |
| `NestedTransactionNotSupportedException` | セーブポイントのないストアでの `nested`。 |
| `InvalidIsolationLevelException` | ストアが提供しない分離レベル。 |
| `InvalidTimeoutException` | 負のタイムアウト。 |

## スキーマの例外

| 例外 | タイミング |
|---|---|
| `SchemaException` | ルート。`NonTransientDataAccessException` の一種。 |
| `ScriptException` | `schema.sql` や `data.sql` の文が失敗した (ファイルと行)。 |
| `MigrationException` | マイグレーションが失敗した、または履歴がファイルと一致しない。 |
| `SchemaValidationException` | エンティティがテーブルに合わない (`spring.data.jdbc.schema=validate`)。 |

これらは起動を止めます。`dataFailureAnalyzer` の Bean は、これらと、どのドライバーも扱わない URL を、原因と修正方法を説明する起動時のレポートに変えます。この Bean は起動時チェックで、`spring.main.startup-checks.enabled` でビルドに含まれます。未設定ならデバッグビルドとプロファイルビルドだけなので、リリースビルドにはそのコードがなく、起動を失敗させたデータベースの例外はそのままの形で報告されます。`application.yml` または `application.properties` で `true` にするとすべてのビルドに、`false` にするとどのビルドにも含まれません。

## Web アプリケーションで

Web スターターがある場合、生成される `dataAccessExceptionResolver` は、これらの一部にステータスと固定の詳細で応答します ([Web アプリケーションで](web.md) を参照)。`OptimisticLockingFailureException` と `DuplicateKeyException` は 409、`EmptyResultDataAccessException` は 404、`PermissionDeniedDataAccessException` は 403、`PropertyReferenceException`、`InvalidPagingRequestException`、`InvalidDataArgumentException` は 400 です。それ以外は 500 です。

## Spring (Java) との対応

クラス名は Spring のもの (`org.springframework.dao`、`org.springframework.transaction`) です。違いは 2 つです。

- PostgreSQL について、スターターは Spring の PostgreSQL のエラーコードの表のより細かいクラスを保ちます。Spring 7 の `JdbcTemplate` は SQL ステートで変換します。`40001` は `CannotSerializeTransactionException`、`40P01` は `DeadlockLoserDataAccessException`、`55P03` は `CannotAcquireLockException`、`25006` は `InvalidDataAccessResourceUsageException` です。スーパータイプは同じです。
- `InvalidDataArgumentException` は追加されたもので、Web アプリケーションが呼び出し元の不正な値をプログラミングの誤りと区別できるようにします。

## 関連項目

- [ロック](locks.md)
- [トランザクション](transactions.md)
- [PostgreSQL](postgresql.md)
- [セッションフック](session-hooks.md)
