cquill/error

Types

AdapterError

Unified error type for all adapter operations. Adapters should map their internal errors to these types.

pub type AdapterError {
  NotFound
  TooManyRows(expected: Int, got: Int)
  ConnectionFailed(reason: String)
  ConnectionTimeout
  PoolExhausted
  ConnectionLost(reason: String)
  QueryFailed(message: String, code: option.Option(String))
  DecodeFailed(
    row: Int,
    column: String,
    expected: String,
    got: String,
  )
  Timeout
  UniqueViolation(constraint: String, detail: String)
  ForeignKeyViolation(constraint: String, detail: String)
  CheckViolation(constraint: String, detail: String)
  NotNullViolation(column: String)
  ConstraintViolation(constraint: String, detail: String)
  StaleData(expected_version: String, actual_version: String)
  DataIntegrityError(message: String)
  NotSupported(operation: String)
  AdapterSpecific(code: String, message: String)
}

Constructors

```
NotFound
```
Record not found when one was expected
```
TooManyRows(expected: Int, got: Int)
```
Too many rows returned when expecting one
```
ConnectionFailed(reason: String)
```
Failed to establish database connection
```
ConnectionTimeout
```
Connection attempt timed out
```
PoolExhausted
```
Connection pool exhausted (all connections in use)
```
ConnectionLost(reason: String)
```
Connection lost during operation

QueryFailed(message: String, code: option.Option(String))

Query execution failed (syntax error, invalid query, etc.)

DecodeFailed(
  row: Int,
  column: String,
  expected: String,
  got: String,
)

Failed to decode a result row

```
Timeout
```
Operation timed out

UniqueViolation(constraint: String, detail: String)

Unique constraint violated

ForeignKeyViolation(constraint: String, detail: String)

Foreign key constraint violated

CheckViolation(constraint: String, detail: String)

Check constraint violated

```
NotNullViolation(column: String)
```
NOT NULL constraint violated
```
ConstraintViolation(constraint: String, detail: String)
```
Generic constraint violation (when type cannot be determined)
```
StaleData(expected_version: String, actual_version: String)
```
Optimistic locking conflict - record was modified by another process
```
DataIntegrityError(message: String)
```
Data integrity error (invalid data state)
```
NotSupported(operation: String)
```
Adapter does not support this operation

AdapterSpecific(code: String, message: String)

Generic error for adapter-specific failures

SavepointError

</>

Savepoint-specific error wrapper for partial rollback operations

pub type SavepointError(e) {
  SavepointNotFound(name: String)
  SavepointAdapterError(AdapterError)
  SavepointUserError(e)
  SavepointCreationFailed(reason: String)
  SavepointReleaseFailed(reason: String)
  SavepointNoTransaction
}

Constructors

```
SavepointNotFound(name: String)
```
Savepoint with the given name was not found
```
SavepointAdapterError(AdapterError)
```
Error from the adapter/database during savepoint operation
```
SavepointUserError(e)
```
The user-provided function returned an error
```
SavepointCreationFailed(reason: String)
```
Savepoint creation failed
```
SavepointReleaseFailed(reason: String)
```
Savepoint release failed
```
SavepointNoTransaction
```
Not in a transaction (savepoints require an active transaction)

TransactionError

</>

Transaction-specific error wrapper

pub type TransactionError(e) {
  UserError(e)
  AdapterTransactionError(AdapterError)
  BeginFailed(reason: String)
  CommitFailed(reason: String)
  RolledBack
  TransactionRollback(reason: String)
  TransactionConnectionLost
  NestedTransactionError
  TransactionTimeout
  SerializationFailure
}

Constructors

```
UserError(e)
```
The user-provided function returned an error
```
AdapterTransactionError(AdapterError)
```
Error from the adapter/database during transaction
```
BeginFailed(reason: String)
```
Transaction could not be started
```
CommitFailed(reason: String)
```
Transaction commit failed (may have been rolled back)
```
RolledBack
```
Explicit rollback was requested
```
TransactionRollback(reason: String)
```
Transaction was explicitly rolled back with a reason
```
TransactionConnectionLost
```
Connection was lost during transaction
```
NestedTransactionError
```
Nested transaction attempted (not supported)
```
TransactionTimeout
```
Transaction timed out
```
SerializationFailure
```
Serialization failure (retry may succeed) - for serializable isolation

Values

adapter_specific

</>

pub fn adapter_specific(
  code: String,
  message: String,
) -> AdapterError

Create an AdapterSpecific error

connection_failed

</>

pub fn connection_failed(reason: String) -> AdapterError

Create a ConnectionFailed error

format_error

</>

pub fn format_error(error: AdapterError) -> String

Format an error for display

format_savepoint_error

</>

pub fn format_savepoint_error(error: SavepointError(e)) -> String

Format a savepoint error for display

format_transaction_error

</>

pub fn format_transaction_error(
  error: TransactionError(e),
) -> String

Format a transaction error for display

from_mysql_error

</>

pub fn from_mysql_error(
  code: Int,
  message: String,
) -> AdapterError

Map a MySQL error code to an AdapterError.

Common MySQL error codes:

1062: Duplicate entry (unique violation)
1452: Foreign key constraint fails
1364: No default value (not null violation)
1048: Column cannot be null
2002: Connection refused
2003: Can’t connect to server
2006: Server has gone away
2013: Lost connection during query

from_postgres_error

</>

pub fn from_postgres_error(
  code: String,
  message: String,
  detail: String,
) -> AdapterError

Map a PostgreSQL error code to an AdapterError.

PostgreSQL error codes are 5-character strings where the first two characters indicate the error class. See: https://www.postgresql.org/docs/current/errcodes-appendix.html

Common codes:

23505: unique_violation
23503: foreign_key_violation
23514: check_violation
23502: not_null_violation
23000: integrity_constraint_violation
08000: connection_exception
08003: connection_does_not_exist
08006: connection_failure
57P01: admin_shutdown
42P01: undefined_table
42703: undefined_column

from_sqlite_error

</>

pub fn from_sqlite_error(
  code: Int,
  message: String,
) -> AdapterError

Map a SQLite error code to an AdapterError.

SQLite uses integer result codes. Extended result codes provide more detail. See: https://www.sqlite.org/rescode.html

is_connection_error

</>

pub fn is_connection_error(error: AdapterError) -> Bool

Check if an error is a connection-related error

is_constraint_violation

</>

pub fn is_constraint_violation(error: AdapterError) -> Bool

Check if an error is any kind of constraint violation

is_foreign_key_violation

</>

pub fn is_foreign_key_violation(error: AdapterError) -> Bool

Check if an error is a foreign key violation

is_not_found

</>

pub fn is_not_found(error: AdapterError) -> Bool

Check if an error indicates the record was not found

is_query_error

</>

pub fn is_query_error(error: AdapterError) -> Bool

Check if an error is a query/execution error

is_recoverable

</>

pub fn is_recoverable(error: AdapterError) -> Bool

Check if an error is recoverable (can retry)

is_unique_violation

</>

pub fn is_unique_violation(error: AdapterError) -> Bool

Check if an error is a unique constraint violation

not_found

</>

pub fn not_found() -> AdapterError

Create a NotFound error

not_supported

</>

pub fn not_supported(operation: String) -> AdapterError

Create a NotSupported error

query_failed

</>

pub fn query_failed(message: String) -> AdapterError

Create a QueryFailed error

query_failed_with_code

</>

pub fn query_failed_with_code(
  message: String,
  code: String,
) -> AdapterError

Create a QueryFailed error with code

timeout

</>

pub fn timeout() -> AdapterError

Create a Timeout error

unique_violation

</>

pub fn unique_violation(
  constraint: String,
  detail: String,
) -> AdapterError

Create a UniqueViolation error