SqlClient unstable

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

Constructors

make

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

Details

Both acquirers lease the connection into the current scope and hold the semaphore until that scope closes. The borrower holds the same semaphore until the statement finishes without creating a scope. Another fiber cannot begin a transaction underneath either. Effects that use the connection directly, such as an export, have to run inside Effect.scoped.

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 or borrow 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, Scope>;
  readonly borrower: Borrower;
  readonly onCommitFailure: (conn: Connection) => Effect<void, SqlError>;
  readonly transactionAcquirer: Effect<C, SqlError, Scope>;
}

Models

SqlClient

interface unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

Signature

interface TransactionConnection {
  readonly _: typeof _;
}

Other

SqlClient

unstable

Since v4.0.0

Namespace containing types associated with the SqlClient service.

TransactionConnection

unstable

Since v4.0.0

Namespace containing types associated with transaction connection services.

Services

SafeIntegers

unstable

Since v4.0.0

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

Signature

declare const SafeIntegers: Reference<boolean>

SqlClient

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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>