Statement
Low-level SQL statement and fragment primitives.
SqlClient uses this module to build executable, parameterized SQL from reusable fragments. A statement can be executed, streamed, run without row transformation, or compiled to SQL text and parameters for a specific dialect. The module also contains helpers for identifiers, parameters, inserts, updates, custom dialect fragments, statement compilation, and row transformation.
Constructors
Signature
declare const and: (clauses: ReadonlyArray<string | Fragment>) => Fragment;arrayHelper
Constructs an ArrayHelper segment for an array of values or fragments.
Signature
declare function arrayHelper(value: readonly Array<unknown>): ArrayHelperCreates a comma-separated SQL fragment from values, optionally adding a prefix, and returns an empty fragment when no values are provided.
Signature
declare const csv: {
(values: readonly Array<string | Fragment>): Fragment;
(prefix: string, values: readonly Array<string | Fragment>): Fragment;
}Creates a constructor for custom SQL segments of a specific kind handled by the active compiler.
Signature
declare function custom<C extends Custom<any, any, any, any>>(
kind: C["kind"],
): (paramA: C["paramA"], paramB: C["paramB"], paramC: C["paramC"]) => C;defaultEscape
Creates an identifier escaping function that wraps names in the given delimiter, doubles delimiter characters, and escapes dots between identifier parts.
Signature
declare function defaultEscape(c: string): (str: string) => string;Constructs a SQL Fragment from low-level statement segments.
Signature
declare function fragment(segments: readonly Array<Segment>): Fragmentidentifier
Constructs a SQL identifier segment that will be escaped by the active compiler.
Signature
declare function identifier(value: string): Identifier;Creates a helper that joins SQL clauses with a literal separator, optionally wrapping multiple clauses in parentheses and using a fallback for an empty list.
Signature
declare function join(lit: string, addParens: boolean, fallback: string): (clauses: readonly Array<string | Fragment>) => FragmentConstructs a raw SQL literal segment. The literal text is not escaped, so use bound parameters for untrusted values.
Signature
declare function literal(value: string, params?: readonly Array<unknown>): LiteralCreates a cached SQL statement constructor from a connection acquirer, compiler, tracing attributes, and optional row transformation function.
Signature
declare function make(acquirer: Acquirer, compiler: Compiler, spanAttributes: readonly Array<readonly [string, unknown]>, transformRows: <A extends object>(row: readonly Array<A>) => readonly Array<A> | undefined): ConstructormakeCompiler
Creates a dialect-specific SQL Compiler from rendering callbacks.
Signature
declare function makeCompiler<C extends Custom<any, any, any, any> = any>(
options: CompilerOptions<C>,
): Compiler;makeCompilerSqlite
Creates a SQLite compiler that uses ? placeholders and quoted identifiers, optionally transforming identifier names before escaping.
Signature
declare function makeCompilerSqlite(transform?: (_: string) => string): Compiler;Combines clauses with OR, parenthesizing multiple clauses and returning 1=1 when the list is empty.
Signature
declare const or: (clauses: ReadonlyArray<string | Fragment>) => Fragment;Constructs a bound parameter segment for a statement value.
Signature
declare function parameter(value: unknown): Parameter;recordInsertHelper
Constructs a RecordInsertHelper from one or more row objects.
Signature
declare function recordInsertHelper(value: readonly Array<Record<string, unknown>>): RecordInsertHelperrecordUpdateHelper
Constructs a RecordUpdateHelper for multi-row update compilation using the provided alias.
Signature
declare function recordUpdateHelper(value: readonly Array<Record<string, unknown>>, alias: string): RecordUpdateHelperrecordUpdateHelperSingle
Constructs a RecordUpdateHelperSingle from a record and a list of columns to omit from the update.
Signature
declare function recordUpdateHelperSingle(value: Record<string, unknown>, omit: readonly Array<string>): RecordUpdateHelperSingleBuilds a Statement from template strings and arguments, preserving fragments and helper segments while converting ordinary interpolated values into bound parameters.
Signature
declare function statement<A = Row>(acquirer: Acquirer, compiler: Compiler, strings: TemplateStringsArray, args: Array<any>, spanAttributes: readonly Array<readonly [string, unknown]>, transformRows: <A extends object>(row: readonly Array<A>) => readonly Array<A> | undefined): Statement<A>Converting
primitiveKind
Classifies a JavaScript value as a SQL primitive kind, treating undefined as null and defaulting unrecognized objects to string.
Signature
declare function primitiveKind(value: unknown): PrimitiveKind;Guards
Creates a type guard for custom SQL segments with the specified custom kind.
Signature
declare function isCustom<A extends Custom<any, any, any, any>>(
kind: A["kind"],
): (u: unknown) => u is A;isFragment
Returns true when a value is a SQL Fragment.
Signature
declare function isFragment(u: unknown): u is Fragment;Models
ArrayHelper interface
Helper segment for compiling an array of values, commonly used to produce placeholder lists for IN clauses.
Signature
interface ArrayHelper {
readonly _tag: "ArrayHelper";
readonly value: readonly Array<unknown>;
}Dialect-specific compiler that converts a SQL Fragment into SQL text and bind parameters, with a no-transform variant.
Signature
interface Compiler {
readonly compile: (statement: Fragment, withoutTransform: boolean) => readonly [string, readonly Array<unknown>];
readonly dialect: Dialect;
readonly withoutTransform: Compiler;
}CompilerOptions type
Callbacks used by makeCompiler to render dialect placeholders, identifiers, insert helpers, update helpers, and custom SQL segments.
Signature
type CompilerOptions<C extends Custom<any, any, any, any> = any> = {
readonly dialect: Dialect;
readonly onCustom: (
type: C,
placeholder: (u: unknown) => string,
withoutTransform: boolean,
) => readonly [sql: string, params: ReadonlyArray<unknown>];
readonly onIdentifier: (value: string, withoutTransform: boolean) => string;
readonly onInsert?: (
columns: ReadonlyArray<string>,
placeholders: string,
values: ReadonlyArray<ReadonlyArray<unknown>>,
returning: readonly [sql: string, params: ReadonlyArray<unknown>] | undefined,
) => readonly [sql: string, binds: ReadonlyArray<unknown>];
readonly onRecordUpdate: (
placeholders: string,
alias: string,
columns: string,
values: ReadonlyArray<ReadonlyArray<unknown>>,
returning: readonly [sql: string, params: ReadonlyArray<unknown>] | undefined,
) => readonly [sql: string, params: ReadonlyArray<unknown>];
readonly onRecordUpdateSingle?: (
columns: ReadonlyArray<string>,
values: ReadonlyArray<unknown>,
returning: readonly [sql: string, params: ReadonlyArray<unknown>] | undefined,
) => readonly [sql: string, params: ReadonlyArray<unknown>];
readonly placeholder: (index: number, value: unknown) => string;
};Constructor interface
SQL tagged-template constructor and helper API for building parameterized statements, escaped identifiers, fragments, record helpers, and dialect-specific branches. Raw helpers such as unsafe and literal insert SQL text directly.
Signature
interface Constructor {
<A extends object = Row>(strings: TemplateStringsArray, ...args: Array<any>): Statement<A>;
(value: string): Identifier;
readonly and: (clauses: readonly Array<string | Fragment>) => Fragment;
readonly csv: {
(values: readonly Array<string | Fragment>): Fragment;
(prefix: string, values: readonly Array<string | Fragment>): Fragment;
};
readonly in: {
(value: readonly Array<unknown>): ArrayHelper;
(column: string, value: readonly Array<unknown>): Fragment;
};
readonly insert: {
(value: readonly Array<Record<string, unknown>>): RecordInsertHelper;
(value: Record<string, unknown>): RecordInsertHelper;
};
readonly join: (literal: string, addParens?: boolean, fallback?: string) => (clauses: readonly Array<string | Fragment>) => Fragment;
readonly literal: (sql: string) => Fragment;
readonly onDialect: <A, B, C, D, E>(options: {
readonly clickhouse: () => E;
readonly mssql: () => D;
readonly mysql: () => C;
readonly pg: () => B;
readonly sqlite: () => A;
}) => A | B | C | D | E;
readonly onDialectOrElse: <A, B = never, C = never, D = never, E = never, F = never>(options: {
readonly clickhouse?: () => F;
readonly mssql?: () => E;
readonly mysql?: () => D;
readonly orElse: () => A;
readonly pg?: () => C;
readonly sqlite?: () => B;
}) => A | B | C | D | E | F;
readonly or: (clauses: readonly Array<string | Fragment>) => Fragment;
readonly unsafe: <A extends object>(sql: string, params?: readonly Array<unknown>) => Statement<A>;
readonly update: <A extends Record<string, unknown>>(value: A, omit?: readonly Array<keyof A>) => RecordUpdateHelperSingle;
readonly updateValues: (value: readonly Array<Record<string, unknown>>, alias: string) => RecordUpdateHelper;
}Custom SQL segment identified by kind and interpreted by the compiler's onCustom callback.
Signature
interface Custom<T extends string = string, A = void, B = void, C = void> {
readonly _tag: "Custom";
readonly kind: T;
readonly paramA: A;
readonly paramB: B;
readonly paramC: C;
}Supported SQL dialect identifiers used by statement compilers.
Signature
type Dialect = "sqlite" | "pg" | "mysql" | "mssql" | "clickhouse";Composable SQL fragment represented as low-level segments that can be interpolated into statements.
Signature
interface Fragment {
readonly "~effect/sql/Fragment": "~effect/sql/Fragment";
readonly segments: readonly Array<Segment>;
}Union of helper segment types accepted by the SQL statement constructor.
Signature
type Helper =
| ArrayHelper
| RecordInsertHelper
| RecordUpdateHelper
| RecordUpdateHelperSingle
| Identifier
| Custom;Identifier interface
SQL identifier segment whose value is escaped by the active dialect compiler.
Signature
interface Identifier {
readonly _tag: "Identifier";
readonly value: string;
}Raw SQL literal segment. The literal text is inserted directly into the compiled SQL, while optional params are appended as bind parameters.
Signature
interface Literal {
readonly _tag: "Literal";
readonly params?: readonly Array<unknown>;
readonly value: string;
}Bound parameter segment whose value is emitted as a dialect-specific placeholder and bind value.
Signature
interface Parameter {
readonly _tag: "Parameter";
readonly value: unknown;
}PrimitiveKind type
Names the primitive value categories recognized by SQL statement helpers and primitiveKind.
Signature
type PrimitiveKind =
| "string"
| "number"
| "bigint"
| "boolean"
| "Date"
| "null"
| "Int8Array"
| "Uint8Array";RecordInsertHelper interface
Helper segment for compiling one or more record objects into an INSERT column/value clause, with optional returning output.
Signature
interface RecordInsertHelper {
readonly _tag: "RecordInsertHelper";
readonly returning: (sql: string | Identifier | Fragment) => RecordInsertHelper;
readonly value: readonly Array<Record<string, unknown>>;
}RecordUpdateHelper interface
Helper segment for compiling multi-row update values with a table alias and optional returning output.
Signature
interface RecordUpdateHelper {
readonly _tag: "RecordUpdateHelper";
readonly alias: string;
readonly returning: (sql: string | Identifier | Fragment) => RecordUpdateHelper;
readonly value: readonly Array<Record<string, unknown>>;
}RecordUpdateHelperSingle interface
Helper segment for compiling a single record into update assignments, omitting selected columns and optionally returning output.
Signature
interface RecordUpdateHelperSingle {
readonly _tag: "RecordUpdateHelperSingle";
readonly omit: readonly Array<string>;
readonly returning: (sql: string | Identifier | Fragment) => RecordUpdateHelperSingle;
readonly value: Record<string, unknown>;
}Union of low-level segment types that make up a SQL Fragment.
Signature
type Segment =
| Literal
| Identifier
| Parameter
| ArrayHelper
| RecordInsertHelper
| RecordUpdateHelper
| RecordUpdateHelperSingle
| Custom<any, any, any, any>;Executable SQL statement that is also a Fragment and Effect, with helpers for raw execution, streaming, value rows, unprepared execution, no-transform execution, and compilation.
Signature
interface Statement<A> extends Fragment, Effect<ReadonlyArray<A>, SqlError> {
readonly compile: (withoutTransform?: boolean) => readonly [string, readonly Array<unknown>];
readonly raw: Effect<unknown, SqlError>;
readonly stream: Stream<A, SqlError>;
readonly unprepared: Effect<readonly Array<A>, SqlError>;
readonly values: Effect<readonly Array<readonly Array<unknown>>, SqlError>;
readonly valuesUnprepared: Effect<readonly Array<readonly Array<unknown>>, SqlError>;
readonly withoutTransform: Effect<readonly Array<A>, SqlError>;
}Transformer type
Hook that can rewrite or wrap a Statement before execution, using the current SQL constructor, fiber, and tracing span.
Signature
type Transformer = (
self: Statement<unknown>,
sql: Constructor,
fiber: Fiber.Fiber<unknown, unknown>,
span: Tracer.Span,
) => Effect.Effect<Statement<unknown>>;Services
CurrentTransformer
Context reference for an optional current SQL statement transformer applied before statement execution.
Signature
declare const CurrentTransformer: Reference<Transformer | undefined>;Transforming
defaultTransforms
Builds value, object, and row-array transformers that rename object keys with the supplied function and optionally recurse into nested object arrays.
Signature
declare function defaultTransforms(transformer: (str: string) => string, nested: boolean): {
array: <A extends object>(rows: readonly Array<A>) => readonly Array<A>;
readonly object: (obj: Record<string, any>) => any;
readonly value: (value: any) => any;
}
Combines clauses with
AND, parenthesizing multiple clauses and returning1=1when the list is empty.