1/**
2 * Low-level SQL connection contract used by driver integrations.
3 *
4 * A `Connection` is the driver-facing layer under `SqlClient`. It executes
5 * already-compiled SQL with positional parameters and can return transformed
6 * rows, raw driver results, streams, value arrays, or unprepared statement
7 * results. This module also defines the scoped connection acquirer type, the
8 * connection service tag, and the generic row shape.
9 *
10 * @stability unstable
11 * @since 4.0.0
12 */
13import * as Context from "../Context.ts"
14import type { Effect } from "../Effect.ts"
15import type { Scope } from "../Scope.ts"
16import type { Stream } from "../Stream.ts"
17import type { SqlError } from "./SqlError.ts"
18
19/**
20 * Low-level SQL driver connection capable of executing compiled SQL as
21 * transformed rows, raw results, streams, value arrays, or unprepared
22 * statements.
23 *
24 * @stability unstable
25 * @category models
26 * @since 4.0.0
27 */
28export interface Connection {
29 readonly execute: (
30 sql: string,
31 params: ReadonlyArray<unknown>,
32 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
33 ) => Effect<ReadonlyArray<any>, SqlError>
34
35 /**
36 * Execute the specified SQL query and return the raw results directly from
37 * underlying SQL client.
38 */
39 readonly executeRaw: (
40 sql: string,
41 params: ReadonlyArray<unknown>
42 ) => Effect<unknown, SqlError>
43
44 readonly executeStream: (
45 sql: string,
46 params: ReadonlyArray<unknown>,
47 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
48 ) => Stream<any, SqlError>
49
50 readonly executeValues: (
51 sql: string,
52 params: ReadonlyArray<unknown>
53 ) => Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>
54
55 readonly executeValuesUnprepared: (
56 sql: string,
57 params: ReadonlyArray<unknown>
58 ) => Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>
59
60 readonly executeUnprepared: (
61 sql: string,
62 params: ReadonlyArray<unknown>,
63 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
64 ) => Effect<ReadonlyArray<any>, SqlError>
65}
66
67/**
68 * Scoped effect that acquires a `Connection`, may fail with `SqlError`, and
69 * requires a `Scope` for release.
70 *
71 * @stability unstable
72 * @category models
73 * @since 4.0.0
74 */
75export type Acquirer = Effect<Connection, SqlError, Scope>
76
77/**
78 * Lends a connection for the duration of one effect and takes it back on any
79 * exit, without the caller opening a scope for it.
80 *
81 * **Details**
82 *
83 * A client that can do this offers it alongside its `Acquirer`, for statements
84 * that finish with the effect that runs them. Long-lived work such as `stream`
85 * still goes through the `Acquirer`, whose lease has to outlive the effect
86 * that starts it.
87 *
88 * @stability unstable
89 * @category models
90 * @since 4.0.0
91 */
92export type Borrower = <A, E, R>(
93 f: (connection: Connection) => Effect<A, E, R>
94) => Effect<A, E | SqlError, R>
95
96/**
97 * Service tag for a low-level SQL `Connection`.
98 *
99 * @stability unstable
100 * @category services
101 * @since 4.0.0
102 */
103export const Connection = Context.Service<Connection>("effect/sql/SqlConnection")
104
105/**
106 * Generic SQL row shape mapping column names to unknown values.
107 *
108 * @stability unstable
109 * @category models
110 * @since 4.0.0
111 */
112export type Row = { readonly [column: string]: unknown }