SqlConnection unstable

Low-level SQL connection contract used by driver integrations.

A Connection is the driver-facing layer under SqlClient. It executes already-compiled SQL with positional parameters and can return transformed rows, raw driver results, streams, value arrays, or unprepared statement results. This module also defines the scoped connection acquirer type, the connection service tag, and the generic row shape.

5 exports Since v4.0.0 Source

Models

Acquirer

type unstable

Since v4.0.0

Scoped effect that acquires a Connection, may fail with SqlError, and requires a Scope for release.

Signature

type Acquirer = Effect<Connection, SqlError, Scope>

Borrower

type unstable

Since v4.0.0

Lends a connection for the duration of one effect and takes it back on any exit, without the caller opening a scope for it.

Details

A client that can do this offers it alongside its Acquirer, for statements that finish with the effect that runs them. Long-lived work such as stream still goes through the Acquirer, whose lease has to outlive the effect that starts it.

Signature

type Borrower = <A, E, R>(f: (connection: Connection) => Effect<A, E, R>) => Effect<A, E | SqlError, R>

Connection

interface unstable

Since v4.0.0

Low-level SQL driver connection capable of executing compiled SQL as transformed rows, raw results, streams, value arrays, or unprepared statements.

Signature

interface Connection {
  readonly execute: (sql: string, params: readonly Array<unknown>, transformRows: <A extends object>(row: readonly Array<A>) => readonly Array<A> | undefined) => Effect<readonly Array<any>, SqlError>;
  readonly executeRaw: (sql: string, params: readonly Array<unknown>) => Effect<unknown, SqlError>;
  readonly executeStream: (sql: string, params: readonly Array<unknown>, transformRows: <A extends object>(row: readonly Array<A>) => readonly Array<A> | undefined) => Stream<any, SqlError>;
  readonly executeUnprepared: (sql: string, params: readonly Array<unknown>, transformRows: <A extends object>(row: readonly Array<A>) => readonly Array<A> | undefined) => Effect<readonly Array<any>, SqlError>;
  readonly executeValues: (sql: string, params: readonly Array<unknown>) => Effect<readonly Array<readonly Array<unknown>>, SqlError>;
  readonly executeValuesUnprepared: (sql: string, params: readonly Array<unknown>) => Effect<readonly Array<readonly Array<unknown>>, SqlError>;
}

Row

type unstable

Since v4.0.0

Generic SQL row shape mapping column names to unknown values.

Signature

type Row = {
  [column: string]: unknown;
}

Services

Connection

unstable

Since v4.0.0

Service tag for a low-level SQL Connection.

Signature

declare const Connection: Service<Connection, Connection>