エラー

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

使う理由

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

例

@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 アプリケーションで を参照)。OptimisticLockingFailureException と DuplicateKeyException は 409、EmptyResultDataAccessException は 404、PermissionDeniedDataAccessException は 403、PropertyReferenceException、InvalidPagingRequestException、InvalidDataArgumentException は 400 です。それ以外は 500 です。

Spring (Java) との対応

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

関連項目