SqlClient

Main SQL client service for tagged-template queries.

SqlClient combines the tagged-template statement constructor with connection acquisition, dialect compilation, transactions, row transforms, tracing, and reactive query helpers. Driver integrations build this service from their connection and compiler pieces.

10 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Constructs a SqlClient from connection acquirers, a compiler, transaction commands, tracing attributes, optional row transforms, and reactive query integration.

Signature

declare const make: (...args: [options: MakeOptions]) => Effect<SqlClient, never, Reactivity>

makeSqliteAcquirers

Added in v4.0.0 Source

Builds the acquirers and failed-COMMIT cleanup for a SQLite client that shares one connection through a semaphore.

Details

SQLite can keep a transaction open after COMMIT fails, for example on a deferred foreign key violation. onCommitFailure rolls it back before the connection is reused. If that ROLLBACK fails, the connection is rejected, and each acquisition retries the ROLLBACK once while holding the semaphore until it succeeds. The database is never reopened, and transactions started with a plain BEGIN are only touched after a failed cleanup.

Pass isTransaction when the driver can report whether a transaction is open. Without it, ROLLBACK always runs and SQLite's "no transaction is active" error counts as clean.

Signature

declare function makeSqliteAcquirers<C extends Connection>(options: {
  readonly connection: Effect<C, SqlError>;
  readonly isTransaction?: (conn: C) => boolean;
  readonly semaphore: Semaphore;
}): {
  readonly acquirer: Effect<C, SqlError>;
  readonly onCommitFailure: (conn: Connection) => Effect<void, SqlError>;
  readonly transactionAcquirer: Effect<C, SqlError, Scope>;
}

Models

SqlClient interface

Added in v4.0.0 Source

SQL client service interface, combining the statement constructor API with connection reservation, transaction handling, and reactive query helpers.

Signature

interface SqlClient extends Constructor {
  <A extends object = Row>(strings: TemplateStringsArray, ...args: Array<any>): Statement<A>;
  (value: string): Identifier;
  readonly "~effect/sql/SqlClient": "~effect/sql/SqlClient";
  readonly reactive: <A, E, R>(keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>, effect: Effect<A, E, R>) => Stream<A, E, R>;
  readonly reactiveMailbox: <A, E, R>(keys: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>, effect: Effect<A, E, R>) => Effect<Dequeue<A, E>, never, Scope | R>;
  readonly reserve: Effect<Connection, SqlError, Scope>;
  readonly safe: SqlClient;
  readonly transactionService: Service<TransactionConnection, Service>;
  readonly withoutTransforms: () => this;
  readonly withTransaction: <R, E, A>(self: Effect<A, E, R>) => Effect<A, SqlError | E, R>;
}

TransactionConnection interface

Added in v4.0.0 Source

Phantom identifier for the scoped transaction connection service associated with a SQL client.

Signature

interface TransactionConnection {
  readonly _: typeof _;
}

Other

SqlClient

Added in v4.0.0 Source

Namespace containing types associated with the SqlClient service.

TransactionConnection

Added in v4.0.0 Source

Namespace containing types associated with transaction connection services.

Services

SafeIntegers

Added in v4.0.0 Source

Context reference used by SQL integrations to opt in to safe integer handling; defaults to false.

Signature

declare const SafeIntegers: Reference<boolean>

SqlClient

Added in v4.0.0 Source

Service tag for the active SQL client service.

When to use

Use to access or provide the SQL client used to build statements, stream rows, reserve connections, and run transactions.

Signature

declare const SqlClient: Service<SqlClient, SqlClient>

TransactionConnection

Added in v4.0.0 Source

Creates a unique context service tag for the active transaction connection of a specific SQL client.

Signature

declare const TransactionConnection: (clientId: number) => Service<TransactionConnection, Service>

Transactions

makeWithTransaction

Added in v4.0.0 Source

Builds a transaction wrapper that begins top-level transactions, uses savepoints for nested transactions, commits on success, and rolls back on failure or interruption. Releases nested savepoints when releaseSavepoint is provided.

Signature

declare function makeWithTransaction<I, S>(options: {
  readonly acquireConnection: Effect<readonly [Closeable | undefined, S], SqlError>;
  readonly begin: (conn: NoInfer<S>) => Effect<void, SqlError>;
  readonly commit: (conn: NoInfer<S>) => Effect<void, SqlError>;
  readonly onCommitFailure?: (conn: NoInfer<S>) => Effect<void, SqlError>;
  readonly releaseSavepoint?: (conn: NoInfer<S>, id: number) => Effect<void, SqlError>;
  readonly rollback: (conn: NoInfer<S>) => Effect<void, SqlError>;
  readonly rollbackSavepoint: (conn: NoInfer<S>, id: number) => Effect<void, SqlError>;
  readonly savepoint: (conn: NoInfer<S>, id: number) => Effect<void, SqlError>;
  readonly spanAttributes: readonly Array<readonly [string, unknown]>;
  readonly transactionService: Key<I, readonly [S, number]>;
}): <R, E, A>(effect: Effect<A, E, R>) => Effect<A, SqlError | E, R>