GitHub

API reference for error.

PostgreSQL failures as SqlError reasons (Effect's @effect/sql-pg internal/sqlError).

A server error carries a SQLSTATE; classify_sql_state maps it to a reason. classify reads the SQLSTATE and constraint name of a psycopg error; a psycopg error without one (a lost or refused connection) is a ConnectionError.

Values

AttributeTypeDescription
CHANNEL_TOO_LONGLiteral['PostgreSQL channel names must not exceed 63 UTF-8 …'] = 'PostgreSQL channel names must not exceed 63 UTF-8 bytes'

Functions

classify_sql_state

classify_sql_state(code, constraint, *, cause, message, operation) -> SqlErrorReason

The reason for the SQLSTATE code; constraint names the constraint a unique violation (23505) broke.

ParameterTypeDescription
codestr | None
constraintobject
causeobject
messagestr
operationstr

Returns SqlErrorReason

def classify_sql_state(
    code: str | None, constraint: object, *, cause: object, message: str, operation: str
) -> SqlErrorReason:
    """The reason for the SQLSTATE ``code``; ``constraint`` names the
    constraint a unique violation (``23505``) broke."""
    if code is None:
        return UnknownError(cause=cause, message=message, operation=operation)
    if code == "23505":
        return UniqueViolation(
            cause=cause,
            message=message,
            operation=operation,
            constraint=_normalize_constraint(constraint),
        )
    reason = _BY_CODE.get(code) or _BY_CLASS.get(code[:2], UnknownError)
    return reason(cause=cause, message=message, operation=operation)

classify

classify(cause, *, message, operation) -> SqlErrorReason

The reason for a psycopg error (or any exception).

ParameterTypeDescription
causeBaseException
messagestr
operationstr

Returns SqlErrorReason

def classify(cause: BaseException, *, message: str, operation: str) -> SqlErrorReason:
    """The reason for a psycopg error (or any exception)."""
    import psycopg

    if not isinstance(cause, psycopg.Error):
        return UnknownError(cause=cause, message=message, operation=operation)
    code = cause.sqlstate
    if code is None and isinstance(cause, (psycopg.OperationalError, psycopg.InterfaceError)):
        if _AUTHENTICATION_FAILURE.search(str(cause)):
            return AuthenticationError(cause=cause, message=message, operation=operation)
        return ConnectionError(cause=cause, message=message, operation=operation)
    return classify_sql_state(
        code, cause.diag.constraint_name, cause=cause, message=message, operation=operation
    )

catch

catch(message, operation) -> Callable[[BaseException], SqlError]

Turns an exception into the SqlError of operation.

ParameterTypeDescription
messagestr
operationstr

Returns Callable[[BaseException], SqlError]

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

connection_error

connection_error(message, operation, cause=None) -> SqlError
ParameterTypeDescription
messagestr
operationstr
causeobject | None = None

Returns SqlError

def connection_error(message: str, operation: str, cause: object | None = None) -> SqlError:
    return SqlError(
        reason=ConnectionError(
            cause=cause if cause is not None else Exception(message),
            message=message,
            operation=operation,
        )
    )

validate_channel_name

validate_channel_name(channel, operation) -> SqlError | None

An error when channel is longer than PostgreSQL allows.

ParameterTypeDescription
channelstr
operationstr

Returns SqlError | None

def validate_channel_name(channel: str, operation: str) -> SqlError | None:
    """An error when ``channel`` is longer than PostgreSQL allows."""
    if len(channel.encode("utf-8", "surrogatepass")) <= _MAX_CHANNEL_BYTES:
        return None
    return SqlError(
        reason=UnknownError(
            cause=Exception(CHANNEL_TOO_LONG), message=CHANNEL_TOO_LONG, operation=operation
        )
    )