Documentation
¶
Overview ¶
Package dberrors provides typed database error classification. Repositories use Classify() to wrap raw driver errors with sentinel types. Services check IsFatal() and decide retry policy. Handlers use errors.Is() for HTTP status mapping.
Index ¶
- Variables
- func Classify(err error) error
- func HandleFatal(err error)
- func InconsistentDatatypesCount() uint64
- func IsFatal(err error) bool
- func IsRetryable(err error) bool
- func MaxOpenCursorsCount() uint64
- func SetFatalHandler(h func(error))
- func SharedPoolExhaustedCount() uint64
- func SnapshotTooOldCount() uint64
- func Wrap(err error, sentinel error) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("not found") ErrConstraint = errors.New("constraint violation") ErrTransient = errors.New("transient database error") ErrPermission = errors.New("permission denied") ErrContextDone = errors.New("context cancelled") // ErrUndefinedObject fires when a referenced schema object (table, view, or // sequence) does not exist — PostgreSQL SQLSTATE 42P01, Oracle ORA-02289 // (sequence does not exist) / ORA-00942 (table or view does not exist). It // indicates schema drift (an object dropped out from under a running // server), not a user-input error, and is NOT transient: a bare retry // without repairing the object will fail identically. Callers that can // recreate the object (e.g. reinstall a missing sequence) may use this to // trigger a repair-and-retry; otherwise it should surface as a 500. ErrUndefinedObject = errors.New("undefined database object") )
Top-level error categories
var ( ErrDuplicate = fmt.Errorf("duplicate: %w", ErrConstraint) ErrForeignKey = fmt.Errorf("foreign key: %w", ErrConstraint) // ErrAppendOnlyViolation fires when the audit_entries / version_snapshots // append-only triggers (T19, #356) reject an UPDATE or DELETE. Distinct // from a generic constraint violation because it indicates a code-correctness // bug (or operator error / hostile action), not a user input error — callers // should never expect a retry to fix this. ErrAppendOnlyViolation = fmt.Errorf("append-only violation: %w", ErrConstraint) )
Constraint sub-categories (wrap ErrConstraint so errors.Is works for both)
Functions ¶
func Classify ¶
Classify wraps a raw database error with the appropriate typed sentinel. It checks in order: context errors, GORM errors, driver-specific errors (PostgreSQL pgconn.PgError, Oracle godror.OraErr), then falls back to string matching for errors that don't carry typed driver info. SEM@bacedc2fda0d7e7c4267e5fef6abc1a24bafed1a: convert a raw database error to a typed sentinel, including no-rows cases (pure)
func HandleFatal ¶
func HandleFatal(err error)
HandleFatal logs a fatal error and terminates the calling goroutine. Called by services when they detect a fatal condition (DB permission denied, crypto failure, etc.). HandleFatal does not return to the caller.
On the first call, if a handler has been installed via SetFatalHandler, the handler runs and HandleFatal then blocks the calling goroutine indefinitely. This lets the server drain in-flight requests while keeping the corrupted caller from continuing.
If no handler is installed, or if HandleFatal has already been called once, the process exits immediately with code 1. SEM@a15ce488928229a669359dcd63fc1e9a3866e2aa: dispatch a fatal DB error to the registered handler, then block; exit immediately on re-entrant call
func InconsistentDatatypesCount ¶
func InconsistentDatatypesCount() uint64
InconsistentDatatypesCount returns the cumulative number of ORA-00932 occurrences observed since process start. Intended for operator inspection and tests: a nonzero, growing count is the signal that a server-side query is hitting a CLOB column in a context Oracle cannot evaluate (ORDER BY, GROUP BY, DISTINCT) and needs a code fix, not a retry. SEM@7bbef7cb69972ca979324137a10e8f644c604934: return the cumulative count of ORA-00932 inconsistent-datatype errors observed since process start (pure)
func IsFatal ¶
IsFatal returns true if the error indicates the server is fundamentally broken and should shut down (permission denied, invalid credentials). SEM@62c90f15b43011216f4ac7ebdd8017b8f96afcbd: report whether a database error indicates a fatal misconfiguration requiring shutdown (pure)
func IsRetryable ¶
IsRetryable returns true if the error represents a transient condition that may succeed on retry (connection errors, serialization failures, deadlocks). SEM@62c90f15b43011216f4ac7ebdd8017b8f96afcbd: report whether a database error is a transient failure safe to retry (pure)
func MaxOpenCursorsCount ¶
func MaxOpenCursorsCount() uint64
MaxOpenCursorsCount returns the cumulative number of ORA-01000 occurrences observed since process start. Intended for operator inspection and tests. SEM@7bbef7cb69972ca979324137a10e8f644c604934: return the cumulative count of ORA-01000 max-open-cursors errors observed since process start (pure)
func SetFatalHandler ¶
func SetFatalHandler(h func(error))
SetFatalHandler installs a handler invoked on the first HandleFatal call. Intended for the server to initiate graceful shutdown on fatal conditions. Subsequent HandleFatal calls bypass the handler and exit immediately. SEM@a15ce488928229a669359dcd63fc1e9a3866e2aa: register a process-level fatal-error callback for graceful shutdown (mutates shared state)
func SharedPoolExhaustedCount ¶
func SharedPoolExhaustedCount() uint64
SharedPoolExhaustedCount returns the cumulative number of ORA-04031 occurrences observed since process start. Intended for operator inspection and tests. SEM@7bbef7cb69972ca979324137a10e8f644c604934: return the cumulative count of ORA-04031 shared-pool-exhaustion errors observed since process start (pure)
func SnapshotTooOldCount ¶
func SnapshotTooOldCount() uint64
SnapshotTooOldCount returns the cumulative number of ORA-01555 occurrences observed since process start. Intended for operator inspection and tests. SEM@379ec443351a5e4c305ce61c48bfaab5ed1a5f97: return the cumulative count of ORA-01555 snapshot-too-old errors observed since process start (pure)
func Wrap ¶
Wrap wraps a raw error with a typed sentinel, preserving the original error chain. Example: Wrap(rawErr, ErrDuplicate) returns an error where:
- errors.Is(result, ErrDuplicate) == true
- errors.Is(result, ErrConstraint) == true (because ErrDuplicate wraps ErrConstraint)
- errors.Unwrap(result) chain reaches rawErr
SEM@62c90f15b43011216f4ac7ebdd8017b8f96afcbd: wrap a raw error with a typed sentinel preserving the full error chain (pure)
Types ¶
This section is empty.
Source Files