Skip to content

5.18.0 — 2026-10-20

← 5.18.1 | 5.17.0 → | ↑ 5.x series

Added

Models - Errors

  • Resource Exhausted Error - Added DatabaseResourceExhaustedError for a database server that runs out of memory or connections.
    • HTTP status 503 and gRPC status RESOURCE_EXHAUSTED
  • Unknown Outcome Error - Added DatabaseUnknownOutcomeError for PostgreSQL 40003 (statement_completion_unknown), where the statement may or may not have completed.
  • Retryable Flag - Added the retryable class attribute to DatabaseError, False by default.
    • True on DatabaseSerializationError, DatabaseDeadlockError and DatabaseResourceExhaustedError

Changed

Adapters - SQLAlchemy

  • Driver Error Classification - Database errors are now classified by the driver error code before the message text.
    • Added archipy/adapters/base/sqlalchemy/driver_errors.py, used by the adapter mixin and the atomic decorators
    • Reads PostgreSQL SQLSTATE, MySQL and StarRocks errno, and SQLite error names
    • Falls back to DBAPIError.connection_invalidated for a disconnect with no usable code
    • StarRocks memory-limit errors reported under errno 1064 are matched by message, except syntax errors
    • The message fallback is unchanged for drivers that expose no code
  • Driver Error Logging - The driver code, message, detail, constraint and table are logged once where the domain error is raised.
    • Serialization failures, deadlocks and resource exhaustion log at WARNING, everything else at ERROR
    • Fields follow the OpenTelemetry names db.response.status_code, error.type and db.query.text
    • The statement is logged only at DEBUG, with string and numeric literals replaced by ?
    • Bind parameters are never logged, and no driver detail is added to additional_data
  • Atomic Block Errors - Raw SQLAlchemy errors in the atomic block are classified by code, where every OperationalError used to become DatabaseConnectionError.

Models - Errors

  • Catchable as Query Error - DatabaseConnectionError, DatabaseTimeoutError, DatabaseConstraintError, DatabaseIntegrityError, DatabaseDeadlockError, DatabaseSerializationError, DatabaseResourceExhaustedError and DatabaseUnknownOutcomeError now extend DatabaseQueryError.
    • Existing except DatabaseQueryError blocks keep catching errors that the classification now reports under a specific class
    • A DatabaseQueryError handler placed before a more specific handler now shadows it

Helpers - Errors

  • Captured Exception Log - capture_exception now logs the exception type and message.

Fixed

Adapters - SQLAlchemy

  • Serialization and Deadlock Mapping - A PostgreSQL 40001 or 40P01 raised by an adapter method now maps to DatabaseSerializationError or DatabaseDeadlockError instead of DatabaseQueryError.
    • The mapping in atomic.py was never reached for errors raised inside adapter methods
    • HTTP status changes from 500 to 409 and gRPC status from INTERNAL to ABORTED

Tests

Tests - Models

  • Database Error Classification - Added features/database_error_classification.feature.
    • PostgreSQL, MySQL, StarRocks and SQLite codes, the asyncpg __cause__ case, disconnect flag, handler output and log level
    • DatabaseQueryError inheritance, retryable flags and statement sanitizing