@effect/sql-pg 4.0.0-rc.112 → 4.0.0-rc.113

package/src/PgPool.ts

@@ -0,0 +1,231 @@
+/**
+ * Pools of native `PgConnection` sessions.
+ *
+ * @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 Pool from "effect/Pool"
+import type * as Scope from "effect/Scope"
+import type { SqlError } from "effect/unstable/sql/SqlError"
+import { connectionInternals } from "./internal/connection.ts"
+import * as PgConnection from "./PgConnection.ts"
+
+const defaultMultiplexConcurrency = 32
+
+/**
+ * The runtime type identifier for `PgPool`.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const TypeId: TypeId = "~@effect/sql-pg/PgPool"
+
+/**
+ * The type-level identifier for `PgPool`.
+ *
+ * @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 10-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.
+ *
+ * With `multiplex` enabled, fibers may share pooled connections for pipelined
+ * queries. Reserved connections remain exclusive. Without multiplexing, every
+ * checkout is exclusive.
+ *
+ * @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 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.
+ *
+ * @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>
+}
+
+/**
+ * The service tag for `PgPool`.
+ *
+ * @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.
+ *
+ * @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 deadConnections = new Set<PgConnection.PgConnection>()
+  const createdAt = new WeakMap<PgConnection.PgConnection, number>()
+  const checkedOut = new WeakSet<PgConnection.PgConnection>()
+
+  // 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.tap(PgConnection.make(options), (connection) =>
+    Effect.sync(() => {
+      createdAt.set(connection, clock.currentTimeMillisUnsafe())
+      const internals = connectionInternals(connection)
+      internals.fatalHooks.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(10),
+    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 get: 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))
+  )
+
+  // `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.
+  const use = <A, E, R>(
+    f: (connection: PgConnection.PgConnection) => Effect.Effect<A, E, R>
+  ): Effect.Effect<A, E | SqlError, R> =>
+    Effect.suspend(() =>
+      connectionTTL === undefined && deadConnections.size === 0
+        ? Pool.use(pool, f)
+        : 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)
+  }
+  return pgPool
+})

package/src/PgProtocol.ts

@@ -46,26 +46,35 @@ export interface Parser<A = Uint8Array | null> {
   readField: FieldReader<A> | undefined
 
   /**
-   * Feeds the next chunk of socket bytes and returns every message that is now
-   * complete. A partial trailing message is retained until the bytes that
-   * finish it arrive. A thrown parse or field-reader error is terminal and the
-   * parser cannot be reused afterward; any messages decoded earlier in the
-   * failing push are discarded.
+   * Decodes a chunk and returns every complete message. A partial message is
+   * retained for the next call. Parse and field-reader errors are terminal and
+   * discard messages decoded earlier in the same call.
    *
-   * Byte fields on the returned messages - `DataRow` values, `CopyData` and
-   * `Unknown` payloads - are views into an internal buffer that the parser
-   * never rewrites, so they stay valid for as long as they are held. They are
-   * meant to be consumed before the next `push`: holding one keeps its whole
-   * buffer alive, so copy it if it has to outlive the row.
+   * **Details**
+   *
+   * `DataRow`, `CopyData`, and `Unknown` payloads are views into an internal
+   * buffer. Copy a payload that must outlive the current row, otherwise its
+   * entire buffer remains in memory.
    */
   readonly push: (chunk: Uint8Array) => ReadonlyArray<BackendMessage<A>>
+
+  /**
+   * Decodes a chunk and passes each complete message to `onMessage`
+   * immediately. This lets a `RowDescription` update `readField` before a
+   * `DataRow` later in the same chunk is decoded. The failure and
+   * buffer-lifetime rules match `push`, except messages
+   * delivered before a failure are not discarded.
+   */
+  readonly pushEach: (chunk: Uint8Array, onMessage: (message: BackendMessage<A>) => void) => void
 }
 
 /**
  * Creates a `Parser`.
  *
- * Special pre-startup replies have no type byte and are not handled here; use
- * `decodeSslResponse` for those.
+ * **Details**
+ *
+ * Special pre-startup replies have no type byte. Use `decodeSslResponse` for
+ * those replies.
  *
  * @category constructors
  * @since 4.0.0
@@ -114,15 +123,21 @@ export const makeParser = <A = Uint8Array | null>(options?: {
     end += chunk.length
   }
 
-  return {
+  const parser: Parser<A> = {
     readField: options?.readField,
     push(chunk) {
+      const messages: Array<BackendMessage<A>> = []
+      parser.pushEach(chunk, (message) => {
+        messages.push(message)
+      })
+      return messages
+    },
+    pushEach(chunk, onMessage) {
       if (failed) {
         throw new ParseError({ message: "Parser cannot be reused after a failure" })
       }
       try {
         append(chunk)
-        const messages: Array<BackendMessage<A>> = []
         while (end - start >= 5) {
           const length = (buffer[start + 1] << 24) | (buffer[start + 2] << 16) | (buffer[start + 3] << 8) |
             buffer[start + 4]
@@ -141,23 +156,23 @@ export const makeParser = <A = Uint8Array | null>(options?: {
           start = limit
           if (type === BackendType.DataRow) {
             // `buffer` always starts at byte 0 of `store`, so offsets index both.
-            messages.push(decodeDataRow<A>(buffer, store, 0, body, limit, this.readField))
+            onMessage(decodeDataRow<A>(buffer, store, 0, body, limit, parser.readField))
           } else {
             reader.reset(buffer, body, limit)
             const message = decodeBackend(type, reader)
             if (reader.offset !== limit) {
               throw new ParseError({ message: `Message has ${limit - reader.offset} trailing byte(s)` })
             }
-            messages.push(message as BackendMessage<A>)
+            onMessage(message as BackendMessage<A>)
           }
         }
-        return messages
       } catch (error) {
         failed = true
         throw error
       }
     }
   }
+  return parser
 }
 
 // -----------------------------------------------------------------------------
@@ -178,9 +193,8 @@ export interface Parse {
 }
 
 /**
- * Binds parameter values to a prepared statement, creating a portal.
- *
- * Parameters and results always use the binary format code.
+ * Binds parameter values to a prepared statement and creates a portal.
+ * Parameters and results use the binary format.
  *
  * @category models
  * @since 4.0.0
@@ -714,6 +728,12 @@ const encodeParseUnsafe = (options: Omit<Parse, "_tag">): Uint8Array => {
   return end()
 }
 
+/**
+ * Encodes a `Parse` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
 export const encodeParse = (options: Omit<Parse, "_tag">): Result.Result<Uint8Array, EncodeError> =>
   encodeResult(() => encodeParseUnsafe(options))
 
@@ -781,15 +801,19 @@ const encodeBindUnsafe = (options: Omit<Bind, "_tag">): Uint8Array => {
   return end()
 }
 
+/**
+ * Encodes a `Bind` message.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
 export const encodeBind = (options: Omit<Bind, "_tag">): Result.Result<Uint8Array, EncodeError> =>
   encodeResult(() => encodeBindUnsafe(options))
 
 /**
- * Where a value writes its wire bytes. `Bind` frames a parameter by leaving
- * room for its length, letting the sink fill in the body, and backfilling the
- * length from what was written, so a value never needs an array of its own.
- *
- * `PgTypes.writeParameter` is the implementation for OID-typed values.
+ * A sink for writing parameter bytes into a `Bind` frame. The frame reserves
+ * and backfills each parameter length. `PgTypes.writeParameter` supports
+ * OID-typed values.
  *
  * @category models
  * @since 4.0.0
@@ -816,24 +840,31 @@ export interface ValueSink {
   readonly endLength: (token: number) => void
 }
 
+const valueWriterUnsafe = Symbol.for("@effect/sql-pg/PgProtocol/ValueWriter/unsafe")
+
 /**
- * Builds a `Bind` encoder that writes parameters straight into the frame,
- * skipping the array per parameter that `encodeBind` has to copy from.
+ * Creates a `Bind` encoder that writes parameters directly into the frame.
+ *
+ * **Details**
+ *
+ * `textFormat` identifies parameters encoded as text. All other parameters
+ * use the binary format.
+ *
+ * **Example** (Encoding a `Bind` message)
  *
  * ```ts
  * import { PgProtocol, PgTypes } from "@effect/sql-pg"
  *
- * const encodeBind = PgProtocol.makeBindEncoder(PgTypes.writeParameter)
+ * const encodeBind = PgProtocol.makeBindEncoder(PgTypes.writeParameter, PgTypes.isTextFormat)
  * const frame = encodeBind({ portal: "", statement: "s1", parameters: [PgTypes.int4(1)] })
  * ```
  *
  * @category encoding
  * @since 4.0.0
  */
-const valueWriterUnsafe = Symbol.for("@effect/sql-pg/PgProtocol/ValueWriter/unsafe")
-
 export const makeBindEncoder = <A, E = never>(
-  writeParameter: (sink: ValueSink, value: A) => Result.Result<void, E>
+  writeParameter: (sink: ValueSink, value: A) => Result.Result<void, E>,
+  textFormat?: (value: A) => boolean
 ) =>
 (options: {
   readonly portal: string
@@ -846,16 +877,32 @@ export const makeBindEncoder = <A, E = never>(
     writer.cString(options.statement)
     const parameters = options.parameters
     const count = requireInt16Count(parameters.length, "Bind parameter")
-    writer.reserve(6)
-    const header = writer.bytes
-    const headerOffset = writer.offset
-    header[headerOffset] = 0
-    header[headerOffset + 1] = 1
-    header[headerOffset + 2] = 0
-    header[headerOffset + 3] = 1
-    header[headerOffset + 4] = count >>> 8
-    header[headerOffset + 5] = count
-    writer.offset = headerOffset + 6
+    let textCount = 0
+    if (textFormat !== undefined) {
+      for (let index = 0; index < count; index++) {
+        if (textFormat(parameters[index])) textCount++
+      }
+    }
+    if (textCount === 0 || textCount === count) {
+      // One format code covering every parameter: binary, or all-text.
+      const code = textCount === 0 ? 1 : 0
+      writer.reserve(6)
+      const header = writer.bytes
+      const headerOffset = writer.offset
+      header[headerOffset] = 0
+      header[headerOffset + 1] = 1
+      header[headerOffset + 2] = 0
+      header[headerOffset + 3] = code
+      header[headerOffset + 4] = count >>> 8
+      header[headerOffset + 5] = count
+      writer.offset = headerOffset + 6
+    } else {
+      writer.int16(count)
+      for (let index = 0; index < count; index++) {
+        writer.int16(textFormat!(parameters[index]) ? 0 : 1)
+      }
+      writer.int16(count)
+    }
     const writeUnsafe = (writeParameter as any)[valueWriterUnsafe] as
       | ((sink: ValueSink, value: A) => void)
       | undefined
@@ -1291,17 +1338,13 @@ export interface DataRow<out A = Uint8Array | null> {
 }
 
 /**
- * Reads one `DataRow` field out of the parser's buffer, for a parser given a
- * `readField`. `size` is -1 for SQL NULL, and `column` is the field's position
- * in the row.
+ * Reads one `DataRow` field from the parser buffer.
  *
- * The bytes are the parser's buffer rather than a view of the field, so they
- * are only the field's for `offset` to `offset + size`, and reading outside
- * that reads the rest of the stream. `PgTypes.makeFieldReader` is the
- * implementation for OID-typed columns.
+ * **Details**
  *
- * A reader runs inside the stateful parser. If it throws, that failure is
- * terminal just like a `ParseError`.
+ * `size` is `-1` for SQL `NULL`, and `column` is the field index. Only bytes
+ * from `offset` through `offset + size` belong to the field. A thrown error
+ * permanently fails the parser.
  *
  * @category models
  * @since 4.0.0