Errors

Every exception dbkit raises is a subclass of DatabaseError, normalized from the underlying driver/SQLAlchemy exception via SQLSTATE-first classification (see docs/requirements.md §13). Bound parameters and DSNs are never present in error messages (§29).

errors

Public re-export of the dbkit error model. See :mod:dbkit._core.errors.

DatabaseCancellationError

DatabaseCancellationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

The operation was cancelled (e.g. by asyncio task cancellation or a client timeout).

DatabaseCheckViolationError

DatabaseCheckViolationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseIntegrityError

A CHECK constraint rejected the row.

DatabaseCircuitOpenError

DatabaseCircuitOpenError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

The circuit breaker for this database/shard/role is open; the call was short-circuited.

DatabaseCommitUnknownError

DatabaseCommitUnknownError(
    message: str = "", **kwargs: Any
)

Bases: DatabaseError

Commit outcome is genuinely unknown — do not retry unless idempotent (§15).

Always marks transaction_state_unknown/connection_invalidated (§15).

DatabaseConfigurationError

DatabaseConfigurationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

Invalid or missing configuration, raised at startup before any connection is made.

DatabaseConnectionError

DatabaseConnectionError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

The connection could not be established or was lost mid-operation.

DatabaseDeadlockError

DatabaseDeadlockError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

PostgreSQL detected and broke a deadlock by aborting this transaction.

DatabaseError

DatabaseError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: Exception

Base class for every error dbkit raises (§13.1).

Attributes are populated by the classifier or by the raising call site. original holds the underlying exception for internal inspection; it is never rendered into the user-facing message.

Any keyword left None falls back to the subclass default or is left unset.

original and the routing/query context fields are for internal inspection and logging — never interpolated into the exception message itself (§13.4, §29).

with_context

with_context(
    *,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
) -> DatabaseError

Attach routing/query context discovered by an outer layer. Returns self.

to_dict

to_dict() -> dict[str, Any]

Safe, secret-free representation for logs/traces (§13.4).

DatabaseForeignKeyViolationError

DatabaseForeignKeyViolationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseIntegrityError

A foreign-key constraint rejected the row.

DatabaseIntegrityError

DatabaseIntegrityError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

Base class for constraint violations (SQLSTATE class 23).

DatabaseLockTimeoutError

DatabaseLockTimeoutError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A statement gave up waiting on a row/table lock (PostgreSQL lock_timeout).

DatabaseMappingError

DatabaseMappingError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A row could not be mapped to the requested map_to type.

DatabaseNotNullViolationError

DatabaseNotNullViolationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseIntegrityError

A NOT NULL column was given a null value.

DatabaseOverloadedError

DatabaseOverloadedError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A concurrency limiter rejected the call because its semaphore was exhausted.

DatabasePermissionError

DatabasePermissionError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

The connected role lacks the privilege required for this operation.

DatabasePoolTimeoutError

DatabasePoolTimeoutError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

No pooled connection became available before the pool checkout timeout elapsed.

DatabaseProgrammingError

DatabaseProgrammingError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

The statement itself is invalid (bad SQL, wrong types, undefined objects).

DatabaseQueryTimeoutError

DatabaseQueryTimeoutError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A single statement exceeded its query timeout.

DatabaseReadOnlyError

DatabaseReadOnlyError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A write was attempted against a read-only transaction or replica target.

DatabaseResultError

DatabaseResultError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A cardinality expectation (exactly-one / at-most-one / scalar) was violated.

DatabaseRoutingError

DatabaseRoutingError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A shard/replica/target could not be resolved (e.g. an unmapped shard key).

DatabaseSerializationError

DatabaseSerializationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A SERIALIZABLE/REPEATABLE READ transaction failed to serialize; safe to retry.

DatabaseSyntaxError

DatabaseSyntaxError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseProgrammingError

The statement failed to parse.

DatabaseTransactionError

DatabaseTransactionError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

A transaction-lifecycle operation (begin/commit/rollback/savepoint) failed.

DatabaseUnavailableError

DatabaseUnavailableError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

The database is reachable but not currently able to serve requests.

DatabaseUniqueViolationError

DatabaseUniqueViolationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseIntegrityError

A unique/primary-key constraint rejected the row.

DatabaseUnsupportedOperationError

DatabaseUnsupportedOperationError(
    message: str = "",
    *,
    code: str | None = None,
    category: ErrorCategory | None = None,
    retryable: bool | None = None,
    connection_invalidated: bool = False,
    transaction_state_unknown: bool = False,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
    query_name: str | None = None,
    sqlstate: str | None = None,
    original: BaseException | None = None,
)

Bases: DatabaseError

The requested operation isn't supported by the current dialect/driver/configuration.

ErrorCategory

Bases: Enum

Coarse grouping used for metrics labels and retry/circuit-breaker decisions.

classify

classify(
    exc: BaseException,
    *,
    query_name: str | None = None,
    database_name: str | None = None,
    shard_id: str | None = None,
    role: str | None = None,
) -> e.DatabaseError

Normalize any exception into a :class:DatabaseError with context attached.

is_connection_error

is_connection_error(exc: BaseException) -> bool

Whether exc indicates the connection itself is broken, not just a query failure (§15).

Used to decide whether a failure during COMMIT means the outcome is genuinely unknown (§15) — prefers SQLAlchemy's own per-dialect disconnect detection (connection_invalidated, computed by each dialect's is_disconnect() when it wraps the driver exception) over a blanket OperationalError check — OperationalError also covers many transient-but-not-disconnected conditions (e.g. some lock/resource errors), which would otherwise over-classify ordinary failures as commit-unknown.

redact_dsn

redact_dsn(value: str) -> str

Redact the password in a URL/DSN while keeping it recognizable for debugging.

redact_params

redact_params(
    params: Mapping[str, Any] | None,
    *,
    sensitive: set[str] | None = None,
) -> dict[str, Any]

Return a copy of params with sensitive values replaced by ***.

A key is redacted if it is named in sensitive (from Query.sensitive_parameters) or if it matches a built-in secret-ish hint.

sanitize_message

sanitize_message(message: str) -> str

Strip DSN passwords out of a free-form error/driver message.

error_class_for_sqlstate

error_class_for_sqlstate(
    sqlstate: str | None,
) -> type[e.DatabaseError] | None

Return the dbkit error class for a SQLSTATE, or None if unrecognized.