GizStack
View .mdOpen in ChatGPTOpen in Claude

gizmodel/error

Typed failures shared by database owners; protocol spelling lives in sql/errors.giz.

gizlang
import * as Error from "gizmodel/error";

Types

QueryErrorKind

gizlang
type QueryErrorKind = | { kind: "invalid_role_grant"; } | { kind: "invalid_window"; } | { kind: "bad_copy"; } | { kind: "active_transaction"; } | { kind: "duplicate_routine"; } | { kind: "invalid_definition"; } | { kind: "stack_depth"; } | { kind: "missing_return"; } | { kind: "constant_assignment"; } | { kind: "case_missing"; } | { kind: "invalid_parameter"; } | { kind: "no_data"; } | { kind: "too_many_rows"; } | { kind: "transaction_termination"; } | { kind: "invalid_rethrow"; }

Query-only causes keep their semantic identity without expanding the outer tag mask.

  • invalid_role_grant
  • invalid_window
  • bad_copy
  • active_transaction
  • duplicate_routine
  • invalid_definition
  • stack_depth
  • missing_return
  • constant_assignment
  • case_missing
  • invalid_parameter
  • no_data
  • too_many_rows
  • transaction_termination
  • invalid_rethrow

ErrorKind

gizlang
type ErrorKind = | { kind: "state"; } | { kind: "aborted"; } | { kind: "blocked"; } | { kind: "check"; } | { kind: "conflict"; } | { kind: "corrupt"; } | { kind: "deadlock"; } | { kind: "dependent"; } | { kind: "exists"; } | { kind: "foreign"; } | { kind: "format"; } | { kind: "internal"; } | { kind: "invalid"; } | { kind: "io"; } | { kind: "limit"; } | { kind: "lock"; } | { kind: "memory"; } | { kind: "missing"; } | { kind: "missing_column"; } | { kind: "missing_portal"; } | { kind: "missing_routine"; } | { kind: "missing_statement"; } | { kind: "null"; } | { kind: "offset"; } | { kind: "protocol"; } | { kind: "schema"; } | { kind: "stopped"; } | { kind: "syntax"; } | { kind: "trimmed"; } | { kind: "type_mismatch"; } | { kind: "unique"; } | { kind: "unsupported"; } | { kind: "unavailable"; } | { kind: "division_zero"; } | { kind: "numeric_range"; } | { kind: "cardinality"; } | { kind: "invalid_text"; } | { kind: "string_length"; } | { kind: "datetime"; } | { kind: "date_day"; } | { kind: "date_month"; } | { kind: "foreign_referenced"; } | { kind: "sequence_not_allowed"; } | { kind: "sequence_missing"; } | { kind: "sequence_currval"; } | { kind: "sequence_bound"; } | { kind: "permission"; } | { kind: "missing_object"; } | { kind: "reserved_name"; } | { kind: "duplicate_object"; } | { kind: "query"; cause: QueryErrorKind; } | { kind: "external_io"; } | { kind: "program_limit"; } | { kind: "not_ready"; } | { kind: "cancelled"; } | { kind: "missing_file"; } | { kind: "null_value"; } | { kind: "invalid_offset"; } | { kind: "sqlstate"; state: string; } | { kind: "application"; number: i64; } | { kind: "exception"; name: string; } | { kind: "kafka"; number: i64; }

The kind of a database error, from which its SQLSTATE and its class come.

  • state
  • aborted
  • blocked
  • check
  • conflict
  • corrupt
  • deadlock
  • dependent
  • exists
  • foreign
  • format
  • internal
  • invalid
  • io
  • limit
  • lock
  • memory
  • missing
  • missing_column
  • missing_portal
  • missing_routine
  • missing_statement
  • null
  • offset
  • protocol
  • schema
  • stopped
  • syntax
  • trimmed
  • type_mismatch
  • unique
  • unsupported
  • unavailable
  • division_zero
  • numeric_range
  • cardinality
  • invalid_text
  • string_length
  • datetime
  • date_day
  • date_month
  • foreign_referenced
  • sequence_not_allowed
  • sequence_missing
  • sequence_currval
  • sequence_bound
  • permission
  • missing_object
  • reserved_name
  • duplicate_object
  • query
  • external_io
  • program_limit
  • not_ready
  • cancelled
  • missing_file
  • null_value
  • invalid_offset
  • sqlstate
  • application
  • exception
  • kafka

FailureContext

gizlang
type FailureContext = { stage: string; declaration: string; field: string; expected: string; actual: string; capability: string; permission: string; }

Where an error happened: the stage, the declaration and field, and what was expected and found.

  • stage: string
  • declaration: string
  • field: string
  • expected: string
  • actual: string
  • capability: string
  • permission: string

DbError

gizlang
type DbError = { code: ErrorKind; message: string; nativeCode: i64; context: Vec<FailureContext>; }

A database error: its kind, message, the code of the native engine that raised it, and where it happened.

  • code: M129.ErrorKind
  • message: string
  • nativeCode: i64
  • context: Vec<M129.FailureContext>

Diagnostic

gizlang
type Diagnostic = { error: DbError; stage: string; declaration: string; field: string; expected: string; actual: string; capabilities: Vec<string>; retry: string; permission: string; approval: bool; affected: Vec<string>; fixes: Vec<string>; }

Context is attached at a boundary; semantic error classification stays here.

  • error: M129.DbError
  • stage: string
  • declaration: string
  • field: string
  • expected: string
  • actual: string
  • capabilities: Vec<string>
  • retry: string
  • permission: string
  • approval: bool
  • affected: Vec<string>
  • fixes: Vec<string>

ErrorInfo

gizlang
type ErrorInfo = { kind: string; state: string; number: i64; name: string; }

The class, SQLSTATE, number and name of an error, as each protocol reports it.

  • kind: string
  • state: string
  • number: i64
  • name: string

Functions

diagnostic

gizlang
function diagnostic(error: DbError, stage: string, declaration: string): Diagnostic

ERROR as a diagnostic of STAGE and DECLARATION, with the context that it carries.

Effects: fail, alloc.

dbError

gizlang
function dbError(code: ErrorKind, message: string): DbError

An error of the kind CODE with MESSAGE.

Effects: fail, alloc.

sqlFailure

gizlang
function sqlFailure(code: string, message: string): bool throws DbError

The failed result of a statement with the SQLSTATE CODE.

Effects: fail, alloc.

contextual

gizlang
function contextual(error: DbError, context: FailureContext): DbError

ERROR with CONTEXT added (at most 16).

Effects: fail, alloc.

withCleanup

gizlang
function withCleanup(error: DbError, cleanup: string): DbError

A failure whose cleanup also failed keeps its class and native cause; the message names both.

Effects: fail, alloc.

ioError

gizlang
function ioError(error: IoError): DbError

One database boundary preserves resource refusal, stale ownership and I/O causes.

Effects: fail, read, alloc.

ioFailure

gizlang
function ioFailure(action: string, error: IoError): DbError

An I/O failure of action ("open PATH"), with its native cause.

Effects: fail, read, alloc.

errorInfo

gizlang
function errorInfo(error: DbError): ErrorInfo

Exhaustive projection from typed causes; protocol text never decides a semantic failure.

semanticKind

gizlang
function semanticKind(error: DbError): string

The class of the error ("constraint", "missing", ...), as errorInfo gives it.

noRelation

gizlang
function noRelation(name: string): DbError

42P01: no relation NAME.

Effects: fail, alloc.

noColumn

gizlang
function noColumn(column: string, relation: string): DbError

42703: no column COLUMN in relation RELATION.

Effects: fail, alloc.

relationExists

gizlang
function relationExists(name: string): DbError

42P07: a relation NAME is there already.

Effects: fail, alloc.

errorCode

gizlang
function errorCode(error: DbError): string

Diagnostic spelling only; no decision reconstructs a kind from this text.

Effects: fail, alloc.

reasoned

gizlang
function reasoned(code: ErrorKind, reason: i64, message: string): DbError

An error of the kind CODE with MESSAGE, for REASON (above).

Effects: fail, alloc.

hasReason

gizlang
function hasReason(error: DbError, reason: i64): bool

Whether ERROR is for REASON.

hashSpilled

gizlang
function hashSpilled(error: DbError): bool

Whether ERROR is a hash past its state, a group key of an unplanned type included.

Effects: fail.

memoryError

gizlang
function memoryError(message: string): DbError

A statement whose working memory or result cannot fit its grant: out of memory (SQLSTATE 53200).

Effects: fail, alloc.

statementFault

gizlang
function statementFault(code: i64): DbError

The error of a statement whose task ended with runtime fault CODE (Task.join): 11 is the memory limit (R011: the process bound or the loop's budget), out of memory (53200). The statement fails alone and the server goes on.

Effects: fail, alloc.

detailed

gizlang
function detailed(code: ErrorKind, message: string, detail: string): DbError

An error with PostgreSQL's DETAIL line (the ErrorResponse D field; pg_input_error_info's detail).

Effects: fail, alloc.

errorDetail

gizlang
function errorDetail(error: DbError): string

The DETAIL line of an error, "" for none.

Effects: fail.

hinted

gizlang
function hinted(error: DbError, hint: string): DbError

An error with PostgreSQL's HINT line (the ErrorResponse H field).

Effects: fail, alloc.

errorHint

gizlang
function errorHint(error: DbError): string

The HINT line of an error, "" for none.

Effects: fail.

positioned

gizlang
function positioned(error: DbError, at: i64): DbError

An error at byte offset AT of the statement text (the ErrorResponse P field, from which psql draws its LINE).

Effects: fail, alloc.

errorPosition

gizlang
function errorPosition(error: DbError): i64

The byte offset an error names in the statement text, -1 for none.

Effects: fail.

Constants

SCAN_SPILL

gizlang
const SCAN_SPILL: i64 = -53001

The reasons that code acts on, kept in an error's nativeCode (the message is for people). The limits make a statement plan again (db/sql/select.giz Attempt.next). Messages carried these reasons as prefixes, and a caller that re-worded one lost the plan's retry. SCAN_SPILL: a scan past the memory budget.

HASH_SPILL

gizlang
const HASH_SPILL: i64 = -53002

A hash past the statement's state: the plan is made again.

UNTYPED_KEY

gizlang
const UNTYPED_KEY: i64 = -53003

A group key whose values are not of its planned type: a hash reason too.

RETAINED_SPILL

gizlang
const RETAINED_SPILL: i64 = -53004

The work a statement kept past its state.

CHUNKED_KEY_TWICE

gizlang
const CHUNKED_KEY_TWICE: i64 = -53005

A chunked load held a key twice.

COPY_UNSTREAMED

gizlang
const COPY_UNSTREAMED: i64 = -53006

A COPY input that streams only into a staged load.

TRAINING_OVER

gizlang
const TRAINING_OVER: i64 = -53007

Training data past pgml.max_training_bytes: out of memory (53200), as memoryError is.

ROW_CREDIT

gizlang
const ROW_CREDIT: i64 = -53008

Collected rows or their bytes past the statement's credit: a plain read whose few estimated rows were wide streams instead (db/sql/select.giz Conn.storedDelivery).