@effect/sql-pg 4.0.0-rc.115 → 4.0.0-rc.117

package/src/PgMigrator.ts

@@ -13,12 +13,12 @@ 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 Redacted from "effect/Redacted"
 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 Password from "./internal/password.ts"
 import { PgClient } from "./PgClient.ts"
 
 /**
@@ -45,7 +45,7 @@ export const run: <R2 = never>(
   | R2
 > = Migrator.make({
   dumpSchema(path, table) {
-    const pgDump = (args: Array<string>) =>
+    const pgDump = (args: Array<string>, password: string | undefined) =>
       Effect.gen(function*() {
         const sql = yield* PgClient
         const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
@@ -55,9 +55,7 @@ export const run: <R2 = never>(
             PGHOST: sql.config.host,
             PGPORT: sql.config.port?.toString(),
             PGUSER: sql.config.username,
-            PGPASSWORD: sql.config.password
-              ? Redacted.value(sql.config.password)
-              : undefined,
+            PGPASSWORD: password,
             PGDATABASE: sql.config.database,
             PGSSLMODE: sql.config.ssl ? "require" : "prefer"
           }
@@ -69,21 +67,20 @@ export const run: <R2 = never>(
           .replace(/\n{2,}/gm, "\n\n")
           .trim();
       }).pipe(
-        Effect.mapError((error) => new Migrator.MigrationError({ kind: "Failed", message: error.message }))
+        Effect.mapError((error) =>
+          new Migrator.MigrationError({ kind: "Failed", message: error.message, cause: error })
+        )
       )
 
-    const pgDumpSchema = pgDump(["--schema-only"])
-
-    const pgDumpMigrations = pgDump([
-      "--column-inserts",
-      "--data-only",
-      `--table=${table}`
-    ])
-
-    const pgDumpAll = Effect.map(
-      Effect.all([pgDumpSchema, pgDumpMigrations], { concurrency: 2 }),
-      ([schema, migrations]) => schema + "\n\n" + migrations
-    )
+    const pgDumpAll = Effect.gen(function*() {
+      const sql = yield* PgClient
+      const password = yield* Password.resolve(sql.config.password)
+      const [schema, migrations] = yield* Effect.all([
+        pgDump(["--schema-only"], password),
+        pgDump(["--column-inserts", "--data-only", `--table=${table}`], password)
+      ], { concurrency: 2 })
+      return schema + "\n\n" + migrations
+    })
 
     const pgDumpFile = (path: string) =>
       Effect.gen(function*() {
@@ -93,7 +90,9 @@ export const run: <R2 = never>(
         yield* fs.makeDirectory(path_.dirname(path), { recursive: true })
         yield* fs.writeFileString(path, dump)
       }).pipe(
-        Effect.mapError((error) => new Migrator.MigrationError({ kind: "Failed", message: error.message }))
+        Effect.mapError((error) =>
+          new Migrator.MigrationError({ kind: "Failed", message: error.message, cause: error })
+        )
       )
 
     return pgDumpFile(path)

package/src/PgPool.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

@@ -10,9 +10,21 @@
  * There is no `typeof` inference: an OID is always supplied, either directly
  * or through a constructor such as `int4` that carries it.
  *
- * `timestamp` has no time zone on the wire and is treated as UTC in both
- * directions. Decoding drops sub-millisecond precision by truncating toward
- * zero, including for timestamps before the PostgreSQL epoch.
+ * `timestamp` and `timestamptz` values, including array elements, decode to
+ * `Date`. Encoders accept `Date` or epoch milliseconds.
+ * Decoding truncates to milliseconds toward zero relative to the PostgreSQL
+ * epoch. To restore numeric decoding, override the codecs with `register`
+ * or a client `Registry`.
+ *
+ * `infinity`, `-infinity` and values outside the JavaScript `Date` range
+ * (±8.64e15 epoch milliseconds) decode to an invalid `Date`. Numeric
+ * `±Infinity` encodes the PostgreSQL sentinels; encoding an invalid `Date` fails.
+ *
+ * The `timestamp` codec maps wall-clock fields to UTC fields of a `Date`.
+ * Date parameters bind as `timestamptz`, so inserting one into a `timestamp`
+ * column applies the session `TimeZone`. Use UTC or `timestamp(value)` to
+ * preserve its UTC fields. `timestamptz` round trips preserve the instant
+ * regardless of session timezone.
  *
  * @since 4.0.0
  */
@@ -301,6 +313,7 @@ export const OID = {
   timestamptz: 1184,
   timetz: 1266,
   numeric: 1700,
+  regclass: 2205,
   uuid: 2950,
   jsonb: 3802,
   boolArray: 1000,
@@ -324,6 +337,7 @@ export const OID = {
   timestamptzArray: 1185,
   timetzArray: 1270,
   numericArray: 1231,
+  regclassArray: 2210,
   uuidArray: 2951,
   jsonbArray: 3807
 } as const
@@ -350,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]
 ])
@@ -992,20 +1007,22 @@ const readTimeMicros = (bytes: Uint8Array, offset: number): number => {
   return micros
 }
 
-/** The two halves of the int64 `timestampInt64` last produced. */
 let timestampHigh = 0
 let timestampLow = 0
 
 /**
- * Converts epoch milliseconds to the halves of the wire int64. Both encoding
- * paths read them from here rather than from a returned pair, so neither
- * allocates.
+ * Writes the wire int64 to timestampHigh/Low, avoiding a pair allocation.
  */
 const timestampInt64 = (value: unknown): void => {
-  const ms = requireNumber(value, "timestamp")
-  if (Number.isNaN(ms)) {
-    fail("timestamp cannot be NaN")
-  } else if (ms === Number.POSITIVE_INFINITY) {
+  let ms: number
+  if (value instanceof Date) {
+    ms = value.getTime()
+    if (Number.isNaN(ms)) fail("timestamp cannot be an invalid Date")
+  } else {
+    ms = typeof value === "number" ? value : fail("Expected a Date or number for timestamp")
+    if (Number.isNaN(ms)) fail("timestamp cannot be NaN")
+  }
+  if (ms === Number.POSITIVE_INFINITY) {
     timestampHigh = INT32_MAX
     timestampLow = -1
   } else if (ms === Number.NEGATIVE_INFINITY) {
@@ -1037,17 +1054,14 @@ const timestampCodec: UnsafeCodec<any> = codecOf(
     requireSize(size, 8, "timestamp")
     const high = readInt32(bytes, offset)
     if (high >= -MAX_EXACT_HIGH && high < MAX_EXACT_HIGH) {
-      // Inside these bounds the whole conversion is float arithmetic, so it
-      // allocates no BigInt. Everything outside them, the sentinels included,
-      // needs the exact 64-bit value.
+      // These bounds allow exact conversion without BigInt.
       const micros = high * 4294967296 + readUint32(bytes, offset + 4)
-      return (micros - micros % 1000) / 1000 + PG_EPOCH_MS
+      return new Date((micros - micros % 1000) / 1000 + PG_EPOCH_MS)
     }
     stage8(bytes, offset)
     const micros = scratchView8.getBigInt64(0)
-    if (micros === INT64_MAX) return Number.POSITIVE_INFINITY
-    if (micros === INT64_MIN) return Number.NEGATIVE_INFINITY
-    return Number(micros / THOUSAND) + PG_EPOCH_MS
+    if (micros === INT64_MAX || micros === INT64_MIN) return new Date(Number.NaN)
+    return new Date(Number(micros / THOUSAND) + PG_EPOCH_MS)
   },
   (value) => {
     timestampInt64(value)
@@ -1056,7 +1070,6 @@ const timestampCodec: UnsafeCodec<any> = codecOf(
     writeInt32(bytes, 4, timestampLow)
     return bytes
   },
-  // Two int32s are the int64, so the sink needs nothing of its own for it.
   (sink, value) => {
     timestampInt64(value)
     sink.int32(timestampHigh)
@@ -1150,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,
@@ -1214,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(
@@ -1399,6 +1412,13 @@ const lookupFor = (registry: Registry | undefined): Lookup =>
  * Registers a binary codec for an OID the built-in catalogue does not cover,
  * or overrides a built-in one. Registered codecs take precedence.
  *
+ * **Details**
+ *
+ * Unregistered OIDs decode as UTF-8 text. Register binary user-defined types
+ * to avoid garbled output or codec errors, which close the connection when
+ * reading rows. For arrays, use `makeRegistry().register` with
+ * `RegisterOptions.arrayOid` and pass the registry as the client's `types` option.
+ *
  * @category registry
  * @since 4.0.0
  */
@@ -1591,9 +1611,9 @@ export interface Column {
  *
  * **Details**
  *
- * Codecs are resolved once per column. SQL `NULL` becomes `null`, and columns
- * without a registered codec return a copy of their bytes. Text-format columns
- * fail with `CodecError`.
+ * Codecs are resolved once per column. SQL `NULL` becomes `null`.
+ * Unregistered OIDs decode as UTF-8 text. Invalid UTF-8 and text-format
+ * columns fail with `CodecError`.
  *
  * **Example** (Updating the reader after `RowDescription`)
  *
@@ -1624,7 +1644,7 @@ export const makeFieldReader = (
     return (bytes: Uint8Array, offset: number, size: number, column: number): unknown => {
       if (size < 0) return null
       const codec = codecs[column]
-      if (codec === undefined) return bytes.slice(offset, offset + size)
+      if (codec === undefined) return decodeUtf8(bytes, offset, size)
       const read = codec.read
       return read === undefined ? codec.decode(bytes.subarray(offset, offset + size)) : read(bytes, offset, size)
     }
@@ -1653,8 +1673,9 @@ export const encode = (value: unknown, oid: number, registry?: Registry): Result
  *
  * **Details**
  *
- * `format` must be `1`; the text format is not implemented. An OID that is
- * neither built in nor registered decodes to the raw bytes.
+ * Only binary format (`1`) is supported. Unregistered OIDs decode as UTF-8
+ * text; invalid UTF-8 fails with `CodecError`. See `register` for binary
+ * user-defined types, including arrays.
  *
  * @category decoding
  * @since 4.0.0
@@ -1670,7 +1691,7 @@ export const decode = (
       return fail(`Only the binary format is supported, received format ${format}`)
     }
     const codec = lookupFor(registry)(oid)
-    return codec === undefined ? bytes : codec.decode(bytes)
+    return codec === undefined ? decodeUtf8(bytes, 0, bytes.length) : codec.decode(bytes)
   })
 
 // -----------------------------------------------------------------------------
@@ -1962,21 +1983,21 @@ export const time: (value: bigint | null) => Parameter = parameter(OID.time)
 export const timetz: (value: string | null) => Parameter = parameter(OID.timetz)
 
 /**
- * A `timestamp` parameter, given as Unix epoch milliseconds and interpreted
- * as UTC.
+ * A `timestamp` parameter from a `Date` or epoch milliseconds. UTC fields
+ * become the stored wall-clock fields, regardless of session `TimeZone`.
  *
  * @category constructors
  * @since 4.0.0
  */
-export const timestamp: (value: number | null) => Parameter = parameter(OID.timestamp)
+export const timestamp: (value: Date | number | null) => Parameter = parameter(OID.timestamp)
 
 /**
- * A `timestamptz` parameter, given as Unix epoch milliseconds.
+ * A `timestamptz` parameter, given as a `Date` or Unix epoch milliseconds.
  *
  * @category constructors
  * @since 4.0.0
  */
-export const timestamptz: (value: number | null) => Parameter = parameter(OID.timestamptz)
+export const timestamptz: (value: Date | number | null) => Parameter = parameter(OID.timestamptz)
 
 /**
  * A one-dimensional array parameter whose elements have the given OID.

package/src/internal/connection.ts

@@ -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/password.ts

@@ -0,0 +1,11 @@
+import * as Effect from "effect/Effect"
+import * as Redacted from "effect/Redacted"
+
+export const resolve = (
+  password: Redacted.Redacted | Effect.Effect<Redacted.Redacted> | undefined
+): Effect.Effect<string | undefined> =>
+  password === undefined
+    ? Effect.succeed(undefined)
+    : Effect.isEffect(password)
+    ? Effect.map(password, Redacted.value)
+    : Effect.succeed(Redacted.value(password))