sailfork / t3code-github / .repos/ effect/ packages/ sql/ pg/ src/ PgPool.ts

/**
 * 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<PgConnection.PgConnection, SqlError, Scope.Scope>
  /**
   * 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<PgConnection.PgConnection, SqlError, Scope.Scope>
  /**
   * 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: <A, E, R>(
    f: (connection: PgConnection.PgConnection) => Effect.Effect<A, E, R>
  ) => Effect.Effect<A, E | SqlError, R>
  readonly invalidate: (connection: PgConnection.PgConnection) => Effect.Effect<void>
  /**
   * 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<Pool.Stats>
}

/**
 * The service tag for `PgPool`.
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export const PgPool = Context.Service<PgPool>("@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<PgPool, SqlError, Scope.Scope> {
  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<PgConnection.PgConnection>()
  const createdAt = new WeakMap<PgConnection.PgConnection, number>()
  const checkedOut = new WeakSet<PgConnection.PgConnection>()

  // 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<PgConnection.PgConnection, readonly [startTime: bigint, endTime: bigint]>()

  const reportConnect = (connection: PgConnection.PgConnection): Effect.Effect<void> =>
    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<PgConnection.PgConnection, SqlError>
  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<PgConnection.PgConnection, SqlError, Scope.Scope> = 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<PgConnection.PgConnection, SqlError, Scope.Scope> = 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 = <A>(
    effect: Effect.Effect<A, SqlError, Scope.Scope>
  ): Effect.Effect<A, SqlError, Scope.Scope> =>
    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 = <A, E, R>(
    f: (connection: PgConnection.PgConnection) => Effect.Effect<A, E, R>
  ): Effect.Effect<A, E | SqlError, R> =>
    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
})