`postgres.sqlstate`

SQLSTATE handling: structured errors, and the codes libpq reports.

Every error a PostgreSQL server sends carries a five-character SQLSTATE code (23505, 40P01, ...) alongside a human-readable message — see https://www.postgresql.org/docs/current/errcodes-appendix.html. Mojo 1.x can only raise Error(String), so there is no field to hang the code on when an error crosses a raises boundary. Instead this module packs the code into a parseable token inside the message text ("[SQLSTATE 23505]"), and gives callers two ways back out:

PostgresError is the structured value: build one from a libpq result, call .to_error() to raise it, and keep the original struct around wherever a try/except block has an Error in hand and wants the fields back — reconstruct a PostgresError(...), or just pull the code via sqlstate_of(err).
sqlstate_of() recovers the raw code from an Error or a String even when the PostgresError itself is gone — the common case, since Mojo's except err: only ever hands back an Error.

08001 and 08006 are not real server SQLSTATEs — libpq itself reports no SQLSTATE at all for a connection that never came up or that dropped mid-use (PQerrorMessage on a failed/lost connection carries only free text). The FFI layer synthesizes SQLCLIENT_UNABLE_TO_ESTABLISH (08001) for a failed PQconnectdb and CONNECTION_FAILURE (08006) for a connection lost after it was established, mirroring the meaning class 08 has for every other client.

Structs

`PostgresError`

struct PostgresError

A PostgreSQL error, decomposed the way PQresultErrorField reports it: severity, SQLSTATE, primary message, and the optional detail/hint the server adds to explain or suggest a fix.

All fields are String and empty when the server didn't supply them. sql is not one of libpq's fields — it's the statement text the caller was executing, attached here so the formatted error is self-contained in a log line.

Implements Copyable, Movable, Writable

Fields: severity: String: ERROR, FATAL, PANIC, or a localized equivalent. Empty if unknown.; sqlstate: String: The five-character SQLSTATE code, e.g. 23505. Empty if the source of this error didn't have one (see the module docstring).; message: String: The primary human-readable message.; detail: String: An optional secondary message with more detail. Empty if absent.; hint: String: An optional suggestion of how to fix the problem. Empty if absent.; sql: String: The SQL text being executed when the error occurred. Empty if not attached.

`init`

def __init__(out self, severity: String = "", sqlstate: String = "", message: String = "", detail: String = "", hint: String = "", sql: String = "")

`format`

def format(self) -> String

Render the multi-line form this type prints and raises as.

Line one is "postgres [SQLSTATE 23505] <message>", or "postgres: <message>" when there's no SQLSTATE to report. A DETAIL: line follows if detail is set, then a HINT: line if hint is set, then a SQL: line — collapsed to one line and capped at 200 characters — if sql is set.

`str`

def __str__(self) -> String

Same as format().

`write_to`

def write_to(self, mut writer: T)

Write format() to writer — what makes String(err) and print(err) produce the formatted form.

`to_error`

def to_error(self) -> Error

Wrap format() in an Error, ready to raise.

sqlstate_of() recovers self.sqlstate back out of the raised Error on the far side of a try/except.