GitHub

API reference for error.

The errors of SQL clients (Effect's effect/sql/SqlError).

Every database failure is one SqlError whose reason says what kind of failure it was; match a reason with catch_reason::

insert.pipe(
    fx.catch_reason(SqlError, UniqueViolation, lambda reason, _e: fx.succeed(None))
)

Each reason carries the driver's cause, an optional message and the operation that failed, and says whether retrying can help (is_retryable). The classes are schema classes, so an SqlError encodes to JSON and back; a cause that is an exception is written as {"name", "message"} and read back as that mapping.

classify_sqlite_error turns an SQLite error (a sqlite3.Error, or any value with Node's code / errno / constraint / message properties) into its reason.

Values

AttributeTypeDescription
SQL_ERROR_REASONUnionSchema[ConnectionError | AuthenticationError | AuthorizationError | SqlSyntaxError | UniqueViolation | ConstraintError | DeadlockError | SerializationError | LockTimeoutError | StatementTimeoutError | UnknownError, Mapping[str, object], Never, Never]

The schema of every reason (Effect's SqlErrorReason schema).

Types

TypeDefinitionDescription
SqlErrorReasontype SqlErrorReason = ConnectionError | AuthenticationError | AuthorizationError | SqlSyntaxError | UniqueViolation | ConstraintError | DeadlockError | SerializationError | LockTimeoutError | StatementTimeoutError | UnknownError

Classes

Functions

is_sql_error

is_sql_error(u) -> TypeIs[SqlError]
ParameterTypeDescription
uobject

Returns TypeIs[SqlError]

def is_sql_error(u: object) -> TypeIs[SqlError]:
    return isinstance(u, SqlError)

is_sql_error_reason

is_sql_error_reason(u) -> TypeIs[SqlErrorReason]
ParameterTypeDescription
uobject

Returns TypeIs[SqlErrorReason]

def is_sql_error_reason(u: object) -> TypeIs[SqlErrorReason]:
    return isinstance(u, _Reason)

classify_sqlite_error

classify_sqlite_error(cause, *, message=None, operation=None) -> SqlErrorReason

The reason for an SQLite failure, from its result code: the name ("SQLITE_BUSY", ...) when there is one, else the number (extended codes are reduced to their primary code). A unique violation reads its constraint from constraint or the message.

ParameterTypeDescription
causeobject
messagestr | None = None
operationstr | None = None

Returns SqlErrorReason

def classify_sqlite_error(
    cause: object, *, message: str | None = None, operation: str | None = None
) -> SqlErrorReason:
    """The reason for an SQLite failure, from its result code: the name
    (``"SQLITE_BUSY"``, ...) when there is one, else the number (extended
    codes are reduced to their primary code). A unique violation reads its
    constraint from ``constraint`` or the message."""
    code = _code(cause)
    if code == _SQLITE_CONSTRAINT_UNIQUE or _matches_numeric(cause, _SQLITE_CONSTRAINT_UNIQUE_CODE):
        return UniqueViolation(
            cause=cause, message=message, operation=operation, constraint=_unique_constraint(cause)
        )
    if isinstance(code, str):
        for prefixes, reason in _BY_CODE:
            if any(_matches_code(code, prefix) for prefix in prefixes):
                return reason(cause=cause, message=message, operation=operation)
    numeric = _numeric_code(cause)
    if numeric is not None:
        reason = _BY_PRIMARY_CODE.get(numeric & 0xFF, UnknownError)
        return reason(cause=cause, message=message, operation=operation)
    return UnknownError(cause=cause, message=message, operation=operation)