GitHub

API reference for error.

SQL Server failures as SqlError reasons (the classifyError of Effect's @effect/sql-mssql MssqlClient).

A server error carries its error number (pytds's errors do); classify maps the numbers Effect knows to reasons, and any other failure to UnknownError (ConnectionError when connecting). A duplicate key (2601 / 2627) names its constraint from a constraint attribute, else from the message's unique index '...' / constraint '...'.

Functions

error_number

error_number(cause) -> int | None

The server's error number of cause, if it has one.

ParameterTypeDescription
causeobject

Returns int | None

def error_number(cause: object) -> int | None:
    """The server's error number of ``cause``, if it has one."""
    number = getattr(cause, "number", None)
    return number if type(number) is int else None

unique_constraint

unique_constraint(number, cause) -> str

The constraint a duplicate key broke: cause.constraint when it has one, else what its message names.

ParameterTypeDescription
numberint
causeobject

Returns str

def unique_constraint(number: int, cause: object) -> str:
    """The constraint a duplicate key broke: ``cause.constraint`` when it
    has one, else what its message names."""
    explicit = _normalize(getattr(cause, "constraint", None))
    if explicit != _UNKNOWN_CONSTRAINT:
        return explicit
    message = _message(cause)
    if not isinstance(message, str):
        return _UNKNOWN_CONSTRAINT
    pattern = _CONSTRAINT_NAME if number == _UNIQUE_CONSTRAINT else _INDEX_NAME
    found = pattern.search(message)
    return _UNKNOWN_CONSTRAINT if found is None else _normalize(found.group(1))

classify

classify(cause, *, message, operation, fallback='unknown') -> SqlErrorReason

The reason for a driver error (or any other cause).

ParameterTypeDescription
causeobject
messagestr
operationstr
fallbackFallback = 'unknown'

Returns SqlErrorReason

def classify(
    cause: object, *, message: str, operation: str, fallback: Fallback = "unknown"
) -> SqlErrorReason:
    """The reason for a driver error (or any other cause)."""
    number = error_number(cause)
    if number in (_UNIQUE_INDEX, _UNIQUE_CONSTRAINT):
        return UniqueViolation(
            cause=cause,
            message=message,
            operation=operation,
            constraint=unique_constraint(number, cause),
        )
    reason = None if number is None else _BY_NUMBER.get(number)
    if reason is None:
        reason = ConnectionError if fallback == "connection" else UnknownError
    return reason(cause=cause, message=message, operation=operation)

catch

catch(message, operation, fallback='unknown') -> Callable[[BaseException], SqlError]

Turns an exception into the SqlError of operation.

ParameterTypeDescription
messagestr
operationstr
fallbackFallback = 'unknown'

Returns Callable[[BaseException], SqlError]

def catch(
    message: str, operation: str, fallback: Fallback = "unknown"
) -> Callable[[BaseException], SqlError]:
    """Turns an exception into the ``SqlError`` of ``operation``."""
    return lambda cause: SqlError(
        reason=classify(cause, message=message, operation=operation, fallback=fallback)
    )