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

main
ts 569 lines 19.2 KB
Raw
1 /**
2 * PostgreSQL support for Effect SQL, backed by the native wire protocol client.
3 *
4 * @stability unstable
5 * @since 4.0.0
6 */
7 import type * as Arr from "effect/Array"
8 import * as Config from "effect/Config"
9 import * as Context from "effect/Context"
10 import type * as Duration from "effect/Duration"
11 import * as Effect from "effect/Effect"
12 import * as Layer from "effect/Layer"
13 import type * as Pool from "effect/Pool"
14 import type * as Queue from "effect/Queue"
15 import * as Reactivity from "effect/reactivity/Reactivity"
16 import type * as Redacted from "effect/Redacted"
17 import type * as Scope from "effect/Scope"
18 import * as Client from "effect/sql/SqlClient"
19 import type { Borrower, Connection } from "effect/sql/SqlConnection"
20 import { SqlError, UnknownError } from "effect/sql/SqlError"
21 import type { Custom, Fragment } from "effect/sql/Statement"
22 import * as Statement from "effect/sql/Statement"
23 import * as Stream from "effect/Stream"
24 import type { Duplex } from "node:stream"
25 import type { ConnectionOptions } from "node:tls"
26 import { validateChannelName } from "./internal/sqlError.ts"
27 import * as PgConnection from "./PgConnection.ts"
28 import * as PgPool from "./PgPool.ts"
29 import * as PgTypes from "./PgTypes.ts"
30
31 /**
32 * The runtime type identifier for `PgClient`.
33 *
34 * @stability unstable
35 * @category type IDs
36 * @since 4.0.0
37 */
38 export const TypeId: TypeId = "~@effect/sql-pg/PgClient"
39
40 /**
41 * The type-level identifier for `PgClient`.
42 *
43 * @stability unstable
44 * @category type IDs
45 * @since 4.0.0
46 */
47 export type TypeId = "~@effect/sql-pg/PgClient"
48
49 /**
50 * A PostgreSQL `SqlClient` with JSON and `LISTEN`/`NOTIFY` helpers.
51 *
52 * @stability unstable
53 * @category services
54 * @since 4.0.0
55 */
56 export interface PgClient extends Client.SqlClient {
57 readonly [TypeId]: TypeId
58 readonly config: PgClientConfig
59 readonly json: (_: unknown) => Fragment
60 /**
61 * Registers a channel listener and returns its notification queue after
62 * PostgreSQL confirms `LISTEN`. The listener holds a connection until the
63 * scope closes.
64 * Connection failures after registration fail the queue with the original
65 * `SqlError`. Intentional scope closure interrupts consumers.
66 */
67 readonly listen: (
68 channel: string
69 ) => Effect.Effect<Queue.Dequeue<PgConnection.Notification, SqlError>, SqlError, Scope.Scope>
70 readonly notify: (channel: string, payload: string) => Effect.Effect<void, SqlError>
71 /**
72 * Returns a snapshot of connection pool occupancy. A client from `makeClient`
73 * has one session that stays leased for its lifetime, so it always reports
74 * `{ idle: 0, used: 1, pending: 0, min: 1, max: 1 }` whatever statements run
75 * on it.
76 */
77 readonly poolStats: Effect.Effect<Pool.Stats>
78 }
79
80 /**
81 * The service tag for `PgClient`.
82 *
83 * @stability unstable
84 * @category services
85 * @since 4.0.0
86 */
87 export const PgClient = Context.Service<PgClient>("@effect/sql-pg/PgClient")
88
89 /**
90 * Connection and query settings for a PostgreSQL client.
91 *
92 * @stability unstable
93 * @category models
94 * @since 4.0.0
95 */
96 export interface PgClientConfig<R = never> {
97 readonly url?: Redacted.Redacted | undefined
98
99 readonly host?: string | undefined
100 readonly port?: number | undefined
101 readonly path?: string | undefined
102 readonly ssl?: boolean | ConnectionOptions | undefined
103 readonly database?: string | undefined
104 readonly username?: string | undefined
105 /**
106 * A static password or an Effect evaluated for each connection attempt.
107 * Providers must handle typed errors and require no services.
108 * {@link Effect.orDie} converts typed errors to defects, not retryable SQL errors.
109 */
110 readonly password?: Redacted.Redacted | Effect.Effect<Redacted.Redacted> | undefined
111
112 readonly connectTimeout?: Duration.Input | undefined
113 /** Idle time before TCP keepalive probes start. See `PgConnection.Config.keepAlive`. */
114 readonly keepAlive?: Duration.Input | undefined
115
116 readonly stream?: (() => Duplex) | undefined
117
118 /**
119 * Overrides `startupParameters.application_name`, the URL's `application_name`,
120 * and the default `"@effect/sql-pg"`, in that order.
121 */
122 readonly applicationName?: string | undefined
123 /**
124 * Session defaults sent in every physical connection's startup packet.
125 * Names are lowercased; `user`, `database`, `replication`, and `options` are
126 * reserved. `client_encoding` only accepts UTF8 / UTF-8 (case-insensitive).
127 * Empty names and NUL bytes fail before connecting; PostgreSQL validates
128 * other settings. Do not set the same GUC here and in `startupOptions`.
129 */
130 readonly startupParameters?: Readonly<Record<string, string>> | undefined
131 /**
132 * Opaque PostgreSQL startup options, overriding the URL's `options` parameter.
133 * Forwarded without parsing `-c` flags or checking for duplicate GUCs.
134 */
135 readonly startupOptions?: string | undefined
136 readonly spanAttributes?: Record<string, unknown> | undefined
137
138 readonly transformResultNames?: ((str: string) => string) | undefined
139 readonly transformQueryNames?: ((str: string) => string) | undefined
140 readonly transformJson?: boolean | undefined
141 readonly types?: PgTypes.Registry | undefined
142 /**
143 * Pipelines queries from multiple fibers on each pooled connection.
144 * Transactions, streams, and listeners still reserve a connection.
145 */
146 readonly multiplex?: boolean | undefined
147 /**
148 * How many statements may share one connection when `multiplex` is on.
149 * Defaults to `32`. Higher values trade tail latency for throughput: the
150 * statements sharing a connection are pipelined into one write, and they
151 * also queue behind the slowest of them.
152 */
153 readonly multiplexConcurrency?: number | undefined
154 /**
155 * Caches prepared statements by name. Enabled by default. Disable it for
156 * poolers that cannot preserve named statements between queries, such as
157 * PgBouncer in transaction mode with `max_prepared_statements = 0`.
158 */
159 readonly prepare?: boolean | undefined
160 /** How many statements a connection keeps prepared. Defaults to `100`. */
161 readonly preparedStatementCacheSize?: number | undefined
162 /** Maximum backend message size in bytes. Defaults to 16 MiB. */
163 readonly maxMessageSize?: number | undefined
164 /**
165 * Runs after each connection checkout, in the fiber that uses the connection.
166 *
167 * **Details**
168 *
169 * Runs once per statement or stream outside a transaction, including
170 * multiplexed statements, and once per `withTransaction`, `reserve`, `listen`
171 * and `notify`. Finalizers it adds run when that acquisition ends. Services it
172 * requires are captured when the client is built, and the consuming fiber's
173 * services take precedence.
174 *
175 * **Gotchas**
176 *
177 * Keep it cheap: it runs while holding the connection. With `makeClient` and
178 * `acquireForStream`, it runs before a stream opens its own connection.
179 *
180 * **Example** (Reading request context on each checkout)
181 *
182 * ```ts
183 * import { PgClient } from "@effect/sql-pg"
184 * import { Context, Effect } from "effect"
185 *
186 * // Set by each request handler with `Effect.provideService`.
187 * const KeepAlive = Context.Reference<(() => void) | undefined>("app/KeepAlive", {
188 * defaultValue: () => undefined
189 * })
190 *
191 * const layer = PgClient.layer({
192 * onAcquire: Effect.gen(function*() {
193 * const keepAlive = yield* KeepAlive
194 * keepAlive?.()
195 * })
196 * })
197 * ```
198 */
199 readonly onAcquire?: Effect.Effect<void, never, R> | undefined
200 }
201
202 /**
203 * PostgreSQL client settings with connection pool limits and timeouts.
204 *
205 * @stability unstable
206 * @category models
207 * @since 4.0.0
208 */
209 export interface PgPoolConfig<R = never> extends PgClientConfig<R> {
210 readonly idleTimeout?: Duration.Input | undefined
211
212 readonly maxConnections?: number | undefined
213 readonly minConnections?: number | undefined
214 readonly connectionTTL?: Duration.Input | undefined
215 /** Bounds how long acquiring a pooled connection takes. See `PgPool.Config.acquireTimeout`. */
216 readonly acquireTimeout?: Duration.Input | undefined
217 }
218
219 /**
220 * Creates a scoped PostgreSQL client backed by a connection pool.
221 *
222 * @stability unstable
223 * @category constructors
224 * @since 4.0.0
225 */
226 export const make = <R = never>(
227 options: PgPoolConfig<R>
228 ): Effect.Effect<PgClient, SqlError, Scope.Scope | Reactivity.Reactivity | R> =>
229 Effect.flatMap(PgPool.make(options), (pool) =>
230 makeImpl({
231 acquirer: Effect.map(pool.get, makeConnection),
232 borrower: (f) => pool.use((connection) => f(makeConnection(connection))),
233 transactionAcquirer: Effect.map(pool.reserve, makeConnection),
234 listenAcquirer: pool.reserve,
235 config: options,
236 poolStats: pool.stats
237 }))
238
239 /**
240 * Creates a scoped PostgreSQL client backed by one connection.
241 *
242 * @stability unstable
243 * @category constructors
244 * @since 4.0.0
245 */
246 export const makeClient = <R = never>(
247 options: PgClientConfig<R> & {
248 /**
249 * Opens a separate connection for each stream and listener when enabled.
250 */
251 readonly acquireForStream?: boolean | undefined
252 }
253 ): Effect.Effect<PgClient, SqlError, Scope.Scope | Reactivity.Reactivity | R> =>
254 Effect.flatMap(PgConnection.make(options), (connection) =>
255 makeImpl({
256 acquirer: Effect.succeed(makeConnection(
257 connection,
258 options.acquireForStream ? PgConnection.make(options) : undefined
259 )),
260 transactionAcquirer: Effect.map(connection.pin, makeConnection),
261 listenAcquirer: options.acquireForStream ? PgConnection.make(options) : connection.pin,
262 config: options,
263 // The one session is leased for the client's lifetime.
264 poolStats: Effect.succeed({ idle: 0, used: 1, pending: 0, min: 1, max: 1 })
265 }))
266
267 /**
268 * Builds the shared SQL facade around native connection acquirers.
269 */
270 const makeImpl = Effect.fnUntraced(function*<R>(
271 options: {
272 readonly acquirer: Effect.Effect<Connection, SqlError, Scope.Scope>
273 readonly borrower?: Borrower | undefined
274 readonly transactionAcquirer: Effect.Effect<Connection, SqlError, Scope.Scope>
275 readonly listenAcquirer: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope>
276 readonly config: PgClientConfig<R>
277 readonly poolStats: Effect.Effect<Pool.Stats>
278 }
279 ): Effect.fn.Return<PgClient, SqlError, Scope.Scope | Reactivity.Reactivity | R> {
280 // The consuming fiber's services take precedence over the captured ones.
281 const hook = options.config.onAcquire
282 const context = yield* Effect.context<R>()
283 const onAcquire = hook &&
284 Effect.updateContext(hook, (current: Context.Context<never>) => Context.merge(context, current))
285 const config: PgClientConfig = { ...options.config, onAcquire }
286 let { acquirer, borrower, listenAcquirer, transactionAcquirer } = options
287 if (onAcquire !== undefined) {
288 acquirer = Effect.tap(acquirer, onAcquire)
289 transactionAcquirer = Effect.tap(transactionAcquirer, onAcquire)
290 listenAcquirer = Effect.tap(listenAcquirer, onAcquire)
291 if (borrower !== undefined) {
292 const borrow = borrower
293 // Scope each statement so hook finalizers run when it ends.
294 borrower = (f) => borrow((connection) => Effect.scoped(Effect.andThen(onAcquire, f(connection))))
295 }
296 }
297 const compiler = makeCompiler(
298 config.transformQueryNames,
299 config.transformJson
300 )
301 const transformRows = config.transformResultNames ?
302 Statement.defaultTransforms(
303 config.transformResultNames,
304 config.transformJson
305 ).array :
306 undefined
307
308 const listen = (
309 channel: string
310 ): Effect.Effect<Queue.Dequeue<PgConnection.Notification, SqlError>, SqlError, Scope.Scope> =>
311 Effect.flatMap(listenAcquirer, (connection) => connection.listen(channel))
312
313 return Object.assign(
314 yield* Client.make({
315 driver: "pg",
316 acquirer,
317 borrower,
318 // Postgres prepares transaction control like anything else, and a client
319 // with preparation turned off falls back to the unnamed path anyway.
320 prepareTransactionControls: true,
321 commit,
322 onCommitFailure,
323 releaseSavepoint: (name) => `RELEASE SAVEPOINT ${name}`,
324 transactionAcquirer,
325 compiler,
326 spanAttributes: [
327 ...(config.spanAttributes ? Object.entries(config.spanAttributes) : []),
328 [ATTR_DB_SYSTEM_NAME, "postgresql"],
329 [ATTR_DB_NAMESPACE, config.database ?? config.username ?? "postgres"],
330 [ATTR_SERVER_ADDRESS, config.host ?? "localhost"],
331 [ATTR_SERVER_PORT, config.port ?? 5432]
332 ],
333 transformRows
334 }),
335 {
336 [TypeId]: TypeId as TypeId,
337 config,
338 poolStats: options.poolStats,
339 json: (_: unknown) => Statement.fragment([PgJson(_)]),
340 listen,
341 notify: (channel: string, payload: string) => {
342 const channelError = validateChannelName(channel, "notify")
343 return channelError !== undefined ?
344 Effect.fail(channelError) :
345 Effect.asVoid(Effect.scoped(Effect.flatMap(
346 acquirer,
347 (conn) => conn.executeRaw(`SELECT pg_notify($1, $2)`, [channel, payload])
348 )))
349 }
350 }
351 )
352 })
353
354 class ConnectionImpl implements Connection {
355 readonly connection: PgConnection.PgConnection
356 readonly streamAcquirer: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> | undefined
357
358 constructor(
359 connection: PgConnection.PgConnection,
360 streamAcquirer?: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> | undefined
361 ) {
362 this.connection = connection
363 this.streamAcquirer = streamAcquirer
364 }
365
366 private run(query: string, params: ReadonlyArray<unknown>, prepare = true) {
367 return Effect.map(this.connection.query(query, params, prepare), (result) => result.rows)
368 }
369
370 execute(
371 sql: string,
372 params: ReadonlyArray<unknown>,
373 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
374 ) {
375 return transformRows
376 ? Effect.map(this.run(sql, params), transformRows)
377 : this.run(sql, params)
378 }
379 executeRaw(sql: string, params: ReadonlyArray<unknown>) {
380 return this.connection.query(sql, params)
381 }
382 executeWithoutTransform(sql: string, params: ReadonlyArray<unknown>) {
383 return this.run(sql, params)
384 }
385 executeValues(sql: string, params: ReadonlyArray<unknown>) {
386 return this.connection.queryValues(sql, params)
387 }
388 executeValuesUnprepared(sql: string, params: ReadonlyArray<unknown>) {
389 return this.connection.queryValues(sql, params, false)
390 }
391 executeUnprepared(
392 sql: string,
393 params: ReadonlyArray<unknown>,
394 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
395 ) {
396 const operation = this.run(sql, params, false)
397 return transformRows
398 ? Effect.map(operation, transformRows)
399 : operation
400 }
401 executeStream(
402 sql: string,
403 params: ReadonlyArray<unknown>,
404 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
405 ) {
406 const stream = this.streamAcquirer === undefined
407 ? this.connection.stream(sql, params)
408 : Stream.unwrap(Effect.map(this.streamAcquirer, (connection) => connection.stream(sql, params)))
409 return transformRows
410 ? Stream.mapArray(stream, (rows) => transformRows(rows) as Arr.NonEmptyReadonlyArray<PgConnection.Row>)
411 : stream
412 }
413 }
414
415 /** PostgreSQL returns `ROLLBACK` for `COMMIT` when a transaction is aborted. */
416 const commit = (conn: Connection): Effect.Effect<void, SqlError> =>
417 Effect.flatMap(
418 conn.executeRaw("COMMIT", []) as Effect.Effect<PgConnection.Result, SqlError>,
419 (result) =>
420 result.command === "ROLLBACK"
421 ? Effect.fail(
422 new SqlError({
423 reason: new UnknownError({
424 cause: new Error("COMMIT rolled back an aborted transaction"),
425 message: "PgClient: COMMIT rolled back an aborted transaction",
426 operation: "commit"
427 })
428 })
429 )
430 : Effect.void
431 )
432
433 /**
434 * Rolls back a transaction left open by a `COMMIT` the backend rejected before
435 * running it. Outside a transaction `ROLLBACK` only warns. Its own failure is
436 * ignored so the `COMMIT` error is the one reported; a session it leaves
437 * aborted is closed on pin release.
438 */
439 const onCommitFailure = (conn: Connection): Effect.Effect<void> =>
440 Effect.ignore(conn.executeUnprepared("ROLLBACK", [], undefined))
441
442 const makeConnection = (
443 connection: PgConnection.PgConnection,
444 streamAcquirer?: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> | undefined
445 ): Connection => new ConnectionImpl(connection, streamAcquirer)
446
447 /**
448 * Provides both `PgClient` and `SqlClient` from an acquisition effect.
449 *
450 * @stability unstable
451 * @category layers
452 * @since 4.0.0
453 */
454 export const layerFrom = <E, R>(
455 acquire: Effect.Effect<PgClient, E, R>
456 ): Layer.Layer<PgClient | Client.SqlClient, E, Exclude<R, Scope.Scope | Reactivity.Reactivity>> =>
457 Layer.effectContext(
458 Effect.map(acquire, (client) =>
459 Context.make(PgClient, client).pipe(
460 Context.add(Client.SqlClient, client)
461 ))
462 ).pipe(Layer.provide(Reactivity.layer)) as any
463
464 /**
465 * Creates a client layer from wrapped pool configuration.
466 *
467 * @stability unstable
468 * @category layers
469 * @since 4.0.0
470 */
471 export const layerConfig = <R = never>(
472 config: Config.Wrap<PgPoolConfig<R>>
473 ): Layer.Layer<
474 PgClient | Client.SqlClient,
475 Config.ConfigError | SqlError,
476 Exclude<R, Scope.Scope | Reactivity.Reactivity>
477 > =>
478 layerFrom(Effect.flatMap(
479 Config.unwrap(config),
480 make
481 ))
482
483 /**
484 * Creates a client layer from pool configuration.
485 *
486 * @stability unstable
487 * @category layers
488 * @since 4.0.0
489 */
490 export const layer = <R = never>(
491 config: PgPoolConfig<R>
492 ): Layer.Layer<PgClient | Client.SqlClient, SqlError, Exclude<R, Scope.Scope | Reactivity.Reactivity>> =>
493 layerFrom(make(config))
494
495 /**
496 * Creates the PostgreSQL statement compiler.
497 *
498 * @stability unstable
499 * @category constructors
500 * @since 4.0.0
501 */
502 export const makeCompiler = (
503 transform?: (_: string) => string,
504 transformJson = true
505 ): Statement.Compiler => {
506 const transformValue = transformJson && transform
507 ? Statement.defaultTransforms(transform).value
508 : undefined
509
510 return Statement.makeCompiler<PgCustom>({
511 dialect: "pg",
512 placeholder(_) {
513 return `$${_}`
514 },
515 onIdentifier: transform ?
516 function(value, withoutTransform) {
517 return withoutTransform ? escape(value) : escape(transform(value))
518 } :
519 escape,
520 onRecordUpdate(placeholders, valueAlias, valueColumns, values, returning) {
521 return [
522 `(values ${placeholders}) AS ${valueAlias}${valueColumns}${returning ? ` RETURNING ${returning[0]}` : ""}`,
523 returning ?
524 values.flat().concat(returning[1]) :
525 values.flat()
526 ]
527 },
528 onCustom(type, placeholder, withoutTransform) {
529 switch (type.kind) {
530 case "PgJson": {
531 const value = withoutTransform || transformValue === undefined
532 ? type.paramA
533 : transformValue(type.paramA)
534 return [
535 placeholder(undefined),
536 [PgTypes.jsonb(value)]
537 ]
538 }
539 }
540 }
541 })
542 }
543
544 const escape = Statement.defaultEscape("\"")
545
546 /**
547 * PostgreSQL-specific statement fragments.
548 *
549 * @stability unstable
550 * @category models
551 * @since 4.0.0
552 */
553 export type PgCustom = PgJson
554
555 /**
556 * @category models
557 * @since 4.0.0
558 */
559 interface PgJson extends Custom<"PgJson", unknown> {}
560 /**
561 * @category constructors
562 * @since 4.0.0
563 */
564 const PgJson = Statement.custom<PgJson>("PgJson")
565
566 const ATTR_DB_SYSTEM_NAME = "db.system.name"
567 const ATTR_DB_NAMESPACE = "db.namespace"
568 const ATTR_SERVER_ADDRESS = "server.address"
569 const ATTR_SERVER_PORT = "server.port"