Skip to content

SqlError

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 Added in v4.0.0 Source

Converting

classifySqliteError

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Returns true when a value is a SqlError.

Signature

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

isSqlErrorReason

Added in v4.0.0 Source

Returns true when a value is a SqlErrorReason.

Signature

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

Schemas

SqlErrorReason

Added in v4.0.0 Source

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,
  ]
>;