/** * Pools of native `PgConnection` sessions. * * @stability unstable * @since 4.0.0 */ import * as Clock from "effect/Clock" import * as Context from "effect/Context" import * as Duration from "effect/Duration" import * as Effect from "effect/Effect" import * as Exit from "effect/Exit" import * as Option from "effect/Option" import * as Pool from "effect/Pool" import { TracerTimingEnabled } from "effect/References" import * as Scope from "effect/Scope" import { ConnectionError, SqlError } from "effect/sql/SqlError" import { SpanPropagationEnabled } from "effect/sql/Statement" import * as Tracer from "effect/Tracer" import { connectionInternals } from "./internal/connection.ts" import * as PgConnection from "./PgConnection.ts" const defaultMultiplexConcurrency = 32 /** * The runtime type identifier for `PgPool`. * * @stability unstable * @category type IDs * @since 4.0.0 */ export const TypeId: TypeId = "~@effect/sql-pg/PgPool" /** * The type-level identifier for `PgPool`. * * @stability unstable * @category type IDs * @since 4.0.0 */ export type TypeId = "~@effect/sql-pg/PgPool" /** * Connection and sizing settings for a PostgreSQL session pool. * * **Details** * * The defaults are 0 to 10 connections and a 60-second idle timeout. * `connectionTTL` replaces connections that exceed the configured lifetime. * Every connection is used at least once, so a TTL of zero disables reuse. * `acquireTimeout` bounds how long a checkout takes to acquire a connection, * including opening a new one; by default it waits indefinitely. * * With `multiplex` enabled, fibers may share pooled connections for pipelined * queries. Reserved connections remain exclusive. Without multiplexing, every * checkout is exclusive. * * @stability unstable * @category models * @since 4.0.0 */ export interface Config extends PgConnection.Config { readonly idleTimeout?: Duration.Input | undefined readonly maxConnections?: number | undefined readonly minConnections?: number | undefined readonly connectionTTL?: Duration.Input | undefined /** * How long a checkout may take to acquire a connection before failing with * a `ConnectionError`. Acquisition includes waiting for a free connection * and opening a new one when the pool needs it. With `multiplex` on, * `reserve` also waits for statements already sent on the shared connection * to finish, and that wait counts too. Work done with the connection after * it is acquired is not bounded. Unbounded by default. */ readonly acquireTimeout?: Duration.Input | undefined /** * How many statements may share one connection when `multiplex` is on. * Defaults to `32`. Statements are pipelined into one write, so a higher * number means fewer round trips, but it also means a slow statement holds * up more of the statements queued behind it. */ readonly multiplexConcurrency?: number | undefined } /** * A PostgreSQL session pool. * * @stability unstable * @category models * @since 4.0.0 */ export interface PgPool { readonly [TypeId]: TypeId readonly config: Config /** * Checks out a session until the scope closes. Without multiplexing the * checkout is exclusive. With multiplexing the * session may be shared with other fibers, so multi-statement work should * use `reserve` instead. */ readonly get: Effect.Effect /** * Checks out a session for exclusive use until the scope closes. Use this for * transactions and listeners on a multiplexed pool. */ readonly reserve: Effect.Effect /** * Removes a session so the pool can replace it. Fatal protocol and socket * errors invalidate sessions automatically. */ /** * Lends a session for the duration of one effect and takes it back on any * exit, without opening a scope for it. * * **Details** * * For work that finishes with the effect that runs it. A lease that has to * outlive its effect - a stream, a transaction - takes `get` or `reserve`. */ readonly use: ( f: (connection: PgConnection.PgConnection) => Effect.Effect ) => Effect.Effect readonly invalidate: (connection: PgConnection.PgConnection) => Effect.Effect /** * Returns a snapshot of session occupancy. Counts sessions rather than * statements, so a multiplexed session shared by many fibers counts once. A * session that has just failed can show as idle until the pool removes it. */ readonly stats: Effect.Effect } /** * The service tag for `PgPool`. * * @stability unstable * @category services * @since 4.0.0 */ export const PgPool = Context.Service("@effect/sql-pg/PgPool") /** * Creates a scoped PostgreSQL session pool. * * **Details** * * Connections are opened lazily up to `maxConnections` and released down to * `minConnections` after `idleTimeout` without use. Closing the scope shuts * the pool down and releases every session. * * With `SpanPropagationEnabled`, a statement that waited for a new session gets * a `db.connect` child span covering the part of the connect it waited for. * * @stability unstable * @category constructors * @since 4.0.0 */ export const make = Effect.fnUntraced(function*(options: Config): Effect.fn.Return { const clock = yield* Clock.Clock const runFork = Effect.runForkWith(yield* Effect.context()) const multiplex = options.multiplex ?? false const connectionTTL = options.connectionTTL !== undefined ? Duration.toMillis(Duration.fromInputUnsafe(options.connectionTTL)) : undefined const acquireTimeout = options.acquireTimeout !== undefined ? Duration.fromInputUnsafe(options.acquireTimeout) : undefined const deadConnections = new Set() const createdAt = new WeakMap() const checkedOut = new WeakSet() // The pool opens sessions on its own fiber, where a span would have no // statement parent. Each connect is recorded here instead and reported on the // session's first checkout, under the statement that waited for it. const connects = new WeakMap() const reportConnect = (connection: PgConnection.PgConnection): Effect.Effect => Effect.withFiber((fiber) => { const opened = connects.get(connection) if (opened === undefined) return Effect.void connects.delete(connection) const statement = fiber.cache.span // Without span timing the statement span has no start time to measure from. if ( !fiber.cache.tracerEnabled || statement?._tag !== "Span" || !fiber.getRef(SpanPropagationEnabled) || !fiber.getRef(TracerTimingEnabled) ) { return Effect.void } const [startTime, endTime] = opened const waitedFrom = statement.status.startTime if (endTime < waitedFrom) return Effect.void const span = fiber.getRef(Tracer.Tracer).span({ name: "db.connect", parent: Option.some(statement), annotations: Context.empty(), links: [], startTime: startTime > waitedFrom ? startTime : waitedFrom, kind: "client", root: false, sampled: statement.sampled }) span.attribute("db.system.name", "postgresql") span.attribute("db.client.connection.connect_time_ms", Number(endTime - startTime) / 1e6) span.end(endTime, Exit.void) return Effect.void }) const handOut = (connection: PgConnection.PgConnection) => connects.has(connection) ? Effect.as(reportConnect(connection), connection) : Effect.succeed(connection) // Assigned below, once the pool exists. `acquire` only runs when the pool // opens a connection, which is always after that. let pool: Pool.Pool const acquire = Effect.suspend(() => { const startTime = clock.currentTimeNanosUnsafe() return Effect.tap(PgConnection.make(options), (connection) => Effect.sync(() => { connects.set(connection, [startTime, clock.currentTimeNanosUnsafe()]) createdAt.set(connection, clock.currentTimeMillisUnsafe()) const internals = connectionInternals(connection) internals.retireHooks.add(() => { deadConnections.add(connection) // `deadConnections` is only read by the next checkout, and a checkout // already waiting for this connection would never get that far. Tell // the pool now so it can replace the connection and admit them. runFork(Pool.invalidate(pool, connection)) }) // Pinning a shared session has to take it out of circulation, or a // second checkout lands on the connection its own stream is holding. if (multiplex) internals.reserve = Pool.reserve(pool, connection) })) }) const maxConnections = options.maxConnections ?? 10 pool = yield* Pool.makeWithTTL({ acquire, min: options.minConnections ?? 0, max: maxConnections, concurrency: multiplex ? Math.max(1, options.multiplexConcurrency ?? defaultMultiplexConcurrency) : 1, timeToLive: options.idleTimeout ?? Duration.seconds(60), timeToLiveStrategy: "usage" }) const expired = (connection: PgConnection.PgConnection): boolean => { if (connectionInternals(connection).deadError() !== undefined) return true if (connectionTTL === undefined) return false if (!checkedOut.has(connection)) { checkedOut.add(connection) return false } const openedAt = createdAt.get(connection) return openedAt !== undefined && clock.currentTimeMillisUnsafe() - openedAt >= connectionTTL } // A checkout runs per statement, so the case where nothing has died and the // first connection is usable stays a plain flatMap; retrying is the // exception and pays for the loop. const retry: Effect.Effect = Effect.gen(function*() { while (true) { if (deadConnections.size > 0) { const dead = Array.from(deadConnections) deadConnections.clear() yield* Effect.forEach(dead, (connection) => Pool.invalidate(pool, connection), { discard: true }) } const connection = yield* Pool.get(pool) if (expired(connection)) { yield* Pool.invalidate(pool, connection) continue } return connection } }) const checkout: Effect.Effect = Effect.suspend(() => deadConnections.size > 0 ? retry : Effect.flatMap(Pool.get(pool), (connection) => expired(connection) ? Effect.andThen(Pool.invalidate(pool, connection), retry) : Effect.succeed(connection)) ) const acquireTimedOut = () => Effect.fail( new SqlError({ reason: new ConnectionError({ cause: new Error("Timed out waiting for a pooled connection"), message: "PgPool: Timed out waiting for a pooled connection", operation: "acquireConnection" }) }) ) // The acquisition runs in a child scope, so a timeout or failure gives back // any lease or reservation it already took instead of leaving them to the // caller's scope. On success the child scope closes with the caller's. const withAcquireTimeout = ( effect: Effect.Effect ): Effect.Effect => acquireTimeout === undefined ? effect : Effect.uninterruptibleMask((restore) => Effect.flatMap(Effect.scope, (parent) => Effect.flatMap(Scope.fork(parent), (scope) => Effect.onError( restore(Effect.timeoutOrElse(Scope.provide(effect, scope), { duration: acquireTimeout, orElse: acquireTimedOut })), (cause) => Scope.close(scope, Exit.failCause(cause)) ))) ) const handedOut = Effect.flatMap(checkout, handOut) const get = withAcquireTimeout(handedOut) // `pin` reserves the pool item itself. On a multiplexed pool it also waits // for shared statements to drain, so the acquire timeout covers it too. const reserve = withAcquireTimeout(Effect.flatMap(handedOut, (connection) => connection.pin)) // `Pool.use` cannot pre-check a session or bound its wait. Use it only when // no TTL or acquire timeout applies and no connection awaits retirement. // Checking inside its callback can deadlock a size-one pool while acquiring // a replacement. const use = ( f: (connection: PgConnection.PgConnection) => Effect.Effect ): Effect.Effect => Effect.suspend(() => connectionTTL === undefined && acquireTimeout === undefined && deadConnections.size === 0 ? Pool.use( pool, (connection) => connects.has(connection) ? Effect.andThen(reportConnect(connection), f(connection)) : f(connection) ) : Effect.scoped(Effect.flatMap(get, f)) ) const pgPool: PgPool = { [TypeId]: TypeId, config: options, get, reserve, use, invalidate: (connection) => Pool.invalidate(pool, connectionInternals(connection).base as PgConnection.PgConnection), stats: Pool.stats(pool) } return pgPool })