Module contention 

Database contention detection utility.

Detects transient lock-contention errors that are safe to retry. The entire transaction must be retried from BEGIN — not just the failing statement — because the database has already rolled it back.

Covered engines

• MySQL / MariaDB — InnoDB deadlock (SQLSTATE 40001). InnoDB detects deadlocks instantly and rolls back one transaction.

  “Always be prepared to re-issue a transaction if it fails due to deadlock. Deadlocks are not dangerous. Just try again.” — MySQL 8.0 Reference Manual, InnoDB Deadlocks

• PostgreSQL — serialization failure (SQLSTATE 40001) and deadlock detected (SQLSTATE 40P01).

  “Applications using this level must be prepared to retry transactions due to serialization failures.” — PostgreSQL docs, Transaction Isolation

• SQLite — SQLITE_BUSY (code 5) and SQLITE_BUSY_SNAPSHOT (code 517). SQLite supports only one writer at a time; concurrent writers receive SQLITE_BUSY when the busy_timeout expires, or SQLITE_BUSY_SNAPSHOT immediately when a WAL snapshot cannot be upgraded. See Result Codes — SQLITE_BUSY.

Backend dispatch

The caller must supply the DbBackend so that pattern matching is scoped to the correct engine, avoiding false positives from shared SQLSTATE codes (e.g., 40001 means different things in MySQL vs PostgreSQL).

This module provides detection helpers for callers that manage their own transaction lifecycle (e.g., the outbox sequencer).

Functions

is_retryable_contention

Returns true if the error is a transient lock-contention error that is safe to retry.