SqlError.ts

SqlError.ts overview

Defines structured failures for SQL clients and driver integrations.

SqlError wraps the different reasons a SQL operation can fail, such as connection, authentication, authorization, syntax, constraint, or transaction problems. Each reason keeps the original cause, optional message and operation metadata, and whether retrying may succeed. This module also includes schemas, guards, a SQLite error classifier, and the ResultLengthMismatch error used by ordered batched SQL resolvers.

Since v4.0.0

---

Exports Grouped by Category

• converting
  • classifySqliteError
• errors
  • AuthenticationError (class)
    • [ReasonTypeId] (property)
  • AuthorizationError (class)
    • [ReasonTypeId] (property)
  • ConnectionError (class)
    • [ReasonTypeId] (property)
  • ConstraintError (class)
    • [ReasonTypeId] (property)
  • DeadlockError (class)
    • [ReasonTypeId] (property)
  • LockTimeoutError (class)
    • [ReasonTypeId] (property)
  • ResultLengthMismatch (class)
  • SerializationError (class)
    • [ReasonTypeId] (property)
  • SqlError (class)
    • [TypeId] (property)
    • cause (property)
  • SqlErrorReason (type alias)
  • SqlSyntaxError (class)
    • [ReasonTypeId] (property)
  • StatementTimeoutError (class)
    • [ReasonTypeId] (property)
  • UniqueViolation (class)
    • [ReasonTypeId] (property)
  • UnknownError (class)
    • [ReasonTypeId] (property)
• guards
  • isSqlError
  • isSqlErrorReason
• schemas
  • SqlErrorReason

---

converting

classifySqliteError

Classifies a native SQLite error cause into a SqlErrorReason using its code or errno, with optional message and operation metadata.

Signature

declare const classifySqliteError: (cause: unknown, { message, operation }?: SqliteClassifyOptions) => SqlErrorReason

Source

Since v4.0.0

errors

AuthenticationError (class)

SQL error reason for authentication failures such as invalid credentials; not marked retryable.

Signature

declare class AuthenticationError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

AuthorizationError (class)

SQL error reason for authorization or permission failures; not marked retryable.

Signature

declare class AuthorizationError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

ConnectionError (class)

SQL error reason for connection or open failures; marked retryable.

Signature

declare class ConnectionError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

ConstraintError (class)

SQL error reason for a non-unique constraint violation; not marked retryable.

Signature

declare class ConstraintError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

DeadlockError (class)

SQL error reason for a database deadlock; marked retryable.

Signature

declare class DeadlockError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

LockTimeoutError (class)

SQL error reason for timing out while waiting on a database lock; marked retryable.

Signature

declare class LockTimeoutError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

ResultLengthMismatch (class)

Error raised when an ordered batched SQL resolver receives a different number of result rows than requests.

Signature

declare class ResultLengthMismatch

Source

Since v4.0.0

SerializationError (class)

SQL error reason for a transaction serialization or isolation conflict; marked retryable.

Signature

declare class SerializationError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

SqlError (class)

Error wrapper for SQL failures whose message, cause, and isRetryable values are derived from its SqlErrorReason.

Signature

declare class SqlError

Source

Since v4.0.0

[TypeId] (property)

Marks this value as the top-level SQL error wrapper for runtime guards.

Signature

readonly [TypeId]: "~effect/sql/SqlError"

Source

Since v4.0.0

cause (property)

Exposes the structured SQL reason as the JavaScript error cause.

Signature

readonly cause: ConnectionError | AuthenticationError | AuthorizationError | SqlSyntaxError | UniqueViolation | ConstraintError | DeadlockError | SerializationError | LockTimeoutError | StatementTimeoutError | UnknownError

Source

Since v4.0.0

SqlErrorReason (type alias)

Union of structured SQL error reasons, each carrying the original cause plus optional message and operation metadata.

Signature

type SqlErrorReason =
  | ConnectionError
  | AuthenticationError
  | AuthorizationError
  | SqlSyntaxError
  | UniqueViolation
  | ConstraintError
  | DeadlockError
  | SerializationError
  | LockTimeoutError
  | StatementTimeoutError
  | UnknownError

Source

Since v4.0.0

SqlSyntaxError (class)

SQL error reason for invalid SQL syntax; not marked retryable.

Signature

declare class SqlSyntaxError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

StatementTimeoutError (class)

SQL error reason for a statement or query timeout; marked retryable.

Signature

declare class StatementTimeoutError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

UniqueViolation (class)

SQL error reason for a unique constraint violation, including the violated constraint identifier; not marked retryable.

Signature

declare class UniqueViolation

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

UnknownError (class)

SQL error reason for an unclassified database failure; not marked retryable.

Signature

declare class UnknownError

Source

Since v4.0.0

[ReasonTypeId] (property)

Marks this value as a structured SQL error reason for runtime guards.

Signature

readonly [ReasonTypeId]: "~effect/sql/SqlError/Reason"

Source

Since v4.0.0

guards

isSqlError

Returns true when a value is a SqlError.

Signature

declare const isSqlError: (u: unknown) => u is SqlError

Source

Since v4.0.0

isSqlErrorReason

Returns true when a value is a SqlErrorReason.

Signature

declare const isSqlErrorReason: (u: unknown) => u is SqlErrorReason

Source

Since v4.0.0

schemas

SqlErrorReason

Schema for encoding and decoding SQL error reasons.

Signature

declare const SqlErrorReason: Schema.Union<
  [
    typeof ConnectionError,
    typeof AuthenticationError,
    typeof AuthorizationError,
    typeof SqlSyntaxError,
    typeof UniqueViolation,
    typeof ConstraintError,
    typeof DeadlockError,
    typeof SerializationError,
    typeof LockTimeoutError,
    typeof StatementTimeoutError,
    typeof UnknownError
  ]
>

Source

Since v4.0.0