async_postgres/pg_errors

Search:
Group by:

Exception hierarchy.

All library-raised exceptions derive from PgError so callers can catch every pg-specific failure with a single except PgError clause. PgProtocolError is a subtype of PgConnectionError because a protocol-level violation desynchronises the wire stream — the only viable recovery is to tear down and re-establish the connection.

PgStateError is deliberately a sibling of PgConnectionError (both under PgError) rather than a subtype: it signals a programming error (e.g. a single connection used concurrently), for which reconnecting is pointless, so it must stay out of except PgConnectionError reconnect loops.

PgTimeoutError is a subtype of PgConnectionError for the opposite reason. A timed-out query/exec/copy/prepare/transaction dispatches a best-effort CancelRequest and marks the connection csClosed (the wire may be mid-exchange and is no longer trustworthy), so reconnecting is the correct recovery and the error must be visible to except PgConnectionError loops. The two timeouts that leave the connection usable — waitNotification and an acquire timeout inside withTransactionDeadline / withTransactionRetryDeadline — still raise PgTimeoutError and are therefore also caught by except PgConnectionError; a caller that needs to tell a timeout apart from a hard connection failure catches PgTimeoutError in a clause placed before the PgConnectionError one.

Types

ErrorField = object
  code*: char
  value*: string
A single field from an ErrorResponse or NoticeResponse message. 
PgConnectionError = object of PgError
Connection failures, disconnections, SSL/auth errors. 
PgError = object of CatchableError
General PostgreSQL error. Base type for all pg-specific errors. 
PgListenError = object of PgConnectionError
  reconnectionAttempted*: bool ## True if the pump attempted reconnection before giving up.
Listen pump died permanently (reconnection failed or connection lost with no channels left to re-subscribe). 
PgNoRowsError = object of PgError
Raised by single-row/single-value queries when the result set is empty. 
PgNotifyOverflowError = object of PgError
  dropped*: int              ## Number of notifications dropped due to queue overflow
PgNullError = object of PgError
Raised by single-value queries when the value is SQL NULL and the caller requested a non-nullable result. 
PgPoolError = object of PgError
Pool-level acquire failure: acquire timeout, pool closed, waiter queue full, or a failed connect attempt during acquire (the underlying error, e.g. PgConnectionError, is preserved as parent). 
PgProtocolError = object of PgConnectionError
Raised on PostgreSQL wire protocol violations. The connection stream is desynchronised after this error and must be torn down. 
PgQueryError = object of PgError
  sqlState*: string          ## 5-char SQLSTATE code (e.g. "42P01"), empty if unavailable.
  severity*: string          ## e.g. "ERROR", "FATAL"
  detail*: string            ## DETAIL field, empty if not present.
  hint*: string              ## HINT field, empty if not present.
  fields*: seq[ErrorField] ## All raw ErrorResponse fields as sent by the server, including any
                           ## not covered by the named accessors below.

SQL execution errors from the server (ErrorResponse).

The most common fields are stored directly; everything else the server sent (schema/table/column/constraint name, error position, …) is kept verbatim in fields and exposed through accessors such as constraintName and position.

PgStateError = object of PgError

Raised when an operation is attempted on a connection that is alive but in the wrong state for that operation — most commonly a single connection used concurrently: a second query started while the first is still in flight finds the connection csBusy.

This is a programming error, not a connection failure. Reconnecting does not fix it, so PgStateError is intentionally not a subtype of PgConnectionError — code that recovers via except PgConnectionError will not spin on it. The fix is to give each concurrent caller its own connection (e.g. via a PgPool).

PgTimeoutError = object of PgConnectionError

Raised when an operation times out.

A timeout on a query/exec/copy/prepare/transaction invalidates the connection: a best-effort CancelRequest is dispatched and the connection is marked csClosed because the protocol may be mid-exchange. The only viable recovery is to reconnect, so PgTimeoutError is a subtype of PgConnectionError — an except PgConnectionError reconnect loop catches it instead of silently dropping the timeout-poisoned connection.

waitNotification and an acquire timeout inside withTransactionDeadline / withTransactionRetryDeadline also raise PgTimeoutError but do not close the connection; catch PgTimeoutError before any PgConnectionError clause if you need to distinguish those.

PgTypeError = object of PgError
Raised when a PostgreSQL value cannot be converted to the requested Nim type. 
ProtocolError {....deprecated: "use PgProtocolError".} = PgProtocolError
Deprecated: use PgProtocolError
Deprecated alias for PgProtocolError, kept for backwards compatibility.

Procs

func columnName(e: ref PgQueryError): string {....raises: [], tags: [], forbids: [].}
Column the error refers to. 
func constraintName(e: ref PgQueryError): string {....raises: [], tags: [],
    forbids: [].}
Constraint the error refers to (e.g. the violated unique index). 
func dataTypeName(e: ref PgQueryError): string {....raises: [], tags: [],
    forbids: [].}
Data type the error refers to. 
func errorField(e: ref PgQueryError; code: char): string {....raises: [], tags: [],
    forbids: [].}
Raw ErrorResponse field by single-char code, "" if not present. 
func getErrorField(fields: seq[ErrorField]; code: char): string {....raises: [],
    tags: [], forbids: [].}
Get the value of an error field by its single-char code (e.g. 'M' for message). 
func internalPosition(e: ref PgQueryError): int {....raises: [], tags: [],
    forbids: [].}
Like position but for internalQuery, 0 if not reported. 
func internalQuery(e: ref PgQueryError): string {....raises: [], tags: [],
    forbids: [].}
Text of the internally-generated query that failed (e.g. inside a function). 
func isCheckViolation(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func isDeadlockDetected(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func isExclusionViolation(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func isForeignKeyViolation(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func isIntegrityConstraintViolation(e: ref PgQueryError): bool {....raises: [],
    tags: [], forbids: [].}
Any SQLSTATE in class 23 (integrity constraint violation). 
func isNotNullViolation(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func isQueryCanceled(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func isSerializationFailure(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func isUniqueViolation(e: ref PgQueryError): bool {....raises: [], tags: [],
    forbids: [].}
func position(e: ref PgQueryError): int {....raises: [], tags: [], forbids: [].}
1-based character index into the original query where the error occurred, 0 if the server did not report a position. 
func schemaName(e: ref PgQueryError): string {....raises: [], tags: [], forbids: [].}
Schema containing the object the error refers to. 
func tableName(e: ref PgQueryError): string {....raises: [], tags: [], forbids: [].}
Table the error refers to. 
func where(e: ref PgQueryError): string {....raises: [], tags: [], forbids: [].}
Context call stack (PL/pgSQL traceback etc.).

Made with Nim. Generated: 2026-06-26 11:39:17 UTC