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

/**
 * Native PostgreSQL sessions built on the `PgProtocol` wire codec.
 *
 * **Details**
 *
 * Sessions support queries, streaming, `LISTEN`/`NOTIFY`, cancellation, and
 * exclusive ownership for transactions.
 *
 * @stability unstable
 * @since 4.0.0
 */
import type * as Arr from "effect/Array"
import * as Cause from "effect/Cause"
import * as Channel from "effect/Channel"
import * as Context from "effect/Context"
import * as Deferred from "effect/Deferred"
import type * as Duration from "effect/Duration"
import * as Effect from "effect/Effect"
import * as Exit from "effect/Exit"
import * as Queue from "effect/Queue"
import type * as Redacted from "effect/Redacted"
import * as EffectResult from "effect/Result"
import * as Scheduler from "effect/Scheduler"
import * as Scope from "effect/Scope"
import * as Semaphore from "effect/Semaphore"
import { AuthenticationError, ConnectionError, SqlError, type SqlErrorReason, UnknownError } from "effect/sql/SqlError"
import * as Stream from "effect/Stream"
import { Buffer } from "node:buffer"
import { randomBytes } from "node:crypto"
import * as Net from "node:net"
import type { Duplex } from "node:stream"
import * as Tls from "node:tls"
import type { ConnectionOptions } from "node:tls"
import { resolveConfig, type ResolvedConfig } from "./internal/config.ts"
import { type ConnectionInternals, internalsKey } from "./internal/connection.ts"
import * as PasswordInternal from "./internal/password.ts"
import { classifySqlState, validateChannelName } from "./internal/sqlError.ts"
import * as PgAuth from "./PgAuth.ts"
import * as PgProtocol from "./PgProtocol.ts"
import * as PgTypes from "./PgTypes.ts"

/**
 * The runtime type identifier for `PgConnection`.
 *
 * @stability unstable
 * @category type IDs
 * @since 4.0.0
 */
export const TypeId: TypeId = "~@effect/sql-pg/PgConnection"

/**
 * The type-level identifier for `PgConnection`.
 *
 * @stability unstable
 * @category type IDs
 * @since 4.0.0
 */
export type TypeId = "~@effect/sql-pg/PgConnection"

/**
 * Connection settings for a PostgreSQL session.
 *
 * **Details**
 *
 * A `url` is parsed as a libpq URI (`postgres://` or `postgresql://`);
 * explicit fields win over anything the URL carries. A `stream` factory wins
 * over `host`, `port`, and `path`. A `path` is used verbatim as the unix
 * socket path, while a `host` beginning with `/` is treated as a socket
 * directory and expands to `${host}/.s.PGSQL.${port}`.
 *
 * URL modes `sslmode=prefer` and `sslmode=allow` try TLS first, falling back
 * to plaintext only when the server answers `SSLRequest` with `N`. Unlike
 * libpq, `allow` also tries TLS first. Certificate verification stays enabled
 * unless explicitly disabled through `ssl` options.
 *
 * Prepared statements are enabled by default and limited by
 * `preparedStatementCacheSize`. Disable them for poolers that drop named
 * statements, such as PgBouncer with `max_prepared_statements = 0`, or for
 * workloads that generate unique SQL. Streams always use unnamed statements.
 *
 * With `multiplex` enabled, unpinned queries from multiple fibers are
 * pipelined. Transactions, streams, and listeners remain exclusive. An
 * unpinned multiplexed connection cannot be interrupted because cancellation
 * could affect another fiber's query.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface Config {
  readonly url?: Redacted.Redacted | undefined
  readonly host?: string | undefined
  readonly port?: number | undefined
  readonly path?: string | undefined
  readonly ssl?: boolean | ConnectionOptions | undefined
  readonly database?: string | undefined
  readonly username?: string | undefined
  /**
   * A static password or an Effect evaluated for each connection attempt.
   * Providers must handle typed errors and require no services.
   * {@link Effect.orDie} converts typed errors to defects, not retryable SQL errors.
   */
  readonly password?: Redacted.Redacted | Effect.Effect<Redacted.Redacted> | undefined
  readonly connectTimeout?: Duration.Input | undefined
  /**
   * Enables TCP keepalive on native TCP connections after this idle time.
   *
   * **Details**
   *
   * The duration is truncated to whole seconds (minimum 1 second). With Node's
   * defaults, the connection errors after 10 unanswered probes sent 1 second
   * apart. Disabled when omitted; Unix sockets and custom streams are unaffected.
   *
   * This is not a query timeout. Probes only run while no sent data is awaiting
   * acknowledgement, so use `Effect.timeout` to bound a write to a dead peer.
   */
  readonly keepAlive?: Duration.Input | undefined
  /**
   * Overrides `startupParameters.application_name`, the URL's `application_name`,
   * and the default `"@effect/sql-pg"`, in that order.
   */
  readonly applicationName?: string | undefined
  /**
   * Session defaults sent in every physical connection's startup packet.
   * Names are lowercased; `user`, `database`, `replication`, and `options` are
   * reserved. `client_encoding` only accepts UTF8 / UTF-8 (case-insensitive).
   * Empty names and NUL bytes fail before connecting; PostgreSQL validates
   * other settings. Do not set the same GUC here and in `startupOptions`.
   */
  readonly startupParameters?: Readonly<Record<string, string>> | undefined
  /**
   * Opaque PostgreSQL startup options, overriding the URL's `options` parameter.
   * Forwarded without parsing `-c` flags or checking for duplicate GUCs.
   */
  readonly startupOptions?: string | undefined
  readonly stream?: (() => Duplex) | undefined
  readonly types?: PgTypes.Registry | undefined
  readonly multiplex?: boolean | undefined
  readonly prepare?: boolean | undefined
  readonly preparedStatementCacheSize?: number | undefined
  /** Maximum backend message size in bytes. Defaults to 16 MiB. */
  readonly maxMessageSize?: number | undefined
}

/**
 * Builds the prepared-statement cache a session should use, or `undefined`
 * when `prepare` is off or the cache is sized to nothing.
 */
const preparedCacheFor = (config: Config): PreparedCache | undefined => {
  if (config.prepare === false) return undefined
  const max = config.preparedStatementCacheSize ?? defaultPreparedStatements
  return max > 0 ? new PreparedCache(max) : undefined
}

/**
 * An object result row keyed by column name.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface Row {
  readonly [column: string]: unknown
}

/**
 * Metadata for one result column.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface Field {
  readonly name: string
  readonly dataTypeId: number
}

/**
 * The result of a query.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface Result {
  readonly command: string
  readonly rowCount: number
  readonly oid: number | null
  readonly rows: ReadonlyArray<Row>
  readonly fields: ReadonlyArray<Field>
}

/**
 * A `NOTIFY` message received while listening on a channel.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface Notification {
  readonly processId: number
  readonly channel: string
  readonly payload: string
}

/**
 * A connected and authenticated PostgreSQL session.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface PgConnection {
  readonly [TypeId]: TypeId
  readonly config: Config
  readonly processId: number
  /**
   * Reserves the session for exclusive use until the scope closes. Pinning is
   * reentrant. Calls through the returned connection skip the
   * ownership queue, while calls through the original connection wait.
   *
   * **Details**
   *
   * After release, queries, streams and listeners through the returned
   * connection fail, and its `interrupt` does nothing. Releasing a pin with
   * an in-flight statement or an open listener closes the session and fails
   * any listener queues, as does leaving a transaction the pin began aborted.
   */
  readonly pin: Effect.Effect<PgConnection, never, Scope.Scope>
  /**
   * Runs a query and returns rows keyed by column name. Pass `false` to skip
   * the prepared statement cache.
   *
   * **Details**
   *
   * On interruption, the connection drains to `ReadyForQuery` and sends a
   * `CancelRequest` if needed. Unless the backend confirms cancellation with
   * `57014`, a pool retires the session before its next checkout. A retained
   * checkout and an unpooled session remain exposed to a late cancel.
   * `statement_timeout` also reports `57014` and can be mistaken for
   * confirmation.
   */
  readonly query: (
    sql: string,
    params?: ReadonlyArray<unknown>,
    prepare?: boolean
  ) => Effect.Effect<Result, SqlError>
  /**
   * Runs a query and returns positional rows. Pass `false` to skip the
   * prepared statement cache. Interruption behaves as for `query`.
   */
  readonly queryValues: (
    sql: string,
    params?: ReadonlyArray<unknown>,
    prepare?: boolean
  ) => Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>
  /**
   * Streams rows without collecting the full result. The session is pinned for
   * the lifetime of the stream. An early abort behaves like an interrupted
   * `query`.
   */
  readonly stream: (
    sql: string,
    params?: ReadonlyArray<unknown>
  ) => Stream.Stream<Row, SqlError>
  /**
   * Registers a channel listener and returns its notification queue after
   * PostgreSQL confirms `LISTEN`. The session stays pinned until the scope
   * closes, when it runs `UNLISTEN` and shuts down the queue. A session that
   * does not confirm `UNLISTEN` within 5 seconds is closed. PostgreSQL
   * registration errors fail the acquiring effect.
   * Connection failures after registration fail the queue with the original
   * `SqlError`. Intentional scope closure interrupts consumers.
   */
  readonly listen: (
    channel: string
  ) => Effect.Effect<Queue.Dequeue<Notification, SqlError>, SqlError, Scope.Scope>
  /**
   * Attempts to cancel the active query through a side connection. This is a
   * no-op for an unpinned multiplexed connection because the active
   * query may belong to another fiber. The effect never fails.
   */
  readonly interrupt: Effect.Effect<void>
}

/**
 * The service tag for `PgConnection`.
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export const PgConnection = Context.Service<PgConnection>("@effect/sql-pg/PgConnection")

/**
 * Connects and authenticates a single PostgreSQL session.
 *
 * **Details**
 *
 * Password resolution, transport, optional `SSLRequest`, startup, and
 * authentication run under `connectTimeout` (5 seconds by default). The effect
 * resolves when the backend sends `ReadyForQuery`. Closing the scope sends
 * `Terminate` and ends the socket.
 *
 * Use `sslmode=require` or explicit `ssl: true` to require encryption.
 * Unix sockets and custom streams should set `ssl.servername` explicitly.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const make = (options: Config): Effect.Effect<PgConnection, SqlError, Scope.Scope> =>
  Effect.flatMap(resolveConfig(options), (config) =>
    Effect.acquireRelease(
      Effect.gen(function*() {
        const password = yield* PasswordInternal.resolve(config.password)
        const session = yield* connect(config, password)
        return new PgConnectionImpl(options, config, session, options.types)
      }),
      (connection) => Effect.sync(() => connection.closeUnsafe()),
      { interruptible: true }
    ).pipe(
      Effect.timeoutOrElse({
        duration: config.connectTimeout,
        orElse: () =>
          Effect.fail(
            new SqlError({
              reason: new ConnectionError({
                cause: new Error("Connection timed out"),
                message: "PgConnection: Connection timed out",
                operation: "connect"
              })
            })
          )
      })
    ))

interface Session {
  readonly socket: Duplex
  readonly encrypted: boolean
  readonly parser: PgProtocol.Parser<unknown>
  readonly processId: number
  readonly secretKey: number
}

/**
 * The active protocol consumer: the state machine of the statement currently
 * on the wire. Messages the pump does not handle itself are forwarded here.
 */
interface Consumer {
  readonly onMessage: (message: PgProtocol.BackendMessage<unknown>) => void
  readonly onBatchEnd?: (() => void) | undefined
  readonly onFatal: (error: SqlError) => void
}

/** One statement waiting in, or travelling through, a multiplexed pipeline. */
interface PipelineEntry {
  readonly plan: Plan
  readonly deferred: Deferred.Deferred<QueryOutput, SqlError>
  readonly machine: QueryMachine
  abandoned: boolean
}

const abortDrainTimeoutMillis = 5000
const abortDrainGraceMillis = 10
/** PostgreSQL `query_canceled` SQLSTATE. */
const queryCanceledCode = "57014"
const cancelRequestTimeoutMillis = 5000
const unlistenTimeoutMillis = 5000
/** How many statements a multiplexed session keeps on the wire at once. */
const maxPipelineDepth = 128
const streamPauseThreshold = 512

class PgConnectionImpl implements PgConnection {
  readonly [TypeId]: TypeId = TypeId
  readonly config: Config
  readonly processId: number
  readonly session: Session
  /** The custom codec registry, or `undefined` for the builtin catalogue. */
  readonly registry: PgTypes.Registry | undefined
  readonly bindEncoder: BindEncoder
  /** The statements this session has named, or `undefined` when disabled. */
  readonly prepared: PreparedCache | undefined
  readonly resolved: ResolvedConfig
  readonly multiplex: boolean
  /** Serializes statements: one in-flight extended-query cycle. */
  readonly wire = Semaphore.makeUnsafe(1)
  /** Exclusive-ownership queue used by `pin` and unpinned statements. */
  readonly owner = Semaphore.makeUnsafe(1)
  pinned = false
  consumer: Consumer | undefined
  deadWith: SqlError | undefined
  closed = false
  cancelPending = false
  /** Reported by the latest `ReadyForQuery`. */
  transactionStatus: PgProtocol.TransactionStatus = "I"
  readonly channels = new Map<string, Set<Queue.Queue<Notification, SqlError>>>()
  readonly retireHooks = new Set<() => void>()
  /** Queued but not yet written; drained into `pipelineInFlight` on flush. */
  readonly pipelinePending: Array<PipelineEntry> = []
  /** Written and awaiting their `ReadyForQuery`, oldest first. */
  readonly pipelineInFlight: Array<PipelineEntry> = []
  pipelineHead = 0
  pipelineFlushScheduled = false
  readonly pipelineIdleWaiters = new Set<() => void>()
  readonly [internalsKey]: ConnectionInternals

  constructor(config: Config, resolved: ResolvedConfig, session: Session, registry: PgTypes.Registry | undefined) {
    this.config = config
    this.resolved = resolved
    this.session = session
    this.processId = session.processId
    this.registry = registry
    this.bindEncoder = makeBindEncoder(registry)
    this.prepared = preparedCacheFor(config)
    this.multiplex = config.multiplex ?? false
    this[internalsKey] = {
      base: this,
      deadError: () => this.deadWith,
      retireHooks: this.retireHooks
    }
    session.socket.on("data", this.onData)
    session.socket.on("error", this.onSocketError)
    session.socket.on("close", this.onSocketClose)
  }

  private readonly onData = (chunk: Uint8Array): void => {
    try {
      this.session.parser.pushEach(chunk, this.dispatch)
    } catch (cause) {
      // A field reader that threw reports the row it could not decode; anything
      // else came out of the framing itself.
      return this.fatal(
        cause instanceof PgProtocol.ParseError
          ? connectionQueryError(cause, "PgConnection: Failed to parse server messages")
          : queryError(cause, "PgConnection: Failed to decode row")
      )
    }
    if (this.deadWith === undefined) this.consumer?.onBatchEnd?.()
  }

  private readonly onSocketError = (cause: Error): void =>
    this.fatal(connectionQueryError(cause, "PgConnection: Socket error"))

  private readonly onSocketClose = (): void =>
    this.fatal(connectionQueryError(new Error("Connection closed"), "PgConnection: Connection closed"))

  private readonly dispatch = (message: PgProtocol.BackendMessage<unknown>): void => {
    if (this.deadWith !== undefined) return
    switch (message._tag) {
      case "ErrorResponse":
        if (message.fields.code === queryCanceledCode) this.cancelPending = false
        break
      case "ReadyForQuery":
        this.transactionStatus = message.status
        if (this.cancelPending) {
          this.cancelPending = false
          this.retire()
        }
        break
      case "NotificationResponse": {
        const queues = this.channels.get(message.channel)
        if (queues !== undefined) {
          const notification: Notification = {
            processId: message.pid,
            channel: message.channel,
            payload: message.payload
          }
          for (const queue of queues) Queue.offerUnsafe(queue, notification)
        }
        return
      }
      case "ParameterStatus":
      case "NoticeResponse":
        return
    }
    if (this.consumer !== undefined) return this.consumer.onMessage(message)
    if (message._tag === "ErrorResponse") {
      return this.fatal(
        new SqlError({
          reason: classifyFields(message.fields, "PgConnection: The server reported an error", "query")
        })
      )
    }
    this.fatal(
      connectionQueryError(
        new Error(`Unexpected ${message._tag} while idle`),
        `PgConnection: Unexpected ${message._tag} while idle`
      )
    )
  }

  /** Marks the session dead: optionally destroys the socket, fails the active statement
   * and every listen queue, and notifies pool hooks unless the session's own
   * scope is being released. */
  fatal(error: SqlError, destroySocket = true): void {
    if (this.deadWith !== undefined) return
    this.deadWith = error
    if (destroySocket) this.session.socket.destroy()
    const consumer = this.consumer
    this.consumer = undefined
    this.retire()
    consumer?.onFatal(error)
    const sets = Array.from(this.channels.values())
    this.channels.clear()
    const cause = this.closed ? Cause.interrupt() : Cause.fail(error)
    for (const set of sets) {
      for (const queue of set) Queue.failCauseUnsafe(queue, cause)
    }
  }

  private retire(): void {
    if (this.closed) return
    for (const hook of this.retireHooks) hook()
  }

  closeUnsafe(): void {
    this.closed = true
    let destroySocket = true
    if (this.deadWith === undefined && this.session.socket.writable) {
      try {
        this.session.socket.end(PgProtocol.encodeTerminate())
        destroySocket = false
      } catch {
        // Fall back to the fatal path's immediate destroy below.
      }
    }
    this.fatal(
      new SqlError({
        reason: new ConnectionError({
          cause: new Error("Connection is closed"),
          message: "PgConnection: Connection is closed",
          operation: "query"
        })
      }),
      destroySocket
    )
    const socket = this.session.socket
    socket.off("data", this.onData)
    socket.off("error", this.onSocketError)
    socket.off("close", this.onSocketClose)
    this.retireHooks.clear()
  }

  /** Plans one execution. `cache` is `undefined` to force the unnamed path. */
  readonly encodeQuery = (
    sql: string,
    params: ReadonlyArray<unknown>,
    cache: PreparedCache | undefined
  ): Plan => encodeQuery(sql, params, this.registry, this.bindEncoder, cache)

  /**
   * Routes backend messages to the oldest statement still on the wire.
   *
   * Every cycle carries its own `Sync`, so the backend answers them in order
   * and finishes each with a `ReadyForQuery`. That boundary is what advances
   * the queue, and it is also why a statement the backend rejects only skips
   * the rest of its own cycle: the ones queued behind it still run.
   */
  private readonly pipelineConsumer: Consumer = {
    onMessage: (message) => {
      const entry = this.pipelineInFlight[this.pipelineHead]
      if (entry === undefined) {
        return this.fatal(connectionQueryError(
          new Error(`Unexpected ${message._tag} without an in-flight query`),
          `PgConnection: Unexpected ${message._tag} without an in-flight query`
        ))
      }
      entry.machine.onMessage(message)
    },
    onBatchEnd: () => this.flushPipeline(),
    onFatal: (error) => {
      const entries = [
        ...this.pipelineInFlight.slice(this.pipelineHead),
        ...this.pipelinePending
      ]
      this.pipelineInFlight.length = 0
      this.pipelineHead = 0
      this.pipelinePending.length = 0
      this.pipelineFlushScheduled = false
      for (const entry of entries) {
        if (!entry.abandoned) Deferred.doneUnsafe(entry.deferred, Effect.fail(error))
      }
      this.notifyPipelineIdle()
    }
  }

  private readonly pipelineDepth = (): number => this.pipelineInFlight.length - this.pipelineHead

  private readonly pipelineIsIdle = (): boolean => this.pipelineDepth() === 0 && this.pipelinePending.length === 0

  private readonly notifyPipelineIdle = (): void => {
    if (!this.pipelineIsIdle()) return
    this.consumer = undefined
    this.session.parser.readField = undefined
    const waiters = Array.from(this.pipelineIdleWaiters)
    this.pipelineIdleWaiters.clear()
    for (const waiter of waiters) waiter()
  }

  /** Resolves once nothing is on the wire, so `pin` can take the connection. */
  readonly waitPipelineIdle: Effect.Effect<void> = Effect.callback((resume) => {
    if (this.pipelineIsIdle()) return resume(Effect.void)
    const waiter = () => resume(Effect.void)
    this.pipelineIdleWaiters.add(waiter)
    return Effect.sync(() => this.pipelineIdleWaiters.delete(waiter))
  })

  private readonly finishPipelineEntry = (
    entry: PipelineEntry,
    result: Effect.Effect<QueryOutput, SqlError>
  ): void => {
    if (this.pipelineInFlight[this.pipelineHead] !== entry) {
      return this.fatal(connectionQueryError(
        new Error("A pipelined query completed out of order"),
        "PgConnection: A pipelined query completed out of order"
      ))
    }
    this.pipelineHead++
    // The next statement's rows can be in this same chunk, so its reader has to
    // be in place before the parser reads on.
    this.session.parser.readField = this.pipelineInFlight[this.pipelineHead]?.machine.readField
    if (!entry.abandoned) Deferred.doneUnsafe(entry.deferred, result)
    if (this.pipelineHead === this.pipelineInFlight.length) {
      this.pipelineInFlight.length = 0
      this.pipelineHead = 0
    }
  }

  /** Writes everything queued since the last flush as one batch. */
  private readonly flushPipeline = (): void => {
    this.pipelineFlushScheduled = false
    if (this.deadWith !== undefined) return
    let capacity = maxPipelineDepth - this.pipelineDepth()
    if (capacity <= 0) return
    const wasEmpty = this.pipelineDepth() === 0
    const batch: Array<PipelineEntry> = []
    let index = 0
    while (capacity > 0 && index < this.pipelinePending.length) {
      const entry = this.pipelinePending[index++]
      if (entry.abandoned) {
        if (entry.plan.parses && entry.plan.prepared !== undefined) {
          entry.plan.prepared.parsing = false
        }
        continue
      }
      batch.push(entry)
      this.pipelineInFlight.push(entry)
      capacity--
    }
    this.pipelinePending.splice(0, index)
    if (batch.length === 0) {
      this.notifyPipelineIdle()
      return
    }
    if (wasEmpty) this.session.parser.readField = batch[0].machine.readField
    const frame = batch.length === 1
      ? batch[0].plan.frame
      : concat(batch.map((entry) => entry.plan.frame))
    try {
      this.session.socket.write(frame)
    } catch (cause) {
      this.fatal(connectionQueryError(cause, "PgConnection: Failed to write query batch"))
    }
  }

  private readonly schedulePipelineFlush = (): void => {
    if (this.pipelineFlushScheduled || this.pipelineDepth() >= maxPipelineDepth) return
    this.pipelineFlushScheduled = true
    // A microtask is what lets fibers submitted in the same tick share a write.
    queueMicrotask(this.flushPipeline)
  }

  /**
   * One cycle on a multiplexed connection. The `owner` permit is only taken to
   * queue the statement, so a pin still orders against submissions without
   * serializing them.
   */
  private readonly pipelineCycle = (
    sql: string,
    params: ReadonlyArray<unknown>,
    wantRows: boolean,
    cache: PreparedCache | undefined
  ): Effect.Effect<QueryOutput, SqlError> =>
    Effect.flatMap(
      this.owner.withPermit(Effect.suspend(() => {
        if (this.deadWith !== undefined) return Effect.fail(this.deadWith)
        let plan: Plan
        try {
          plan = this.encodeQuery(sql, params, cache)
        } catch (cause) {
          return Effect.fail(queryError(cause, "PgConnection: Failed to encode query"))
        }
        const deferred = Deferred.makeUnsafe<QueryOutput, SqlError>()
        let entry: PipelineEntry
        const machine = new QueryMachine(this, plan, wantRows, (result) => this.finishPipelineEntry(entry, result))
        entry = { plan, deferred, machine, abandoned: false }
        this.pipelinePending.push(entry)
        this.consumer = this.pipelineConsumer
        this.schedulePipelineFlush()
        return Effect.succeed(entry)
      })),
      (entry) => {
        const awaited = Deferred.await(entry.deferred).pipe(
          Effect.onInterrupt(() =>
            Effect.sync(() => {
              entry.abandoned = true
            })
          )
        )
        if (cache === undefined || entry.plan.parses) return awaited
        return retryStale(entry.plan, cache, awaited, () => this.pipelineCycle(sql, params, wantRows, undefined))
      }
    )

  /**
   * Runs one cycle for a caller that owns the session. No wire permit is needed
   * because competing pinned work and streams must acquire `owner` first.
   */
  readonly cycleOwned = (
    sql: string,
    params: ReadonlyArray<unknown>,
    wantRows: boolean,
    cache: PreparedCache | undefined
  ): Effect.Effect<QueryOutput, SqlError> => Effect.suspend(() => this.attempt(sql, params, wantRows, cache))

  /**
   * Runs one cycle. A reused statement the backend has since dropped, or whose
   * plan no longer matches its columns, is parsed again on a second attempt;
   * that attempt skips the cache, so it cannot loop.
   */
  private readonly attempt = (
    sql: string,
    params: ReadonlyArray<unknown>,
    wantRows: boolean,
    cache: PreparedCache | undefined
  ): Effect.Effect<QueryOutput, SqlError> => {
    if (this.deadWith !== undefined) return Effect.fail(this.deadWith)
    let plan: Plan
    try {
      plan = this.encodeQuery(sql, params, cache)
    } catch (cause) {
      return Effect.fail(queryError(cause, "PgConnection: Failed to encode query"))
    }
    const run = runQuery(this, plan, wantRows)
    if (cache === undefined || plan.parses) return run
    return retryStale(plan, cache, run, () => this.attempt(sql, params, wantRows, undefined))
  }

  /** Sends a `CancelRequest` for this session on a side connection. */
  readonly cancel: Effect.Effect<void> = Effect.suspend(() => {
    if (this.deadWith !== undefined) return Effect.void
    this.cancelPending = true
    if (this.consumer === undefined) this.retire()
    return sendCancelRequest(this.resolved, this.session)
  })

  readonly pin: Effect.Effect<PinnedPgConnection, never, Scope.Scope> = Effect.suspend(() => {
    const reserve = this[internalsKey].reserve
    return reserve === undefined ? this.pinExclusive : Effect.andThen(reserve, this.pinExclusive)
  })

  // Only the waits are interruptible, so a caller can bound how long it waits
  // for the connection without leaking the `owner` permit.
  private readonly pinExclusive: Effect.Effect<PinnedPgConnection, never, Scope.Scope> = Effect.acquireRelease(
    Effect.uninterruptibleMask((restore) =>
      Effect.flatMap(restore(this.owner.take(1)), () =>
        // Holding `owner` stops new submissions; a pipeline already on the wire
        // still has to drain before this fiber owns the connection.
        Effect.map(
          Effect.onInterrupt(restore(this.waitPipelineIdle), () => this.owner.release(1)),
          () => {
            this.pinned = true
            return new PinnedPgConnection(this)
          }
        ))
    ),
    (view) =>
      Effect.flatMap(
        Effect.suspend(() => {
          view.released = true
          this.pinned = false
          // An `UNLISTEN` that took the wire before the release is bounded by its
          // own timeout, so wait for it rather than treating it as leaked work.
          return view.unlistening > 0 ? Effect.as(this.wire.take(1), true) : this.wire.takeIfAvailable(1)
        }),
        (idle) => {
          // Retire rather than wait indefinitely for leaked work to finish.
          if (!idle || view.listeners > 0) {
            this.fatal(connectionQueryError(
              new Error("Pinned connection released with work outstanding"),
              "PgConnection: Pinned connection released with work outstanding"
            ))
          } else if (view.startedIdle && this.transactionStatus === "E") {
            // A failed cleanup, such as a cancelled `ROLLBACK`, leaves every later
            // statement failing. A transaction open before the pin is its caller's.
            this.fatal(connectionQueryError(
              new Error("Pinned connection released in an aborted transaction"),
              "PgConnection: Pinned connection released in an aborted transaction"
            ))
          }
          return idle ? Effect.andThen(this.wire.release(1), this.owner.release(1)) : this.owner.release(1)
        }
      ),
    { interruptible: true }
  )

  private readonly run = (
    sql: string,
    params: ReadonlyArray<unknown>,
    wantRows: boolean,
    prepare: boolean
  ): Effect.Effect<QueryOutput, SqlError> => {
    const cache = prepare ? this.prepared : undefined
    return this.multiplex
      ? this.pipelineCycle(sql, params, wantRows, cache)
      : this.owner.withPermit(this.cycleOwned(sql, params, wantRows, cache))
  }

  readonly query = (sql: string, params?: ReadonlyArray<unknown>, prepare = true): Effect.Effect<Result, SqlError> =>
    Effect.map(this.run(sql, params ?? emptyParams, true, prepare), takeResult)

  readonly queryValues = (
    sql: string,
    params?: ReadonlyArray<unknown>,
    prepare = true
  ): Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError> =>
    Effect.map(this.run(sql, params ?? emptyParams, false, prepare), takeValues)

  readonly stream = (sql: string, params?: ReadonlyArray<unknown>): Stream.Stream<Row, SqlError> =>
    streamRows(this, this.pin, sql, params ?? emptyParams)

  readonly listen = (
    channel: string
  ): Effect.Effect<Queue.Dequeue<Notification, SqlError>, SqlError, Scope.Scope> =>
    listenChannel(this, this.pin, channel)

  readonly interrupt: Effect.Effect<void> = Effect.suspend(() =>
    this.multiplex && !this.pinned ? Effect.void : this.cancel
  )
}

/**
 * The view of a session returned by `pin`: statements skip the ownership
 * queue and re-pinning is a no-op, making `pin` reentrant for `stream` and
 * `listen` running inside a transaction.
 */
class PinnedPgConnection implements PgConnection {
  readonly [TypeId]: TypeId = TypeId
  readonly base: PgConnectionImpl
  readonly [internalsKey]: ConnectionInternals
  readonly pin: Effect.Effect<PinnedPgConnection, never, Scope.Scope>
  released = false
  listeners = 0
  unlistening = 0
  /** No transaction was open when the pin took the session. */
  readonly startedIdle: boolean

  constructor(base: PgConnectionImpl) {
    this.base = base
    this[internalsKey] = base[internalsKey]
    this.pin = Effect.succeed(this)
    this.startedIdle = base.transactionStatus === "I"
  }

  // Check the lease under the wire permit so queued work cannot run after release.
  private cycle(
    sql: string,
    params: ReadonlyArray<unknown>,
    wantRows: boolean,
    prepare: boolean
  ): Effect.Effect<QueryOutput, SqlError> {
    return this.base.wire.withPermit(Effect.suspend(() =>
      this.released
        ? Effect.fail(pinReleasedError())
        : this.base.cycleOwned(sql, params, wantRows, prepare ? this.base.prepared : undefined)
    ))
  }

  readonly interrupt: Effect.Effect<void> = Effect.suspend(() => this.released ? Effect.void : this.base.cancel)

  get config(): Config {
    return this.base.config
  }

  get processId(): number {
    return this.base.processId
  }

  readonly query = (sql: string, params?: ReadonlyArray<unknown>, prepare = true): Effect.Effect<Result, SqlError> =>
    Effect.map(this.cycle(sql, params ?? emptyParams, true, prepare), takeResult)

  readonly queryValues = (
    sql: string,
    params?: ReadonlyArray<unknown>,
    prepare = true
  ): Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError> =>
    Effect.map(this.cycle(sql, params ?? emptyParams, false, prepare), takeValues)

  readonly stream = (sql: string, params?: ReadonlyArray<unknown>): Stream.Stream<Row, SqlError> =>
    streamRows(this.base, this.pin, sql, params ?? emptyParams)

  readonly listen = (
    channel: string
  ): Effect.Effect<Queue.Dequeue<Notification, SqlError>, SqlError, Scope.Scope> =>
    listenChannel(this.base, this.pin, channel)
}

interface QueryOutput {
  readonly result: Result
  readonly values: ReadonlyArray<ReadonlyArray<unknown>>
}

const INT32_MIN = -2147483648
const INT32_MAX = 2147483647

const inferredParameter = (oid: number, value: unknown): PgTypes.Parameter => ({
  [PgTypes.ParameterTypeId]: PgTypes.ParameterTypeId,
  oid,
  value
})

const inferScalar = (value: unknown): PgTypes.Parameter => {
  if (PgTypes.isParameter(value)) return value
  if (value === null || value === undefined) return inferredParameter(0, null)
  switch (typeof value) {
    case "boolean":
      return inferredParameter(PgTypes.OID.bool, value)
    case "bigint":
      return inferredParameter(PgTypes.OID.int8, value)
    case "number":
      if (Number.isInteger(value)) {
        if (value >= INT32_MIN && value <= INT32_MAX) {
          return inferredParameter(PgTypes.OID.int4, value)
        }
        if (Number.isSafeInteger(value)) {
          return inferredParameter(PgTypes.OID.int8, BigInt(value))
        }
      }
      return inferredParameter(PgTypes.OID.float8, value)
    case "string":
      // Bound with no concrete type, as a text-format literal, so the backend
      // derives the type from the statement: a string works against a bigint
      // or timestamp column the way it did with the text-protocol drivers.
      return inferredParameter(0, value)
  }
  if (value instanceof Date) return inferredParameter(PgTypes.OID.timestamptz, value)
  if (value instanceof Uint8Array) return inferredParameter(PgTypes.OID.bytea, value)
  if (value instanceof Int8Array) {
    return inferredParameter(
      PgTypes.OID.bytea,
      new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
    )
  }
  throw new PgTypes.CodecError({ message: `Cannot infer a PostgreSQL type for ${String(value)}` })
}

const inferParameter = (value: unknown, registry: PgTypes.Registry | undefined): PgTypes.Parameter => {
  if (!Array.isArray(value)) return inferScalar(value)
  if (value.length === 0) {
    // Let the backend infer the array type from the statement, as for scalar strings.
    return inferredParameter(0, "{}")
  }
  let elementOid: number | undefined
  const values: Array<unknown> = new Array(value.length)
  for (let index = 0; index < value.length; index++) {
    const element = value[index]
    if (Array.isArray(element)) {
      throw new PgTypes.CodecError({ message: "Nested array parameters are not supported" })
    }
    const parameter = inferScalar(element)
    // A scalar string binds untyped, but an array names its element type.
    let oid = parameter.oid
    if (oid === 0) {
      if (parameter.value === null) {
        values[index] = null
        continue
      }
      oid = PgTypes.OID.text
    }
    if (Array.isArray(parameter.value)) {
      throw new PgTypes.CodecError({ message: "Nested array parameters are not supported" })
    }
    if (elementOid === undefined) elementOid = oid
    else if (elementOid !== oid) {
      throw new PgTypes.CodecError({ message: "Array parameter elements must have the same inferred OID" })
    }
    values[index] = parameter.value
  }
  if (elementOid === undefined) {
    throw new PgTypes.CodecError({ message: "Cannot infer the type of an array containing only null values" })
  }
  const arrayOid = PgTypes.arrayOidFor(elementOid, registry)
  if (arrayOid === undefined) {
    throw new PgTypes.CodecError({ message: `No array type known for element OID ${elementOid}` })
  }
  return inferredParameter(arrayOid, values)
}

/**
 * Joins the parts of a frame into the buffer that goes on the wire.
 *
 * The buffer comes from Node's pool and can be passed directly to
 * `socket.write`. Every byte is initialized before the buffer is returned.
 */
const concat = (chunks: ReadonlyArray<Uint8Array>): Uint8Array => {
  let length = 0
  for (let index = 0; index < chunks.length; index++) length += chunks[index].length
  const output = Buffer.allocUnsafe(length)
  let offset = 0
  for (let index = 0; index < chunks.length; index++) {
    output.set(chunks[index], offset)
    offset += chunks[index].length
  }
  return output
}

const emptyParams: ReadonlyArray<unknown> = []

const takeResult = (output: QueryOutput): Result => output.result
const takeValues = (output: QueryOutput): ReadonlyArray<ReadonlyArray<unknown>> => output.values

/**
 * The tail of every extended-query frame. `Describe` names the unnamed portal,
 * `Execute` runs it without a row limit, and `Sync` closes the cycle; none of
 * the three carries per-query state, so the bytes are encoded once.
 */
const describeExecuteSync: Uint8Array = concat([
  PgProtocol.encodeDescribe({ target: "portal", name: "" }),
  PgProtocol.encodeExecute({ portal: "", maxRows: 0 }),
  PgProtocol.encodeSync()
])

/** The same tail for a statement whose columns are already known. */
const executeSync: Uint8Array = concat([
  PgProtocol.encodeExecute({ portal: "", maxRows: 0 }),
  PgProtocol.encodeSync()
])

/** The default number of statements a connection keeps prepared. */
const defaultPreparedStatements = 100

/**
 * A statement the backend has parsed and holds under a name.
 *
 * `ready` turns true once `ParseComplete` confirms the backend has it and the
 * first execution has reported its columns. Until then the entry is treated as
 * a miss, which is safe because one cycle runs at a time. A `ready` entry with
 * no `description` describes a statement that returns no rows.
 */
interface Prepared {
  readonly name: string
  readonly key: string
  ready: boolean
  /** A cycle carrying this statement's `Parse` is on the wire. */
  parsing: boolean
  description: Description | undefined
}

/** One planned execution: the bytes to write and what to expect back. */
interface Plan {
  readonly frame: Uint8Array
  /** `CloseComplete` messages to consume before the cycle proper. */
  readonly closes: number
  /** Whether the frame carries a `Parse`. */
  readonly parses: boolean
  /** Whether the frame carries a `Describe`, so the columns arrive on the wire. */
  readonly describes: boolean
  /** The statement being filled in or reused, if this execution names one. */
  readonly prepared: Prepared | undefined
  /** Set when the columns were already known, so no `RowDescription` is coming. */
  readonly description: Description | undefined
  /** Set by the cycle when the backend rejected the name or the cached plan. */
  stale: boolean
}

/** The unnamed path: `Parse` / `Bind` / `Describe` / `Execute` / `Sync`. */
const encodeUnnamed = (
  sql: string,
  parameters: ReadonlyArray<PgTypes.Parameter>,
  parameterTypes: ReadonlyArray<number>,
  encodeBind: BindEncoder
): Plan => {
  const parse = PgProtocol.encodeParse({ name: "", query: sql, parameterTypes })
  if (EffectResult.isFailure(parse)) throw parse.failure
  const bind = encodeBind({ portal: "", statement: "", parameters })
  if (EffectResult.isFailure(bind)) throw bind.failure
  return {
    frame: concat([parse.success, bind.success, describeExecuteSync]),
    closes: 0,
    parses: true,
    describes: true,
    prepared: undefined,
    description: undefined,
    stale: false
  }
}

/**
 * Builds one extended-query cycle as a single buffer, so a statement costs one
 * socket write.
 *
 * A statement the backend already holds under a name needs only
 * `Bind` / `Execute` / `Sync`: no `Parse` for the backend to plan and no
 * `Describe`, because the columns came back the first time and are cached with
 * the name. Statements evicted from the cache ride along as `Close` messages
 * rather than paying a round trip of their own.
 */
const encodeQuery = (
  sql: string,
  params: ReadonlyArray<unknown>,
  registry: PgTypes.Registry | undefined,
  encodeBind: BindEncoder,
  cache: PreparedCache | undefined
): Plan => {
  const count = params.length
  const parameters: Array<PgTypes.Parameter> = new Array(count)
  const parameterTypes: Array<number> = new Array(count)
  for (let index = 0; index < count; index++) {
    const parameter = inferParameter(params[index], registry)
    parameters[index] = parameter
    parameterTypes[index] = parameter.oid
  }

  if (cache === undefined) {
    return encodeUnnamed(sql, parameters, parameterTypes, encodeBind)
  }

  const prepared = cache.get(sql, parameterTypes)
  if (!prepared.ready && prepared.parsing) {
    // Another cycle is already on the wire carrying this name's `Parse`.
    // Naming it again would collide, and reusing it would mean binding to
    // columns nobody has seen yet, so this execution goes unnamed.
    return encodeUnnamed(sql, parameters, parameterTypes, encodeBind)
  }
  const bind = encodeBind({ portal: "", statement: prepared.name, parameters })
  if (EffectResult.isFailure(bind)) throw bind.failure
  const parse = prepared.ready ? undefined : PgProtocol.encodeParse({ name: prepared.name, query: sql, parameterTypes })
  if (parse !== undefined && EffectResult.isFailure(parse)) throw parse.failure
  const closeFrames = cache.takeCloses()

  if (parse === undefined) {
    return {
      frame: closeFrames === undefined
        ? concat([bind.success, executeSync])
        : concat([closeFrames.frames, bind.success, executeSync]),
      closes: closeFrames?.count ?? 0,
      parses: false,
      describes: false,
      prepared,
      description: prepared.description,
      stale: false
    }
  }

  prepared.parsing = true
  return {
    frame: closeFrames === undefined
      ? concat([parse.success, bind.success, describeExecuteSync])
      : concat([closeFrames.frames, parse.success, bind.success, describeExecuteSync]),
    closes: closeFrames?.count ?? 0,
    parses: true,
    describes: true,
    prepared,
    description: undefined,
    stale: false
  }
}

/**
 * The statements one connection has prepared, keyed by SQL text and the
 * parameter OIDs inferred for it: the same text with differently typed
 * parameters is a different statement to the backend.
 *
 * The cache is bounded and evicts least-recently-used. An evicted statement is
 * closed on the backend, but its `Close` waits for the next statement to go
 * out rather than taking a round trip of its own.
 */
class PreparedCache {
  readonly max: number
  private readonly statements = new Map<string, Prepared>()
  private readonly namespace = randomBytes(8).toString("hex")
  private closes: Array<Uint8Array> | undefined
  private counter = 0

  constructor(max: number) {
    this.max = max
  }

  get(sql: string, parameterTypes: ReadonlyArray<number>): Prepared {
    const key = parameterTypes.length === 0 ? sql : `${sql}\u0000${parameterTypes.join(",")}`
    const found = this.statements.get(key)
    if (found !== undefined) {
      // Re-insert to move it to the end: `Map` iterates in insertion order, so
      // the first key is the least recently used one.
      this.statements.delete(key)
      this.statements.set(key, found)
      this.trim(found)
      return found
    }
    const prepared: Prepared = {
      name: `effect_${this.namespace}_${++this.counter}`,
      key,
      ready: false,
      parsing: false,
      description: undefined
    }
    this.statements.set(key, prepared)
    this.trim(prepared)
    return prepared
  }

  /**
   * A statement still being parsed cannot be closed yet: its `Parse` may not
   * have reached the socket. Let the cache exceed its bound temporarily, then
   * discard abandoned entries and close excess ready statements on access.
   */
  private trim(protectedStatement?: Prepared): void {
    while (this.statements.size > this.max) {
      let evicted: Prepared | undefined
      for (const prepared of this.statements.values()) {
        if (prepared !== protectedStatement && (prepared.ready || !prepared.parsing)) {
          evicted = prepared
          break
        }
      }
      if (evicted === undefined) return
      this.statements.delete(evicted.key)
      if (evicted.ready) this.close(evicted.name)
    }
  }

  /**
   * Drops a statement the backend no longer holds, or whose plan went stale.
   *
   * The name is closed either way. A plan that went stale is still held under
   * it, and re-parsing would collide; a name the backend has already lost
   * ignores the `Close`, which Postgres treats as a success.
   */
  evict(prepared: Prepared): void {
    if (prepared.parsing) return
    if (this.statements.delete(prepared.key) && prepared.ready) this.close(prepared.name)
  }

  /**
   * Drops a statement whose parsing cycle failed before its columns arrived.
   *
   * A `Parse` that completed before the error outlives the failed cycle, so
   * the backend may hold the name while the entry can never become ready. The
   * name is closed either way: closing one the backend never registered is a
   * no-op.
   */
  evictFailed(prepared: Prepared): void {
    this.statements.delete(prepared.key)
    this.close(prepared.name)
  }

  private close(name: string): void {
    ;(this.closes ??= []).push(PgProtocol.encodeClose({ target: "statement", name }))
  }

  takeCloses(): { readonly frames: Uint8Array; readonly count: number } | undefined {
    const closes = this.closes
    if (closes === undefined) return undefined
    this.closes = undefined
    return { frames: closes.length === 1 ? closes[0] : concat(closes), count: closes.length }
  }
}

/**
 * SQLSTATEs that mean "this name is no longer usable": the backend lost the
 * statement, or the plan behind it no longer matches the columns it was
 * prepared for. Both are recovered by parsing the statement again.
 */
const isStalePreparedStatement = (code: string | undefined): boolean => code === "26000" || code === "0A000"

type BindEncoder = (options: {
  readonly portal: string
  readonly statement: string
  readonly parameters: ReadonlyArray<PgTypes.Parameter>
}) => EffectResult.Result<Uint8Array, PgProtocol.EncodeError | PgTypes.CodecError>

/**
 * The default builtin-catalogue encoder, shared by every connection without a
 * custom registry. Passing `PgTypes.writeParameter` itself engages
 * `makeBindEncoder`'s unsafe fast path.
 */
const defaultBindEncoder: BindEncoder = PgProtocol.makeBindEncoder(PgTypes.writeParameter, PgTypes.isTextFormat)

/** One bind encoder per registry, since building one allocates a closure. */
const makeBindEncoder = (registry: PgTypes.Registry | undefined): BindEncoder =>
  registry === undefined
    ? defaultBindEncoder
    : PgProtocol.makeBindEncoder(
      (sink: PgProtocol.ValueSink, parameter: PgTypes.Parameter) => PgTypes.writeParameter(sink, parameter, registry),
      PgTypes.isTextFormat
    )

const queryError = (cause: unknown, message: string): SqlError =>
  new SqlError({ reason: new UnknownError({ cause, message, operation: "query" }) })

/**
 * Retries a cycle whose named statement the backend no longer honors: the
 * statement is dropped from the cache and the retry runs unnamed, so it cannot
 * loop.
 */
const retryStale = (
  plan: Plan,
  cache: PreparedCache,
  run: Effect.Effect<QueryOutput, SqlError>,
  rerun: () => Effect.Effect<QueryOutput, SqlError>
): Effect.Effect<QueryOutput, SqlError> =>
  Effect.catchCause(run, (cause) => {
    if (!plan.stale) return Effect.failCause(cause)
    cache.evict(plan.prepared!)
    return rerun()
  })

const connectionQueryError = (cause: unknown, message: string): SqlError =>
  new SqlError({ reason: new ConnectionError({ cause, message, operation: "query" }) })

const pinReleasedError = (): SqlError =>
  connectionQueryError(new Error("Pinned connection was released"), "PgConnection: Pinned connection was released")

const escapeIdentifier = (identifier: string): string => `"${identifier.replaceAll("\"", "\"\"")}"`

type QueryPhase = "close" | "parse" | "bind" | "describe" | "rows" | "complete" | "error"

/**
 * Splits a command tag such as `SELECT 3` or `INSERT 0 1`. Reading the two
 * spaces directly keeps a completed statement from allocating the parts array
 * that splitting on every space would.
 */
const parseCommandTag = (tag: string): { command: string; rowCount: number; oid: number | null } => {
  const firstSpace = tag.indexOf(" ")
  if (firstSpace < 0) return { command: tag, oid: null, rowCount: 0 }
  const command = tag.slice(0, firstSpace)
  const secondSpace = tag.indexOf(" ", firstSpace + 1)
  if (command === "INSERT" && secondSpace > 0) {
    return {
      command,
      oid: Number(tag.slice(firstSpace + 1, secondSpace)),
      rowCount: Number(tag.slice(secondSpace + 1))
    }
  }
  const last = tag.slice((secondSpace < 0 ? firstSpace : secondSpace) + 1)
  return { command, oid: null, rowCount: isDigits(last) ? Number(last) : 0 }
}

const isDigits = (value: string): boolean => {
  if (value.length === 0) return false
  for (let index = 0; index < value.length; index++) {
    const code = value.charCodeAt(index)
    if (code < 48 || code > 57) return false
  }
  return true
}

/**
 * Tracks one query cycle while the connection routes backend messages to it.
 * Each pipelined cycle keeps its own parser state and completes once.
 */
class QueryMachine implements Consumer {
  private readonly conn: PgConnectionImpl
  private readonly plan: Plan
  private readonly finish: (effect: Effect.Effect<QueryOutput, SqlError>) => void
  /** Installed on the parser while this machine is at the head of the queue. */
  readonly readField: PgProtocol.FieldReader<unknown> | undefined
  /** Object rows, or `undefined` when the caller asked for positional ones. */
  private readonly rows: Array<Row> | undefined
  private readonly values: Array<ReadonlyArray<unknown>> | undefined

  private closes: number
  private phase: QueryPhase
  private fieldCount: number
  private resultFields: ReadonlyArray<Field>
  private rowBuilder: RowBuilder | undefined
  private command = ""
  private rowCount = 0
  private oid: number | null = null
  private failure: SqlError | undefined
  private done = false
  private aborted = false
  private drainDone: (() => void) | undefined

  constructor(
    conn: PgConnectionImpl,
    plan: Plan,
    wantRows: boolean,
    finish: (effect: Effect.Effect<QueryOutput, SqlError>) => void
  ) {
    this.conn = conn
    this.plan = plan
    this.finish = finish
    this.rows = wantRows ? [] : undefined
    this.values = wantRows ? undefined : []
    this.closes = plan.closes
    this.phase = plan.closes > 0 ? "close" : plan.parses ? "parse" : "bind"
    const description = plan.description
    this.readField = description?.readField
    this.fieldCount = description?.resultFields.length ?? 0
    this.resultFields = description?.resultFields ?? emptyFields
    this.rowBuilder = description?.rowBuilder
  }

  isDone(): boolean {
    return this.done
  }

  abort(onDrained: () => void): void {
    if (this.done) return onDrained()
    this.aborted = true
    this.drainDone = onDrained
  }

  private complete(effect: Effect.Effect<QueryOutput, SqlError>): void {
    if (this.done) return
    this.done = true
    // Whether it parsed or not, this cycle no longer holds the name: success
    // has already marked it ready, failure leaves it to be parsed again.
    const prepared = this.plan.prepared
    if (prepared !== undefined) prepared.parsing = false
    this.finish(effect)
  }

  private failDesync(message: string): void {
    this.conn.fatal(connectionQueryError(new Error(message), `PgConnection: ${message}`))
  }

  onFatal(error: SqlError): void {
    if (this.done) return
    this.done = true
    const prepared = this.plan.prepared
    if (prepared !== undefined) prepared.parsing = false
    if (this.aborted) this.drainDone?.()
    else this.finish(Effect.fail(this.failure ?? error))
  }

  onMessage(message: PgProtocol.BackendMessage<unknown>): void {
    if (this.aborted) {
      if (message._tag === "ReadyForQuery") {
        this.done = true
        this.drainDone?.()
      }
      return
    }
    if (this.phase === "error") {
      if (message._tag === "ReadyForQuery") {
        // Retrying in an aborted transaction would mask the original error with 25P02.
        if (this.plan.stale && !this.plan.parses && message.status === "E") {
          this.conn.prepared?.evict(this.plan.prepared!)
          this.plan.stale = false
        }
        return this.complete(Effect.fail(this.failure!))
      }
      return this.failDesync(`Unexpected ${message._tag} after ErrorResponse`)
    }
    switch (message._tag) {
      case "CloseComplete":
        if (this.phase !== "close") return this.failDesync(`Unexpected CloseComplete during ${this.phase}`)
        if (--this.closes === 0) this.phase = this.plan.parses ? "parse" : "bind"
        return
      case "ParseComplete":
        if (this.phase !== "parse") return this.failDesync(`Unexpected ParseComplete during ${this.phase}`)
        this.phase = "bind"
        return
      case "BindComplete":
        if (this.phase !== "bind") return this.failDesync(`Unexpected BindComplete during ${this.phase}`)
        this.phase = this.plan.describes ? "describe" : "rows"
        return
      case "RowDescription": {
        if (this.phase !== "describe") return this.failDesync(`Unexpected RowDescription during ${this.phase}`)
        const description = describe(message.fields, this.conn.registry)
        if (EffectResult.isFailure(description)) {
          return this.conn.fatal(queryError(description.failure, "PgConnection: Failed to decode row"))
        }
        this.fieldCount = message.fields.length
        this.resultFields = description.success.resultFields
        this.rowBuilder = description.success.rowBuilder
        // `pushEach` hands this description over before it reads the rows
        // behind it, including rows that arrived in the same chunk.
        this.conn.session.parser.readField = description.success.readField
        const prepared = this.plan.prepared
        if (prepared !== undefined) {
          prepared.description = description.success
          prepared.ready = true
        }
        this.phase = "rows"
        return
      }
      case "NoData": {
        if (this.phase !== "describe") return this.failDesync(`Unexpected NoData during ${this.phase}`)
        const prepared = this.plan.prepared
        if (prepared !== undefined) {
          prepared.description = undefined
          prepared.ready = true
        }
        this.phase = "rows"
        return
      }
      case "DataRow": {
        if (this.phase !== "rows" || this.rowBuilder === undefined) {
          return this.failDesync(`Unexpected DataRow during ${this.phase}`)
        }
        const rowValues = message.values
        if (rowValues.length !== this.fieldCount) {
          return this.failDesync(`DataRow has ${rowValues.length} values for ${this.fieldCount} fields`)
        }
        if (this.rows !== undefined) this.rows.push(this.rowBuilder(rowValues))
        else this.values!.push(rowValues)
        return
      }
      case "CommandComplete": {
        if (this.phase !== "rows") return this.failDesync(`Unexpected CommandComplete during ${this.phase}`)
        const parsed = parseCommandTag(message.commandTag)
        this.command = parsed.command
        this.rowCount = parsed.rowCount
        this.oid = parsed.oid
        this.phase = "complete"
        return
      }
      case "EmptyQueryResponse":
        if (this.phase !== "rows") return this.failDesync(`Unexpected EmptyQueryResponse during ${this.phase}`)
        this.phase = "complete"
        return
      case "ErrorResponse": {
        if (isStalePreparedStatement(message.fields.code)) this.plan.stale = true
        // A cycle that carried this statement's `Parse` but failed before its
        // columns arrived leaves an entry that can never become ready while
        // the backend may still hold the name: the `Parse` outlives the
        // failed cycle. Drop the entry and close the name, so the next
        // execution parses fresh under a new one.
        const prepared = this.plan.prepared
        if (this.plan.parses && prepared !== undefined && !prepared.ready) {
          this.conn.prepared?.evictFailed(prepared)
        }
        // Every phase drains the same way: the backend skips the rest of the
        // cycle and sends `ReadyForQuery` after the `Sync` that closes it, so
        // a statement it refused to parse leaves the session usable.
        this.failure = new SqlError({
          reason: classifyFields(message.fields, "PgConnection: Query failed", "query")
        })
        this.phase = "error"
        return
      }
      case "ReadyForQuery":
        if (this.phase !== "complete") return this.failDesync(`Unexpected ReadyForQuery during ${this.phase}`)
        return this.complete(Effect.succeed({
          result: {
            command: this.command,
            rowCount: this.rowCount,
            oid: this.oid,
            rows: this.rows ?? emptyRows,
            fields: this.resultFields
          },
          values: this.values ?? emptyValues
        }))
      case "CopyInResponse":
      case "CopyOutResponse":
      case "CopyBothResponse":
      case "CopyData":
      case "CopyDone":
        return this.failDesync(`Unexpected ${message._tag}; COPY is not supported`)
      default:
        return this.failDesync(`Unexpected ${message._tag} during ${this.phase}`)
    }
  }
}

const emptyRows: ReadonlyArray<Row> = []
const emptyValues: ReadonlyArray<ReadonlyArray<unknown>> = []

/** Drains an aborted statement, sending a cancel after a short grace period and failing if it stalls. */
const drainAborted = (
  conn: PgConnectionImpl,
  timeoutMessage: string,
  abort: (onDrained: () => void) => void
): Effect.Effect<void> => {
  const drained = Deferred.makeUnsafe<void>()
  const timeout = setTimeout(
    () => conn.fatal(connectionQueryError(new Error(timeoutMessage), `PgConnection: ${timeoutMessage}`)),
    abortDrainTimeoutMillis
  )
  abort(() => {
    clearTimeout(timeout)
    Deferred.doneUnsafe(drained, Effect.void)
  })
  const grace = Effect.callback<void>((resume) => {
    const timer = setTimeout(() => resume(Effect.void), abortDrainGraceMillis)
    return Effect.sync(() => clearTimeout(timer))
  })
  const cancelAndDrain = Effect.andThen(conn.cancel, Deferred.await(drained))
  return Effect.andThen(
    Effect.raceFirst(Deferred.await(drained), grace),
    Effect.suspend(() => Deferred.isDoneUnsafe(drained) ? Effect.void : cancelAndDrain)
  )
}

/** One cycle on a connection that carries a single statement at a time. */
const runQuery = (
  conn: PgConnectionImpl,
  plan: Plan,
  wantRows: boolean
): Effect.Effect<QueryOutput, SqlError> =>
  Effect.callback<QueryOutput, SqlError>((resume) => {
    if (conn.deadWith !== undefined) {
      resume(Effect.fail(conn.deadWith))
      return
    }
    const machine = new QueryMachine(conn, plan, wantRows, (effect) => {
      conn.consumer = undefined
      resume(effect)
    })
    conn.consumer = machine
    // A reused statement has no `RowDescription` coming, so its reader has to
    // be in place before the rows are.
    conn.session.parser.readField = machine.readField
    try {
      conn.session.socket.write(plan.frame)
    } catch (cause) {
      conn.fatal(connectionQueryError(cause, "PgConnection: Failed to write query"))
    }

    return Effect.suspend(() => {
      if (machine.isDone()) return Effect.void
      return drainAborted(conn, "Query cancellation timed out", (onDrained) =>
        machine.abort(() => {
          conn.consumer = undefined
          onDrained()
        }))
    })
  })

/** Turns one decoded row into an object keyed by column name. */
type RowBuilder = (rowValues: ReadonlyArray<unknown>) => Row

/** Everything a query needs from one `RowDescription`. */
interface Description {
  readonly readField: PgProtocol.FieldReader<unknown>
  readonly rowBuilder: RowBuilder
  readonly resultFields: ReadonlyArray<Field>
}

const emptyFields: ReadonlyArray<Field> = []

/** Derives the per-column readers and the row constructor for a description. */
const describe = (
  fields: ReadonlyArray<PgProtocol.FieldDescription>,
  registry: PgTypes.Registry | undefined
): EffectResult.Result<Description, PgTypes.CodecError> => {
  const reader = PgTypes.makeFieldReader(fields, registry)
  if (EffectResult.isFailure(reader)) return EffectResult.fail(reader.failure)
  const resultFields: Array<Field> = new Array(fields.length)
  for (let index = 0; index < fields.length; index++) {
    resultFields[index] = { name: fields[index].name, dataTypeId: fields[index].dataTypeOid }
  }
  return EffectResult.succeed({
    readField: reader.success,
    rowBuilder: makeRowBuilder(fields),
    resultFields
  })
}

/**
 * Builds the row constructor for one `RowDescription`.
 *
 * Assignment is an order of magnitude faster than `Object.defineProperty` and
 * stores the same own, enumerable, writable, configurable property - except
 * for `__proto__`, which assignment routes to the prototype setter instead. A
 * description carrying that column name falls back to the slow spelling.
 */
const makeRowBuilder = (fields: ReadonlyArray<PgProtocol.FieldDescription>): RowBuilder => {
  const names: Array<string> = new Array(fields.length)
  let hasProto = false
  for (let index = 0; index < fields.length; index++) {
    const name = fields[index].name
    names[index] = name
    if (name === "__proto__") hasProto = true
  }
  if (hasProto) {
    return (rowValues) => {
      const row: Record<string, unknown> = {}
      for (let index = 0; index < names.length; index++) {
        Object.defineProperty(row, names[index], {
          value: rowValues[index],
          enumerable: true,
          configurable: true,
          writable: true
        })
      }
      return row
    }
  }
  return (rowValues) => {
    const row: Record<string, unknown> = {}
    for (let index = 0; index < names.length; index++) {
      row[names[index]] = rowValues[index]
    }
    return row
  }
}

const streamRows = (
  conn: PgConnectionImpl,
  pin: Effect.Effect<PinnedPgConnection, never, Scope.Scope>,
  sql: string,
  params: ReadonlyArray<unknown>
): Stream.Stream<Row, SqlError> =>
  Stream.fromChannel(Channel.fromTransform(Effect.fnUntraced(function*(_, scope) {
    const pinned = yield* Scope.provide(pin, scope)
    yield* Scope.provide(
      Effect.acquireRelease(conn.wire.take(1), () => conn.wire.release(1)),
      scope
    )
    if (pinned.released) return yield* pinReleasedError()
    // Streams stay on the unnamed path: a stream pays its setup once over the
    // whole result, so naming the statement buys little and would need the
    // stale-plan retry to unwind rows already delivered.
    const plan = yield* Effect.try({
      try: () => conn.encodeQuery(sql, params, undefined),
      catch: (cause) => queryError(cause, "PgConnection: Failed to encode query")
    })
    const frame = plan.frame

    const socket = conn.session.socket
    const parser = conn.session.parser
    let phase: QueryPhase = "parse"
    let fieldCount = 0
    let rowBuilder: RowBuilder | undefined
    let buffer: Array<Row> = []
    let failure: SqlError | undefined
    let finished = false
    let done = false
    let aborted = false
    let paused = false
    let pending:
      | ((effect: Effect.Effect<Arr.NonEmptyReadonlyArray<Row>, SqlError | Cause.Done>) => void)
      | undefined
    let drainDone: (() => void) | undefined

    const setPaused = (value: boolean): void => {
      if (paused === value) return
      paused = value
      if (value) socket.pause()
      else socket.resume()
    }

    const deliver = (): void => {
      if (pending === undefined) return
      const resume = pending
      if (buffer.length > 0) {
        const chunk = buffer as Arr.NonEmptyArray<Row>
        buffer = []
        pending = undefined
        resume(Effect.succeed(chunk))
      } else if (finished) {
        pending = undefined
        resume(failure !== undefined ? Effect.fail(failure) : Cause.done())
      }
    }

    const onFatal = (error: SqlError): void => {
      if (done) return
      done = true
      finished = true