The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * Pools of native `PgConnection` sessions. |
| 3 | * |
| 4 | * @stability unstable |
| 5 | * @since 4.0.0 |
| 6 | */ |
| 7 | import * as Clock from "effect/Clock" |
| 8 | import * as Context from "effect/Context" |
| 9 | import * as Duration from "effect/Duration" |
| 10 | import * as Effect from "effect/Effect" |
| 11 | import * as Exit from "effect/Exit" |
| 12 | import * as Option from "effect/Option" |
| 13 | import * as Pool from "effect/Pool" |
| 14 | import { TracerTimingEnabled } from "effect/References" |
| 15 | import * as Scope from "effect/Scope" |
| 16 | import { ConnectionError, SqlError } from "effect/sql/SqlError" |
| 17 | import { SpanPropagationEnabled } from "effect/sql/Statement" |
| 18 | import * as Tracer from "effect/Tracer" |
| 19 | import { connectionInternals } from "./internal/connection.ts" |
| 20 | import * as PgConnection from "./PgConnection.ts" |
| 21 | |
| 22 | const defaultMultiplexConcurrency = 32 |
| 23 | |
| 24 | /** |
| 25 | * The runtime type identifier for `PgPool`. |
| 26 | * |
| 27 | * @stability unstable |
| 28 | * @category type IDs |
| 29 | * @since 4.0.0 |
| 30 | */ |
| 31 | export const TypeId: TypeId = "~@effect/sql-pg/PgPool" |
| 32 | |
| 33 | /** |
| 34 | * The type-level identifier for `PgPool`. |
| 35 | * |
| 36 | * @stability unstable |
| 37 | * @category type IDs |
| 38 | * @since 4.0.0 |
| 39 | */ |
| 40 | export type TypeId = "~@effect/sql-pg/PgPool" |
| 41 | |
| 42 | /** |
| 43 | * Connection and sizing settings for a PostgreSQL session pool. |
| 44 | * |
| 45 | * **Details** |
| 46 | * |
| 47 | * The defaults are 0 to 10 connections and a 60-second idle timeout. |
| 48 | * `connectionTTL` replaces connections that exceed the configured lifetime. |
| 49 | * Every connection is used at least once, so a TTL of zero disables reuse. |
| 50 | * `acquireTimeout` bounds how long a checkout takes to acquire a connection, |
| 51 | * including opening a new one; by default it waits indefinitely. |
| 52 | * |
| 53 | * With `multiplex` enabled, fibers may share pooled connections for pipelined |
| 54 | * queries. Reserved connections remain exclusive. Without multiplexing, every |
| 55 | * checkout is exclusive. |
| 56 | * |
| 57 | * @stability unstable |
| 58 | * @category models |
| 59 | * @since 4.0.0 |
| 60 | */ |
| 61 | export interface Config extends PgConnection.Config { |
| 62 | readonly idleTimeout?: Duration.Input | undefined |
| 63 | readonly maxConnections?: number | undefined |
| 64 | readonly minConnections?: number | undefined |
| 65 | readonly connectionTTL?: Duration.Input | undefined |
| 66 | /** |
| 67 | * How long a checkout may take to acquire a connection before failing with |
| 68 | * a `ConnectionError`. Acquisition includes waiting for a free connection |
| 69 | * and opening a new one when the pool needs it. With `multiplex` on, |
| 70 | * `reserve` also waits for statements already sent on the shared connection |
| 71 | * to finish, and that wait counts too. Work done with the connection after |
| 72 | * it is acquired is not bounded. Unbounded by default. |
| 73 | */ |
| 74 | readonly acquireTimeout?: Duration.Input | undefined |
| 75 | /** |
| 76 | * How many statements may share one connection when `multiplex` is on. |
| 77 | * Defaults to `32`. Statements are pipelined into one write, so a higher |
| 78 | * number means fewer round trips, but it also means a slow statement holds |
| 79 | * up more of the statements queued behind it. |
| 80 | */ |
| 81 | readonly multiplexConcurrency?: number | undefined |
| 82 | } |
| 83 | |
| 84 | /** |
| 85 | * A PostgreSQL session pool. |
| 86 | * |
| 87 | * @stability unstable |
| 88 | * @category models |
| 89 | * @since 4.0.0 |
| 90 | */ |
| 91 | export interface PgPool { |
| 92 | readonly [TypeId]: TypeId |
| 93 | readonly config: Config |
| 94 | /** |
| 95 | * Checks out a session until the scope closes. Without multiplexing the |
| 96 | * checkout is exclusive. With multiplexing the |
| 97 | * session may be shared with other fibers, so multi-statement work should |
| 98 | * use `reserve` instead. |
| 99 | */ |
| 100 | readonly get: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> |
| 101 | /** |
| 102 | * Checks out a session for exclusive use until the scope closes. Use this for |
| 103 | * transactions and listeners on a multiplexed pool. |
| 104 | */ |
| 105 | readonly reserve: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> |
| 106 | /** |
| 107 | * Removes a session so the pool can replace it. Fatal protocol and socket |
| 108 | * errors invalidate sessions automatically. |
| 109 | */ |
| 110 | /** |
| 111 | * Lends a session for the duration of one effect and takes it back on any |
| 112 | * exit, without opening a scope for it. |
| 113 | * |
| 114 | * **Details** |
| 115 | * |
| 116 | * For work that finishes with the effect that runs it. A lease that has to |
| 117 | * outlive its effect - a stream, a transaction - takes `get` or `reserve`. |
| 118 | */ |
| 119 | readonly use: <A, E, R>( |
| 120 | f: (connection: PgConnection.PgConnection) => Effect.Effect<A, E, R> |
| 121 | ) => Effect.Effect<A, E | SqlError, R> |
| 122 | readonly invalidate: (connection: PgConnection.PgConnection) => Effect.Effect<void> |
| 123 | /** |
| 124 | * Returns a snapshot of session occupancy. Counts sessions rather than |
| 125 | * statements, so a multiplexed session shared by many fibers counts once. A |
| 126 | * session that has just failed can show as idle until the pool removes it. |
| 127 | */ |
| 128 | readonly stats: Effect.Effect<Pool.Stats> |
| 129 | } |
| 130 | |
| 131 | /** |
| 132 | * The service tag for `PgPool`. |
| 133 | * |
| 134 | * @stability unstable |
| 135 | * @category services |
| 136 | * @since 4.0.0 |
| 137 | */ |
| 138 | export const PgPool = Context.Service<PgPool>("@effect/sql-pg/PgPool") |
| 139 | |
| 140 | /** |
| 141 | * Creates a scoped PostgreSQL session pool. |
| 142 | * |
| 143 | * **Details** |
| 144 | * |
| 145 | * Connections are opened lazily up to `maxConnections` and released down to |
| 146 | * `minConnections` after `idleTimeout` without use. Closing the scope shuts |
| 147 | * the pool down and releases every session. |
| 148 | * |
| 149 | * With `SpanPropagationEnabled`, a statement that waited for a new session gets |
| 150 | * a `db.connect` child span covering the part of the connect it waited for. |
| 151 | * |
| 152 | * @stability unstable |
| 153 | * @category constructors |
| 154 | * @since 4.0.0 |
| 155 | */ |
| 156 | export const make = Effect.fnUntraced(function*(options: Config): Effect.fn.Return<PgPool, SqlError, Scope.Scope> { |
| 157 | const clock = yield* Clock.Clock |
| 158 | const runFork = Effect.runForkWith(yield* Effect.context()) |
| 159 | |
| 160 | const multiplex = options.multiplex ?? false |
| 161 | const connectionTTL = options.connectionTTL !== undefined |
| 162 | ? Duration.toMillis(Duration.fromInputUnsafe(options.connectionTTL)) |
| 163 | : undefined |
| 164 | const acquireTimeout = options.acquireTimeout !== undefined |
| 165 | ? Duration.fromInputUnsafe(options.acquireTimeout) |
| 166 | : undefined |
| 167 | const deadConnections = new Set<PgConnection.PgConnection>() |
| 168 | const createdAt = new WeakMap<PgConnection.PgConnection, number>() |
| 169 | const checkedOut = new WeakSet<PgConnection.PgConnection>() |
| 170 | |
| 171 | // The pool opens sessions on its own fiber, where a span would have no |
| 172 | // statement parent. Each connect is recorded here instead and reported on the |
| 173 | // session's first checkout, under the statement that waited for it. |
| 174 | const connects = new WeakMap<PgConnection.PgConnection, readonly [startTime: bigint, endTime: bigint]>() |
| 175 | |
| 176 | const reportConnect = (connection: PgConnection.PgConnection): Effect.Effect<void> => |
| 177 | Effect.withFiber((fiber) => { |
| 178 | const opened = connects.get(connection) |
| 179 | if (opened === undefined) return Effect.void |
| 180 | connects.delete(connection) |
| 181 | const statement = fiber.cache.span |
| 182 | // Without span timing the statement span has no start time to measure from. |
| 183 | if ( |
| 184 | !fiber.cache.tracerEnabled || statement?._tag !== "Span" || !fiber.getRef(SpanPropagationEnabled) || |
| 185 | !fiber.getRef(TracerTimingEnabled) |
| 186 | ) { |
| 187 | return Effect.void |
| 188 | } |
| 189 | const [startTime, endTime] = opened |
| 190 | const waitedFrom = statement.status.startTime |
| 191 | if (endTime < waitedFrom) return Effect.void |
| 192 | const span = fiber.getRef(Tracer.Tracer).span({ |
| 193 | name: "db.connect", |
| 194 | parent: Option.some(statement), |
| 195 | annotations: Context.empty(), |
| 196 | links: [], |
| 197 | startTime: startTime > waitedFrom ? startTime : waitedFrom, |
| 198 | kind: "client", |
| 199 | root: false, |
| 200 | sampled: statement.sampled |
| 201 | }) |
| 202 | span.attribute("db.system.name", "postgresql") |
| 203 | span.attribute("db.client.connection.connect_time_ms", Number(endTime - startTime) / 1e6) |
| 204 | span.end(endTime, Exit.void) |
| 205 | return Effect.void |
| 206 | }) |
| 207 | |
| 208 | const handOut = (connection: PgConnection.PgConnection) => |
| 209 | connects.has(connection) ? Effect.as(reportConnect(connection), connection) : Effect.succeed(connection) |
| 210 | |
| 211 | // Assigned below, once the pool exists. `acquire` only runs when the pool |
| 212 | // opens a connection, which is always after that. |
| 213 | let pool: Pool.Pool<PgConnection.PgConnection, SqlError> |
| 214 | const acquire = Effect.suspend(() => { |
| 215 | const startTime = clock.currentTimeNanosUnsafe() |
| 216 | return Effect.tap(PgConnection.make(options), (connection) => |
| 217 | Effect.sync(() => { |
| 218 | connects.set(connection, [startTime, clock.currentTimeNanosUnsafe()]) |
| 219 | createdAt.set(connection, clock.currentTimeMillisUnsafe()) |
| 220 | const internals = connectionInternals(connection) |
| 221 | internals.retireHooks.add(() => { |
| 222 | deadConnections.add(connection) |
| 223 | // `deadConnections` is only read by the next checkout, and a checkout |
| 224 | // already waiting for this connection would never get that far. Tell |
| 225 | // the pool now so it can replace the connection and admit them. |
| 226 | runFork(Pool.invalidate(pool, connection)) |
| 227 | }) |
| 228 | // Pinning a shared session has to take it out of circulation, or a |
| 229 | // second checkout lands on the connection its own stream is holding. |
| 230 | if (multiplex) internals.reserve = Pool.reserve(pool, connection) |
| 231 | })) |
| 232 | }) |
| 233 | |
| 234 | const maxConnections = options.maxConnections ?? 10 |
| 235 | pool = yield* Pool.makeWithTTL({ |
| 236 | acquire, |
| 237 | min: options.minConnections ?? 0, |
| 238 | max: maxConnections, |
| 239 | concurrency: multiplex |
| 240 | ? Math.max(1, options.multiplexConcurrency ?? defaultMultiplexConcurrency) |
| 241 | : 1, |
| 242 | timeToLive: options.idleTimeout ?? Duration.seconds(60), |
| 243 | timeToLiveStrategy: "usage" |
| 244 | }) |
| 245 | |
| 246 | const expired = (connection: PgConnection.PgConnection): boolean => { |
| 247 | if (connectionInternals(connection).deadError() !== undefined) return true |
| 248 | if (connectionTTL === undefined) return false |
| 249 | if (!checkedOut.has(connection)) { |
| 250 | checkedOut.add(connection) |
| 251 | return false |
| 252 | } |
| 253 | const openedAt = createdAt.get(connection) |
| 254 | return openedAt !== undefined && clock.currentTimeMillisUnsafe() - openedAt >= connectionTTL |
| 255 | } |
| 256 | |
| 257 | // A checkout runs per statement, so the case where nothing has died and the |
| 258 | // first connection is usable stays a plain flatMap; retrying is the |
| 259 | // exception and pays for the loop. |
| 260 | const retry: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> = Effect.gen(function*() { |
| 261 | while (true) { |
| 262 | if (deadConnections.size > 0) { |
| 263 | const dead = Array.from(deadConnections) |
| 264 | deadConnections.clear() |
| 265 | yield* Effect.forEach(dead, (connection) => Pool.invalidate(pool, connection), { discard: true }) |
| 266 | } |
| 267 | const connection = yield* Pool.get(pool) |
| 268 | if (expired(connection)) { |
| 269 | yield* Pool.invalidate(pool, connection) |
| 270 | continue |
| 271 | } |
| 272 | return connection |
| 273 | } |
| 274 | }) |
| 275 | |
| 276 | const checkout: Effect.Effect<PgConnection.PgConnection, SqlError, Scope.Scope> = Effect.suspend(() => |
| 277 | deadConnections.size > 0 ? retry : Effect.flatMap(Pool.get(pool), (connection) => |
| 278 | expired(connection) |
| 279 | ? Effect.andThen(Pool.invalidate(pool, connection), retry) |
| 280 | : Effect.succeed(connection)) |
| 281 | ) |
| 282 | |
| 283 | const acquireTimedOut = () => |
| 284 | Effect.fail( |
| 285 | new SqlError({ |
| 286 | reason: new ConnectionError({ |
| 287 | cause: new Error("Timed out waiting for a pooled connection"), |
| 288 | message: "PgPool: Timed out waiting for a pooled connection", |
| 289 | operation: "acquireConnection" |
| 290 | }) |
| 291 | }) |
| 292 | ) |
| 293 | |
| 294 | // The acquisition runs in a child scope, so a timeout or failure gives back |
| 295 | // any lease or reservation it already took instead of leaving them to the |
| 296 | // caller's scope. On success the child scope closes with the caller's. |
| 297 | const withAcquireTimeout = <A>( |
| 298 | effect: Effect.Effect<A, SqlError, Scope.Scope> |
| 299 | ): Effect.Effect<A, SqlError, Scope.Scope> => |
| 300 | acquireTimeout === undefined ? |
| 301 | effect : |
| 302 | Effect.uninterruptibleMask((restore) => |
| 303 | Effect.flatMap(Effect.scope, (parent) => |
| 304 | Effect.flatMap(Scope.fork(parent), (scope) => |
| 305 | Effect.onError( |
| 306 | restore(Effect.timeoutOrElse(Scope.provide(effect, scope), { |
| 307 | duration: acquireTimeout, |
| 308 | orElse: acquireTimedOut |
| 309 | })), |
| 310 | (cause) => Scope.close(scope, Exit.failCause(cause)) |
| 311 | ))) |
| 312 | ) |
| 313 | |
| 314 | const handedOut = Effect.flatMap(checkout, handOut) |
| 315 | const get = withAcquireTimeout(handedOut) |
| 316 | |
| 317 | // `pin` reserves the pool item itself. On a multiplexed pool it also waits |
| 318 | // for shared statements to drain, so the acquire timeout covers it too. |
| 319 | const reserve = withAcquireTimeout(Effect.flatMap(handedOut, (connection) => connection.pin)) |
| 320 | |
| 321 | // `Pool.use` cannot pre-check a session or bound its wait. Use it only when |
| 322 | // no TTL or acquire timeout applies and no connection awaits retirement. |
| 323 | // Checking inside its callback can deadlock a size-one pool while acquiring |
| 324 | // a replacement. |
| 325 | const use = <A, E, R>( |
| 326 | f: (connection: PgConnection.PgConnection) => Effect.Effect<A, E, R> |
| 327 | ): Effect.Effect<A, E | SqlError, R> => |
| 328 | Effect.suspend(() => |
| 329 | connectionTTL === undefined && acquireTimeout === undefined && deadConnections.size === 0 |
| 330 | ? Pool.use( |
| 331 | pool, |
| 332 | (connection) => |
| 333 | connects.has(connection) ? Effect.andThen(reportConnect(connection), f(connection)) : f(connection) |
| 334 | ) |
| 335 | : Effect.scoped(Effect.flatMap(get, f)) |
| 336 | ) |
| 337 | |
| 338 | const pgPool: PgPool = { |
| 339 | [TypeId]: TypeId, |
| 340 | config: options, |
| 341 | get, |
| 342 | reserve, |
| 343 | use, |
| 344 | invalidate: (connection) => |
| 345 | Pool.invalidate(pool, connectionInternals(connection).base as PgConnection.PgConnection), |
| 346 | stats: Pool.stats(pool) |
| 347 | } |
| 348 | return pgPool |
| 349 | }) |