The best way to control Claude Code, Codex and more from any computer or phone

main
ts 435 lines 16.2 KB
Raw
1 /**
2 * Connects Effect SQL to SQLite on Node.js using `node:sqlite`.
3 *
4 * This module opens a SQLite database and exposes it as both `SqliteClient` and
5 * the generic Effect SQL client. It serializes access through one connection,
6 * caches prepared statements, enables WAL mode unless disabled, and waits up
7 * to five seconds for busy databases by default. Explicit transactions on
8 * writable connections use `BEGIN IMMEDIATE` to avoid read-to-write lock
9 * upgrades, which serializes them behind other writers even when they only
10 * read. Clients opened with `readonly: true` are unaffected. Busy waits block
11 * the Node.js event loop because `node:sqlite` is synchronous. Database backup
12 * and extension loading are supported; streaming queries and `updateValues`
13 * are not.
14 *
15 * @stability unstable
16 * @since 4.0.0
17 */
18 import * as Cache from "effect/Cache"
19 import * as Clock from "effect/Clock"
20 import * as Config from "effect/Config"
21 import * as Context from "effect/Context"
22 import * as Duration from "effect/Duration"
23 import * as Effect from "effect/Effect"
24 import * as Exit from "effect/Exit"
25 import { identity } from "effect/Function"
26 import * as Layer from "effect/Layer"
27 import * as Reactivity from "effect/reactivity/Reactivity"
28 import * as Schedule from "effect/Schedule"
29 import type * as Scope from "effect/Scope"
30 import * as Semaphore from "effect/Semaphore"
31 import * as Client from "effect/sql/SqlClient"
32 import type { Connection } from "effect/sql/SqlConnection"
33 import { classifySqliteError, SqlError } from "effect/sql/SqlError"
34 import * as Statement from "effect/sql/Statement"
35 import * as Stream from "effect/Stream"
36 import { backup as backupDatabase, DatabaseSync } from "node:sqlite"
37 import type { StatementSync } from "node:sqlite"
38
39 const ATTR_DB_SYSTEM_NAME = "db.system.name"
40 const MAX_BUSY_TIMEOUT = 2_147_483_647
41 const NANOS_PER_MILLI = BigInt(1_000_000)
42
43 /**
44 * Runtime type identifier used to mark Node `SqliteClient` values.
45 *
46 * @stability unstable
47 * @category type IDs
48 * @since 4.0.0
49 */
50 export const TypeId: TypeId = "~@effect/sql-sqlite-node/SqliteClient"
51
52 /**
53 * Type-level identifier used to mark Node `SqliteClient` values.
54 *
55 * @stability unstable
56 * @category type IDs
57 * @since 4.0.0
58 */
59 export type TypeId = "~@effect/sql-sqlite-node/SqliteClient"
60
61 /**
62 * Node SQLite client service, extending `SqlClient` with database export, backup, and extension loading helpers. `updateValues` is not supported.
63 *
64 * @stability unstable
65 * @category services
66 * @since 4.0.0
67 */
68 export interface SqliteClient extends Client.SqlClient {
69 readonly [TypeId]: TypeId
70 readonly config: SqliteClientConfig
71 readonly backup: (destination: string) => Effect.Effect<BackupMetadata, SqlError>
72 readonly loadExtension: (path: string) => Effect.Effect<void, SqlError>
73
74 /** Not supported in sqlite */
75 readonly updateValues: never
76 }
77
78 /**
79 * Metadata returned from a Node SQLite backup operation, reporting total and remaining page counts.
80 *
81 * @stability unstable
82 * @category models
83 * @since 4.0.0
84 */
85 export interface BackupMetadata {
86 readonly totalPages: number
87 readonly remainingPages: number
88 }
89
90 /**
91 * Service tag for the node SQLite client implementation.
92 *
93 * @stability unstable
94 * @category services
95 * @since 4.0.0
96 */
97 export const SqliteClient = Context.Service<SqliteClient>("@effect/sql-sqlite-node/SqliteClient")
98
99 /**
100 * Configuration for a node SQLite client backed by `node:sqlite`, including the database filename, read-only mode, statement cache settings, WAL and busy timeout behavior, span attributes, and query/result name transforms.
101 *
102 * @stability unstable
103 * @category models
104 * @since 4.0.0
105 */
106 export interface SqliteClientConfig {
107 readonly filename: string
108 readonly readonly?: boolean | undefined
109 readonly prepareCacheSize?: number | undefined
110 readonly prepareCacheTTL?: Duration.Input | undefined
111 readonly disableWAL?: boolean | undefined
112 /**
113 * How long SQLite waits when the database is busy. Defaults to 5 seconds.
114 * `Duration.infinity` is clamped to SQLite's maximum timeout.
115 * Waiting blocks the Node.js event loop because `node:sqlite` is synchronous.
116 */
117 readonly busyTimeout?: Duration.Input | undefined
118 readonly spanAttributes?: Record<string, unknown> | undefined
119
120 readonly transformResultNames?: ((str: string) => string) | undefined
121 readonly transformQueryNames?: ((str: string) => string) | undefined
122 }
123
124 interface SqliteConnection extends Connection {
125 readonly isTransaction: () => boolean
126 readonly backup: (destination: string) => Effect.Effect<BackupMetadata, SqlError>
127 readonly loadExtension: (path: string) => Effect.Effect<void, SqlError>
128 }
129
130 /**
131 * Creates a scoped node SQLite client from the supplied configuration, using a single serialized connection with WAL and a 5-second busy timeout enabled by default. Explicit transactions on writable connections take the write lock for their duration, even when they only read; clients opened with `readonly: true` are unaffected.
132 *
133 * @stability unstable
134 * @category constructors
135 * @since 4.0.0
136 */
137 export const make = (
138 options: SqliteClientConfig
139 ): Effect.Effect<SqliteClient, SqlError, Scope.Scope | Reactivity.Reactivity> =>
140 Effect.gen(function*() {
141 const compiler = Statement.makeCompilerSqlite(options.transformQueryNames)
142 const transformRows = options.transformResultNames ?
143 Statement.defaultTransforms(
144 options.transformResultNames
145 ).array :
146 undefined
147
148 const makeConnection = Effect.gen(function*() {
149 const db = yield* Effect.acquireRelease(
150 Effect.try({
151 try: () =>
152 new DatabaseSync(options.filename, {
153 readOnly: options.readonly ?? false,
154 allowExtension: true
155 }),
156 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to open database", "connect") })
157 }),
158 (db) => Effect.sync(() => db.close())
159 )
160 setLoadExtensionEnabled(db, false)
161 const busyTimeout = Math.min(
162 MAX_BUSY_TIMEOUT,
163 Math.max(0, Math.round(Duration.toMillis(options.busyTimeout ?? Duration.seconds(5))))
164 )
165 const exec = (sql: string) =>
166 Effect.try({
167 try: () => db.exec(sql),
168 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to configure database", "connect") })
169 })
170 yield* exec(`PRAGMA busy_timeout = ${busyTimeout}`)
171
172 if (options.disableWAL !== true && !options.readonly) {
173 // Switching to WAL can fail with SQLITE_BUSY without invoking the busy
174 // handler, so retry it until busyTimeout has elapsed. Each attempt's
175 // native busy wait is limited to the remaining time.
176 // Deno's `exec` errors omit `errcode`, so run the pragma as a prepared
177 // statement to keep SQLITE_BUSY retryable.
178 const enableWAL = Effect.try({
179 try: () => db.prepare("PRAGMA journal_mode = WAL").get(),
180 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to configure database", "connect") })
181 })
182 const deadline = (yield* Clock.monotonicTimeNanos) + BigInt(busyTimeout) * NANOS_PER_MILLI
183 const remainingMillis = Effect.map(
184 Clock.monotonicTimeNanos,
185 (now) => Math.max(0, Number((deadline - now) / NANOS_PER_MILLI))
186 )
187 yield* remainingMillis.pipe(
188 Effect.flatMap((remaining) => exec(`PRAGMA busy_timeout = ${remaining}`)),
189 Effect.andThen(enableWAL),
190 Effect.retry({
191 while: (error) =>
192 error.reason._tag === "LockTimeoutError" && Effect.map(remainingMillis, (remaining) => remaining > 0),
193 schedule: Schedule.spaced("10 millis")
194 })
195 )
196 yield* exec(`PRAGMA busy_timeout = ${busyTimeout}`)
197 }
198
199 const prepare = (sql: string) =>
200 Effect.try({
201 try: () => db.prepare(sql),
202 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to prepare statement", "prepare") })
203 })
204
205 const prepareCacheTTL = options.prepareCacheTTL ?? Duration.minutes(10)
206 const prepareCache = yield* Cache.makeWith(prepare, {
207 capacity: options.prepareCacheSize ?? 200,
208 timeToLive: (exit) => Exit.isSuccess(exit) ? prepareCacheTTL : Duration.zero
209 })
210
211 const runStatement = (
212 statement: StatementSync,
213 params: ReadonlyArray<unknown>,
214 raw: boolean
215 ) =>
216 Effect.withFiber<ReadonlyArray<any>, SqlError>((fiber) => {
217 const useSafeIntegers = Context.get(fiber.context, Client.SafeIntegers)
218 return Effect.try({
219 try: () => {
220 statement.setReadBigInts(useSafeIntegers)
221 if (!raw || statement.columns().length > 0) {
222 return statement.all(...(params as Array<any>)) as ReadonlyArray<any>
223 }
224 const result = statement.run(...(params as Array<any>))
225 return { changes: result.changes, lastInsertRowid: result.lastInsertRowid } as any
226 },
227 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
228 })
229 })
230
231 const runStatementValues = (
232 statement: StatementSync,
233 params: ReadonlyArray<unknown>
234 ) =>
235 Effect.withFiber<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>((fiber) => {
236 const useSafeIntegers = Context.get(fiber.context, Client.SafeIntegers)
237 return Effect.try({
238 try: () => {
239 statement.setReadBigInts(useSafeIntegers)
240 return statement.all(...(params as Array<any>)) as unknown as ReadonlyArray<ReadonlyArray<unknown>>
241 },
242 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
243 })
244 })
245
246 const runStatementValuesUnprepared = (
247 statement: StatementSync,
248 params: ReadonlyArray<unknown>
249 ) =>
250 Effect.withFiber<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>((fiber) => {
251 const useSafeIntegers = Context.get(fiber.context, Client.SafeIntegers)
252 return Effect.try({
253 try: () => {
254 statement.setReadBigInts(useSafeIntegers)
255 statement.setReturnArrays(true)
256 return statement.all(...(params as Array<any>)) as unknown as ReadonlyArray<ReadonlyArray<unknown>>
257 },
258 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
259 })
260 })
261
262 const run = (
263 sql: string,
264 params: ReadonlyArray<unknown>,
265 raw = false
266 ) =>
267 Effect.flatMap(
268 Cache.get(prepareCache, sql),
269 (s) => runStatement(s, params, raw)
270 )
271
272 const runValues = (
273 sql: string,
274 params: ReadonlyArray<unknown>
275 ) =>
276 Effect.acquireUseRelease(
277 Cache.get(prepareCache, sql),
278 (statement) => {
279 statement.setReturnArrays(true)
280 return runStatementValues(statement, params)
281 },
282 (statement) => Effect.sync(() => statement.setReturnArrays(false))
283 )
284
285 const runValuesUnprepared = (
286 sql: string,
287 params: ReadonlyArray<unknown>
288 ) => Effect.flatMap(prepare(sql), (statement) => runStatementValuesUnprepared(statement, params))
289
290 return identity<SqliteConnection>({
291 isTransaction: () => db.isTransaction,
292 execute(sql, params, transformRows) {
293 return transformRows
294 ? Effect.map(run(sql, params), transformRows)
295 : run(sql, params)
296 },
297 executeRaw(sql, params) {
298 return run(sql, params, true)
299 },
300 executeValues(sql, params) {
301 return runValues(sql, params)
302 },
303 executeValuesUnprepared(sql, params) {
304 return runValuesUnprepared(sql, params)
305 },
306 executeUnprepared(sql, params, transformRows) {
307 const effect = Effect.flatMap(prepare(sql), (statement) => runStatement(statement, params ?? [], false))
308 return transformRows ? Effect.map(effect, transformRows) : effect
309 },
310 executeStream(_sql, _params) {
311 return Stream.die("executeStream not implemented")
312 },
313 backup(destination) {
314 return Effect.suspend(() => {
315 let totalPages = 0
316 return Effect.tryPromise({
317 try: () =>
318 backupDatabase(db, destination, {
319 progress: (progress) => {
320 totalPages = progress.totalPages
321 }
322 }).then((pages): BackupMetadata => ({ totalPages: totalPages || pages, remainingPages: 0 })),
323 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to backup database", "backup") })
324 })
325 })
326 },
327 loadExtension(path) {
328 return Effect.acquireUseRelease(
329 Effect.sync(() => setLoadExtensionEnabled(db, true)),
330 () =>
331 Effect.try({
332 try: () => db.loadExtension(path),
333 catch: (cause) =>
334 new SqlError({ reason: classifyError(cause, "Failed to load extension", "loadExtension") })
335 }),
336 () => Effect.sync(() => setLoadExtensionEnabled(db, false))
337 )
338 }
339 })
340 })
341
342 const connection = yield* makeConnection
343 const { acquirer, borrower, isTransaction, onCommitFailure, transactionAcquirer } = Client.makeSqliteAcquirers({
344 connection: Effect.succeed(connection),
345 semaphore: yield* Semaphore.make(1),
346 isTransaction: (conn) => conn.isTransaction()
347 })
348
349 return Object.assign(
350 (yield* Client.make({
351 driver: "sqlite-node",
352 acquirer,
353 borrower,
354 compiler,
355 transactionAcquirer,
356 onCommitFailure,
357 isTransaction,
358 releaseSavepoint: (name) => `RELEASE SAVEPOINT ${name}`,
359 beginTransaction: options.readonly === true ? "BEGIN" : "BEGIN IMMEDIATE",
360 spanAttributes: [
361 ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
362 [ATTR_DB_SYSTEM_NAME, "sqlite"]
363 ],
364 transformRows
365 })) as SqliteClient,
366 {
367 [TypeId]: TypeId as TypeId,
368 config: options,
369 backup: (destination: string) => Effect.scoped(Effect.flatMap(acquirer, (_) => _.backup(destination))),
370 loadExtension: (path: string) => Effect.scoped(Effect.flatMap(acquirer, (_) => _.loadExtension(path)))
371 }
372 )
373 })
374
375 /**
376 * Builds a layer from an Effect `Config` value, providing both the node `SqliteClient` service and the generic `SqlClient` service.
377 *
378 * @stability unstable
379 * @category layers
380 * @since 4.0.0
381 */
382 export const layerConfig = (
383 config: Config.Wrap<SqliteClientConfig>
384 ): Layer.Layer<SqliteClient | Client.SqlClient, Config.ConfigError | SqlError> =>
385 Layer.effectContext(
386 Config.unwrap(config).pipe(
387 Effect.flatMap(make),
388 Effect.map((client) =>
389 Context.make(SqliteClient, client).pipe(
390 Context.add(Client.SqlClient, client)
391 )
392 )
393 )
394 ).pipe(Layer.provide(Reactivity.layer))
395
396 /**
397 * Builds a layer from a node SQLite client configuration, providing both `SqliteClient` and the generic `SqlClient` service.
398 *
399 * @stability unstable
400 * @category layers
401 * @since 4.0.0
402 */
403 export const layer = (
404 config: SqliteClientConfig
405 ): Layer.Layer<SqliteClient | Client.SqlClient, SqlError> =>
406 Layer.effectContext(
407 Effect.map(make(config), (client) =>
408 Context.make(SqliteClient, client).pipe(
409 Context.add(Client.SqlClient, client)
410 ))
411 ).pipe(Layer.provide(Reactivity.layer))
412
413 // internal
414
415 const classifyError = (cause: unknown, message: string, operation: string) =>
416 classifySqliteError(sqliteCauseWithErrno(cause), { message, operation })
417
418 const sqliteCauseWithErrno = (cause: unknown): unknown => {
419 if (typeof cause !== "object" || cause === null || !("errcode" in cause) || "errno" in cause) {
420 return cause
421 }
422 const errcode = (cause as { readonly errcode: unknown }).errcode
423 if (typeof errcode !== "number") {
424 return cause
425 }
426 return Object.assign(cause, { errno: errcode })
427 }
428
429 // Deno's node:sqlite has no `enableLoadExtension`, so `allowExtension` alone
430 // controls extension loading there.
431 const setLoadExtensionEnabled = (db: DatabaseSync, enabled: boolean): void => {
432 if (typeof db.enableLoadExtension === "function") {
433 db.enableLoadExtension(enabled)
434 }
435 }