Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

SqlError unstable

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.

18 exports Since v4.0.0 Source

Converting

classifySqliteError

unstable
Since v4.0.0

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

Signature

declare function classifySqliteError(cause: unknown, __namedParameters: SqliteClassifyOptions): SqlErrorReason

Errors

AuthenticationError

unstable
Since v4.0.0

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

Signature

declare class AuthenticationError extends {
  readonly _tag: "AuthenticationError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "AuthenticationError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

AuthorizationError

unstable
Since v4.0.0

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

Signature

declare class AuthorizationError extends {
  readonly _tag: "AuthorizationError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "AuthorizationError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

ConnectionError

unstable
Since v4.0.0

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

Signature

declare class ConnectionError extends {
  readonly _tag: "ConnectionError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ConnectionError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

ConstraintError

unstable
Since v4.0.0

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

Signature

declare class ConstraintError extends {
  readonly _tag: "ConstraintError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ConstraintError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

DeadlockError

unstable
Since v4.0.0

SQL error reason for a database deadlock; marked retryable.

Signature

declare class DeadlockError extends {
  readonly _tag: "DeadlockError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "DeadlockError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

LockTimeoutError

unstable
Since v4.0.0

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

Signature

declare class LockTimeoutError extends {
  readonly _tag: "LockTimeoutError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "LockTimeoutError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

ResultLengthMismatch

unstable
Since v4.0.0

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

Signature

declare class ResultLengthMismatch extends {
  readonly _tag: "ResultLengthMismatch";
  readonly actual: number;
  readonly expected: number;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "ResultLengthMismatch";
    readonly actual: number;
    readonly expected: number;
  }, options?: MakeOptions]);
  message: string;
}

SerializationError

unstable
Since v4.0.0

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

Signature

declare class SerializationError extends {
  readonly _tag: "SerializationError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "SerializationError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

SqlError

unstable
Since v4.0.0

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

Signature

declare class SqlError extends {
  readonly _tag: "SqlError";
  readonly reason: ConnectionError | AuthenticationError | AuthorizationError | SqlSyntaxError | UniqueViolation | ConstraintError | DeadlockError | SerializationError | LockTimeoutError | StatementTimeoutError | UnknownError;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "SqlError";
    readonly reason: ConnectionError | AuthenticationError | AuthorizationError | SqlSyntaxError | UniqueViolation | ConstraintError | DeadlockError | SerializationError | LockTimeoutError | StatementTimeoutError | UnknownError;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError": "~effect/sql/SqlError";
  readonly cause: ConnectionError | AuthenticationError | AuthorizationError | SqlSyntaxError | UniqueViolation | ConstraintError | DeadlockError | SerializationError | LockTimeoutError | StatementTimeoutError | UnknownError;
  isRetryable: boolean;
  message: string;
}

SqlErrorReason

type unstable
Since v4.0.0

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

SqlSyntaxError

unstable
Since v4.0.0

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

Signature

declare class SqlSyntaxError extends {
  readonly _tag: "SqlSyntaxError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "SqlSyntaxError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

StatementTimeoutError

unstable
Since v4.0.0

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

Signature

declare class StatementTimeoutError extends {
  readonly _tag: "StatementTimeoutError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "StatementTimeoutError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

UniqueViolation

unstable
Since v4.0.0

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

Signature

declare class UniqueViolation extends {
  readonly _tag: "UniqueViolation";
  readonly cause: unknown;
  readonly constraint: string;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "UniqueViolation";
    readonly cause: unknown;
    readonly constraint: string;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

UnknownError

unstable
Since v4.0.0

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

Signature

declare class UnknownError extends {
  readonly _tag: "UnknownError";
  readonly cause: unknown;
  readonly message?: string;
  readonly operation?: string;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "UnknownError";
    readonly cause: unknown;
    readonly message?: string;
    readonly operation?: string;
  }, options?: MakeOptions]);
  readonly "~effect/sql/SqlError/Reason": "~effect/sql/SqlError/Reason";
  isRetryable: boolean;
}

Guards

isSqlError

unstable
Since v4.0.0

Returns true when a value is a SqlError.

Signature

declare function isSqlError(u: unknown): u is SqlError

isSqlErrorReason

unstable
Since v4.0.0

Returns true when a value is a SqlErrorReason.

Signature

declare function isSqlErrorReason(u: unknown): u is SqlErrorReason

Schemas

SqlErrorReason

unstable
Since v4.0.0

Schema for encoding and decoding SQL error reasons.

Signature

declare const SqlErrorReason: Union<[typeof ConnectionError, typeof AuthenticationError, typeof AuthorizationError, typeof SqlSyntaxError, typeof UniqueViolation, typeof ConstraintError, typeof DeadlockError]>