gizmodel/error
Typed failures shared by database owners; protocol spelling lives in sql/errors.giz.
import * as Error from "gizmodel/error";Types
QueryErrorKind
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_grantinvalid_windowbad_copyactive_transactionduplicate_routineinvalid_definitionstack_depthmissing_returnconstant_assignmentcase_missinginvalid_parameterno_datatoo_many_rowstransaction_terminationinvalid_rethrow
ErrorKind
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.
stateabortedblockedcheckconflictcorruptdeadlockdependentexistsforeignformatinternalinvalidiolimitlockmemorymissingmissing_columnmissing_portalmissing_routinemissing_statementnulloffsetprotocolschemastoppedsyntaxtrimmedtype_mismatchuniqueunsupportedunavailabledivision_zeronumeric_rangecardinalityinvalid_textstring_lengthdatetimedate_daydate_monthforeign_referencedsequence_not_allowedsequence_missingsequence_currvalsequence_boundpermissionmissing_objectreserved_nameduplicate_objectqueryexternal_ioprogram_limitnot_readycancelledmissing_filenull_valueinvalid_offsetsqlstateapplicationexceptionkafka
FailureContext
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:stringdeclaration:stringfield:stringexpected:stringactual:stringcapability:stringpermission:string
DbError
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.ErrorKindmessage:stringnativeCode:i64context:Vec<M129.FailureContext>
Diagnostic
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.DbErrorstage:stringdeclaration:stringfield:stringexpected:stringactual:stringcapabilities:Vec<string>retry:stringpermission:stringapproval:boolaffected:Vec<string>fixes:Vec<string>
ErrorInfo
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:stringstate:stringnumber:i64name:string
Functions
diagnostic
function diagnostic(error: DbError, stage: string, declaration: string): DiagnosticERROR as a diagnostic of STAGE and DECLARATION, with the context that it carries.
Effects: fail, alloc.
dbError
function dbError(code: ErrorKind, message: string): DbErrorAn error of the kind CODE with MESSAGE.
Effects: fail, alloc.
sqlFailure
function sqlFailure(code: string, message: string): bool throws DbErrorThe failed result of a statement with the SQLSTATE CODE.
Effects: fail, alloc.
contextual
function contextual(error: DbError, context: FailureContext): DbErrorERROR with CONTEXT added (at most 16).
Effects: fail, alloc.
withCleanup
function withCleanup(error: DbError, cleanup: string): DbErrorA failure whose cleanup also failed keeps its class and native cause; the message names both.
Effects: fail, alloc.
ioError
function ioError(error: IoError): DbErrorOne database boundary preserves resource refusal, stale ownership and I/O causes.
Effects: fail, read, alloc.
ioFailure
function ioFailure(action: string, error: IoError): DbErrorAn I/O failure of action ("open PATH"), with its native cause.
Effects: fail, read, alloc.
errorInfo
function errorInfo(error: DbError): ErrorInfoExhaustive projection from typed causes; protocol text never decides a semantic failure.
semanticKind
function semanticKind(error: DbError): stringThe class of the error ("constraint", "missing", ...), as errorInfo gives it.
noRelation
function noRelation(name: string): DbError42P01: no relation NAME.
Effects: fail, alloc.
noColumn
function noColumn(column: string, relation: string): DbError42703: no column COLUMN in relation RELATION.
Effects: fail, alloc.
relationExists
function relationExists(name: string): DbError42P07: a relation NAME is there already.
Effects: fail, alloc.
errorCode
function errorCode(error: DbError): stringDiagnostic spelling only; no decision reconstructs a kind from this text.
Effects: fail, alloc.
reasoned
function reasoned(code: ErrorKind, reason: i64, message: string): DbErrorAn error of the kind CODE with MESSAGE, for REASON (above).
Effects: fail, alloc.
hasReason
function hasReason(error: DbError, reason: i64): boolWhether ERROR is for REASON.
hashSpilled
function hashSpilled(error: DbError): boolWhether ERROR is a hash past its state, a group key of an unplanned type included.
Effects: fail.
memoryError
function memoryError(message: string): DbErrorA statement whose working memory or result cannot fit its grant: out of memory (SQLSTATE 53200).
Effects: fail, alloc.
statementFault
function statementFault(code: i64): DbErrorThe 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
function detailed(code: ErrorKind, message: string, detail: string): DbErrorAn error with PostgreSQL's DETAIL line (the ErrorResponse D field; pg_input_error_info's detail).
Effects: fail, alloc.
errorDetail
function errorDetail(error: DbError): stringThe DETAIL line of an error, "" for none.
Effects: fail.
hinted
function hinted(error: DbError, hint: string): DbErrorAn error with PostgreSQL's HINT line (the ErrorResponse H field).
Effects: fail, alloc.
errorHint
function errorHint(error: DbError): stringThe HINT line of an error, "" for none.
Effects: fail.
positioned
function positioned(error: DbError, at: i64): DbErrorAn error at byte offset AT of the statement text (the ErrorResponse P field, from which psql draws its LINE).
Effects: fail, alloc.
errorPosition
function errorPosition(error: DbError): i64The byte offset an error names in the statement text, -1 for none.
Effects: fail.
Constants
SCAN_SPILL
const SCAN_SPILL: i64 = -53001The 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
const HASH_SPILL: i64 = -53002A hash past the statement's state: the plan is made again.
UNTYPED_KEY
const UNTYPED_KEY: i64 = -53003A group key whose values are not of its planned type: a hash reason too.
RETAINED_SPILL
const RETAINED_SPILL: i64 = -53004The work a statement kept past its state.
CHUNKED_KEY_TWICE
const CHUNKED_KEY_TWICE: i64 = -53005A chunked load held a key twice.
COPY_UNSTREAMED
const COPY_UNSTREAMED: i64 = -53006A COPY input that streams only into a staged load.
TRAINING_OVER
const TRAINING_OVER: i64 = -53007Training data past pgml.max_training_bytes: out of memory (53200), as memoryError is.
ROW_CREDIT
const ROW_CREDIT: i64 = -53008Collected 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).