@effect/sql-pg 4.0.0-rc.116 → 4.0.0-rc.118

package/src/PgConnection.ts

@@ -1,6 +1,8 @@
 /**
  * Native PostgreSQL sessions built on the `PgProtocol` wire codec.
  *
+ * **Details**
+ *
  * Sessions support queries, streaming, `LISTEN`/`NOTIFY`, cancellation, and
  * exclusive ownership for transactions.
  *
@@ -19,14 +21,8 @@ import * as Redacted from "effect/Redacted"
 import * as EffectResult from "effect/Result"
 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 {
-  AuthenticationError,
-  ConnectionError,
-  SqlError,
-  type SqlErrorReason,
-  UnknownError
-} from "effect/unstable/sql/SqlError"
 import { Buffer } from "node:buffer"
 import { randomBytes } from "node:crypto"
 import * as Net from "node:net"
@@ -199,13 +195,28 @@ export interface PgConnection {
    * ownership queue, while calls through the original connection wait.
    */
   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. */
+  /**
+   * 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. */
+  /**
+   * 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>,
@@ -213,9 +224,8 @@ export interface PgConnection {
   ) => Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>
   /**
    * Streams rows without collecting the full result. The session is pinned for
-   * the lifetime of the stream. Aborting the stream
-   * before the result completes cancels the statement with a `CancelRequest`
-   * and drains the connection back to `ReadyForQuery`.
+   * the lifetime of the stream. An early abort behaves like an interrupted
+   * `query`.
    */
   readonly stream: (
     sql: string,
@@ -317,6 +327,9 @@ interface PipelineEntry {
 }
 
 const abortDrainTimeoutMillis = 5000
+const abortDrainGraceMillis = 10
+/** PostgreSQL `query_canceled` SQLSTATE. */
+const queryCanceledCode = "57014"
 const cancelRequestTimeoutMillis = 5000
 /** How many statements a multiplexed session keeps on the wire at once. */
 const maxPipelineDepth = 128
@@ -342,8 +355,9 @@ class PgConnectionImpl implements PgConnection {
   consumer: Consumer | undefined
   deadWith: SqlError | undefined
   closed = false
+  cancelPending = false
   readonly channels = new Map<string, Set<Queue.Queue<Notification, SqlError>>>()
-  readonly fatalHooks = new Set<() => void>()
+  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. */
@@ -367,7 +381,7 @@ class PgConnectionImpl implements PgConnection {
     this[internalsKey] = {
       base: this,
       deadError: () => this.deadWith,
-      fatalHooks: this.fatalHooks
+      retireHooks: this.retireHooks
     }
     this.pinnedView = new PinnedPgConnection(this)
     session.socket.on("data", this.onData)
@@ -399,6 +413,15 @@ class PgConnectionImpl implements PgConnection {
   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":
+        if (this.cancelPending) {
+          this.cancelPending = false
+          this.retire()
+        }
+        break
       case "NotificationResponse": {
         const queues = this.channels.get(message.channel)
         if (queues !== undefined) {
@@ -440,6 +463,7 @@ class PgConnectionImpl implements PgConnection {
     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()
@@ -447,9 +471,11 @@ class PgConnectionImpl implements PgConnection {
     for (const set of sets) {
       for (const queue of set) Queue.failCauseUnsafe(queue, cause)
     }
-    if (!this.closed) {
-      for (const hook of this.fatalHooks) hook()
-    }
+  }
+
+  private retire(): void {
+    if (this.closed) return
+    for (const hook of this.retireHooks) hook()
   }
 
   closeUnsafe(): void {
@@ -695,6 +721,8 @@ class PgConnectionImpl implements PgConnection {
   /** 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)
   })
 
@@ -1077,6 +1105,7 @@ const encodeQuery = (
 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
 
@@ -1096,7 +1125,7 @@ class PreparedCache {
       return found
     }
     const prepared: Prepared = {
-      name: `effect${++this.counter}`,
+      name: `effect_${this.namespace}_${++this.counter}`,
       key,
       ready: false,
       parsing: false,
@@ -1457,6 +1486,32 @@ class QueryMachine implements Consumer {
 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,
@@ -1482,26 +1537,13 @@ const runQuery = (
       conn.fatal(connectionQueryError(cause, "PgConnection: Failed to write query"))
     }
 
-    // On interruption: cancel the statement and drain the connection back to
-    // ReadyForQuery so it stays usable, destroying it when the drain stalls.
     return Effect.suspend(() => {
       if (machine.isDone()) return Effect.void
-      const wait = Effect.callback<void>((resumeWait) => {
-        const timer = setTimeout(
-          () =>
-            conn.fatal(connectionQueryError(
-              new Error("Query cancellation timed out"),
-              "PgConnection: Query cancellation timed out"
-            )),
-          abortDrainTimeoutMillis
-        )
+      return drainAborted(conn, "Query cancellation timed out", (onDrained) =>
         machine.abort(() => {
-          clearTimeout(timer)
           conn.consumer = undefined
-          resumeWait(Effect.void)
-        })
-      })
-      return Effect.andThen(conn.cancel, wait)
+          onDrained()
+        }))
     })
   })
 
@@ -1746,30 +1788,16 @@ const streamRows = (
       else if (buffer.length >= streamPauseThreshold) setPaused(true)
     }
 
-    // On early abort: cancel the statement and drain back to ReadyForQuery so
-    // the pinned connection stays usable, destroying it when the drain stalls.
     yield* Scope.addFinalizer(
       scope,
       Effect.suspend(() => {
         if (done) return Effect.void
         aborted = true
-        setPaused(false)
-        const wait = Effect.callback<void>((resumeWait) => {
-          if (done) return resumeWait(Effect.void)
-          const timer = setTimeout(
-            () =>
-              conn.fatal(connectionQueryError(
-                new Error("Stream cancellation timed out"),
-                "PgConnection: Stream cancellation timed out"
-              )),
-            abortDrainTimeoutMillis
-          )
-          drainDone = () => {
-            clearTimeout(timer)
-            resumeWait(Effect.void)
-          }
+        const drain = drainAborted(conn, "Stream cancellation timed out", (onDrained) => {
+          drainDone = onDrained
         })
-        return Effect.andThen(conn.cancel, wait)
+        setPaused(false)
+        return drain
       })
     )
 

package/src/PgMigrator.ts

@@ -13,18 +13,18 @@ import * as Effect from "effect/Effect"
 import * as FileSystem from "effect/FileSystem"
 import * as Layer from "effect/Layer"
 import * as Path from "effect/Path"
-import * as ChildProcess from "effect/unstable/process/ChildProcess"
-import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner"
-import * as Migrator from "effect/unstable/sql/Migrator"
-import type { SqlClient } from "effect/unstable/sql/SqlClient"
-import type { SqlError } from "effect/unstable/sql/SqlError"
+import * as ChildProcess from "effect/process/ChildProcess"
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner"
+import * as Migrator from "effect/sql/Migrator"
+import type { SqlClient } from "effect/sql/SqlClient"
+import type { SqlError } from "effect/sql/SqlError"
 import * as Password from "./internal/password.ts"
 import { PgClient } from "./PgClient.ts"
 
 /**
  * @since 4.0.0
  */
-export * from "effect/unstable/sql/Migrator"
+export * from "effect/sql/Migrator"
 
 /**
  * Runs PostgreSQL SQL migrations using the configured clients. Schema dumps use `pg_dump` and require child process, filesystem, and path services.

package/src/PgPool.ts

@@ -9,7 +9,7 @@ import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Pool from "effect/Pool"
 import type * as Scope from "effect/Scope"
-import type { SqlError } from "effect/unstable/sql/SqlError"
+import type { SqlError } from "effect/sql/SqlError"
 import { connectionInternals } from "./internal/connection.ts"
 import * as PgConnection from "./PgConnection.ts"
 
@@ -140,7 +140,7 @@ export const make = Effect.fnUntraced(function*(options: Config): Effect.fn.Retu
     Effect.sync(() => {
       createdAt.set(connection, clock.currentTimeMillisUnsafe())
       const internals = connectionInternals(connection)
-      internals.fatalHooks.add(() => {
+      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
@@ -204,12 +204,9 @@ export const make = Effect.fnUntraced(function*(options: Config): Effect.fn.Retu
   // `pin` reserves the pool item itself, so this needs no help.
   const reserve = Effect.flatMap(get, (connection) => connection.pin)
 
-  // `Pool.use` cannot check the session it hands over before running the
-  // effect, so it is only taken when there is nothing to check: no session is
-  // known dead, and no lifetime can have run out. Otherwise the scoped
-  // checkout does its replacement pass first. Checking inside the callback
-  // instead would hold one lease while acquiring another, which deadlocks a
-  // pool of one.
+  // `Pool.use` cannot pre-check a session. Use it only when no TTL 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> =>

package/src/PgTypes.ts

@@ -29,10 +29,10 @@
  * @since 4.0.0
  */
 import * as Data from "effect/Data"
+import * as IpInterface from "effect/net/IpInterface"
+import * as IpNetwork from "effect/net/IpNetwork"
+import * as NetAddress from "effect/net/NetAddress"
 import * as Result from "effect/Result"
-import * as IpInterface from "effect/unstable/net/IpInterface"
-import * as IpNetwork from "effect/unstable/net/IpNetwork"
-import * as NetAddress from "effect/unstable/net/NetAddress"
 import type * as PgProtocol from "./PgProtocol.ts"
 import type { ValueSink } from "./PgProtocol.ts"
 
@@ -313,6 +313,7 @@ export const OID = {
   timestamptz: 1184,
   timetz: 1266,
   numeric: 1700,
+  regclass: 2205,
   uuid: 2950,
   jsonb: 3802,
   boolArray: 1000,
@@ -336,6 +337,7 @@ export const OID = {
   timestamptzArray: 1185,
   timetzArray: 1270,
   numericArray: 1231,
+  regclassArray: 2210,
   uuidArray: 2951,
   jsonbArray: 3807
 } as const
@@ -362,6 +364,7 @@ const arrayToElement = new Map<number, number>([
   [OID.timestamptzArray, OID.timestamptz],
   [OID.timetzArray, OID.timetz],
   [OID.numericArray, OID.numeric],
+  [OID.regclassArray, OID.regclass],
   [OID.uuidArray, OID.uuid],
   [OID.jsonbArray, OID.jsonb]
 ])
@@ -1160,6 +1163,23 @@ const jsonbCodec: UnsafeCodec<any> = codecOf(
   }
 )
 
+const oidCodec: UnsafeCodec<any> = codecOf(
+  (bytes, offset, size) => {
+    requireSize(size, 4, "oid")
+    return readUint32(bytes, offset)
+  },
+  (value) => {
+    const num = requireInteger(value, "oid", 0, 4294967295)
+    const bytes = new Uint8Array(4)
+    bytes[0] = num >>> 24
+    bytes[1] = num >>> 16
+    bytes[2] = num >>> 8
+    bytes[3] = num
+    return bytes
+  },
+  (sink, value) => sink.int32(requireInteger(value, "oid", 0, 4294967295))
+)
+
 const builtinScalars = new Map<number, UnsafeCodec<any>>([
   [
     OID.bool,
@@ -1224,25 +1244,8 @@ const builtinScalars = new Map<number, UnsafeCodec<any>>([
       (sink, value) => sink.int32(requireInteger(value, "int4", INT32_MIN, INT32_MAX))
     )
   ],
-  [
-    OID.oid,
-    codecOf(
-      (bytes, offset, size) => {
-        requireSize(size, 4, "oid")
-        return readUint32(bytes, offset)
-      },
-      (value) => {
-        const num = requireInteger(value, "oid", 0, 4294967295)
-        const bytes = new Uint8Array(4)
-        bytes[0] = num >>> 24
-        bytes[1] = num >>> 16
-        bytes[2] = num >>> 8
-        bytes[3] = num
-        return bytes
-      },
-      (sink, value) => sink.int32(requireInteger(value, "oid", 0, 4294967295))
-    )
-  ],
+  [OID.oid, oidCodec],
+  [OID.regclass, oidCodec],
   [
     OID.int8,
     codecOf(

package/src/internal/connection.ts

@@ -1,6 +1,6 @@
 import type * as Effect from "effect/Effect"
 import type * as Scope from "effect/Scope"
-import type { SqlError } from "effect/unstable/sql/SqlError"
+import type { SqlError } from "effect/sql/SqlError"
 
 /** @internal */
 export const internalsKey = "~@effect/sql-pg/PgConnection/internals" as const
@@ -10,8 +10,8 @@ export interface ConnectionInternals {
   /** The pool item identity: the unpinned base connection. */
   readonly base: object
   readonly deadError: () => SqlError | undefined
-  /** Fired once when the connection dies outside its own scope release. */
-  readonly fatalHooks: Set<() => void>
+  /** Fired when a pool must stop reusing the connection. */
+  readonly retireHooks: Set<() => void>
   /**
    * Installed by a multiplexed pool so that pinning the session also takes it
    * out of shared circulation for as long as the pin lasts. Every route to an

package/src/internal/sqlError.ts

@@ -12,7 +12,7 @@ import {
   StatementTimeoutError,
   UniqueViolation,
   UnknownError
-} from "effect/unstable/sql/SqlError"
+} from "effect/sql/SqlError"
 
 interface ErrorProps {
   readonly cause: unknown