turbine-orm 0.53.0 → 0.54.0

package/dist/cjs/client.js

@@ -62,6 +62,23 @@ async function withRetry(fn, options) {
     }
     throw lastError;
 }
+/**
+ * The accepted `plan_cache_mode` values, as a runtime set.
+ *
+ * A GUC name/value pair cannot be a bind parameter (`SET plan_cache_mode = $1`
+ * is a syntax error), so the emitted statement necessarily contains a literal.
+ * This CLOSED SET is therefore the entire safety boundary: the statement is
+ * built from the matched MEMBER of this set, never from the caller's string,
+ * so no input a caller can supply reaches the SQL text even if it compares
+ * equal under some looser rule. Anything not in the set is refused at
+ * construction. Module-private and frozen, so the set itself is not a mutation
+ * target either.
+ */
+const PLAN_CACHE_MODES = Object.freeze([
+    'auto',
+    'force_custom_plan',
+    'force_generic_plan',
+]);
 // ---------------------------------------------------------------------------
 // Unknown-config-key diagnostics
 // ---------------------------------------------------------------------------
@@ -92,6 +109,7 @@ const TURBINE_CONFIG_KEYS = {
     defaultLimit: true,
     warnOnUnlimited: true,
     utcTimestamps: true,
+    planCacheMode: true,
     scopedConnect: true,
     relationLoadStrategy: true,
     stableRelationOrder: true,
@@ -431,21 +449,33 @@ class TurbineClient {
     schema;
     static int8ParserRegistered = false;
     /**
-     * The `utcTimestamps` value the FIRST Turbine-owned pool in this process
-     * settled the OID 1114 read parser on, or `undefined` while no Turbine-owned
-     * client has been constructed yet.
+     * The `utcTimestamps` value the FIRST TurbineClient in this process settled
+     * on, or `undefined` while none has been constructed yet.
      *
      * `pg.types.setTypeParser` is process-global by nature: there is one parser
      * per OID for the whole pg module, so the READ side of `utcTimestamps` cannot
      * be per client the way the WRITE side is. Recording the settled value (not
      * just "registered yes/no") is what lets the constructor detect a second
      * client asking for the opposite and refuse it, instead of handing back a
-     * client whose reads and writes disagree. See {@link assertUtcTimestampsAgree}.
+     * client whose reads and writes disagree. Every client records it, including
+     * one on an external pool, which registers nothing but still READS through
+     * whatever an owned client in the same process installed. See
+     * {@link assertUtcTimestampsAgree}.
      */
     static utcTimestampParserMode;
+    /**
+     * Whether the zone-less temporal read parsers (OIDs 1114, 1082, 1115, 1182)
+     * have actually been installed. Separate from
+     * {@link utcTimestampParserMode}, which every client settles: only an OWNED
+     * pool registers, so a client on an external pool must not make a later
+     * owned client skip registration.
+     */
+    static utcTimestampParsersRegistered = false;
     logging;
     /** Active SQL dialect, owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     dialect;
+    /** Validated `plan_cache_mode` to pin on every owned connection, or undefined to issue nothing. */
+    planCacheMode;
     tableCache = new Map();
     middlewares = [];
     queryListeners = new Set();
@@ -538,6 +568,12 @@ class TurbineClient {
         // Name any key on the config object that is not part of the config surface
         // (dev only, once per key, never throws). See warnUnknownConfigKeys.
         warnUnknownConfigKeys(config);
+        // ALL config validation runs before ANY process-global side effect below.
+        // A constructor that throws must leave the process exactly as it found it:
+        // settling the process-global parser mode and then rejecting the config
+        // would poison the next, valid, TurbineClient with a phantom conflict.
+        const dialect = config.dialect ?? dialect_js_1.postgresDialect;
+        const planCacheMode = TurbineClient.resolvePlanCacheMode(config.planCacheMode, dialect);
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
          * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
@@ -569,7 +605,8 @@ class TurbineClient {
             });
             TurbineClient.int8ParserRegistered = true;
         }
-        // Parse `timestamp` (OID 1114) as UTC instead of server-local time. The
+        // Parse the zone-less temporal types (`timestamp` OID 1114, `date` OID
+        // 1082, and their array forms 1115 / 1182) as UTC instead of local time. The
         // pg driver's default hands back a Date built in the process's local zone,
         // so the same row yields a different instant per deployment region. The
         // ORM convention (Prisma, Rails, Django), and the only interpretation
@@ -580,16 +617,23 @@ class TurbineClient {
         // same flag is per client (query/writes.ts). Two clients disagreeing about
         // it therefore cannot both be served, so the disagreement is refused here
         // rather than resolved silently into a client that does not round-trip.
-        if (ownsAnyPool) {
-            const wantUtcTimestamps = config.utcTimestamps !== false;
-            TurbineClient.assertUtcTimestampsAgree(wantUtcTimestamps);
-            if (wantUtcTimestamps && TurbineClient.utcTimestampParserMode === undefined) {
-                pg_1.default.types.setTypeParser(1114, (val) => new Date(`${val.replace(' ', 'T')}Z`));
-            }
-            TurbineClient.utcTimestampParserMode = wantUtcTimestamps;
+        //
+        // The AGREEMENT check runs for EVERY client, owned pool or not. Only an
+        // owned pool ever REGISTERS the parsers, but once any client has registered
+        // them every client in the process reads through them, including one on an
+        // external pool: it would then read UTC while its own per-client write half
+        // still rendered local literals, which on a `date` column walks the stored
+        // calendar day backwards one day per read-modify-write cycle.
+        const wantUtcTimestamps = config.utcTimestamps !== false;
+        TurbineClient.assertUtcTimestampsAgree(wantUtcTimestamps);
+        if (ownsAnyPool && wantUtcTimestamps && !TurbineClient.utcTimestampParsersRegistered) {
+            (0, utils_js_1.registerUtcTemporalParsers)();
+            TurbineClient.utcTimestampParsersRegistered = true;
         }
+        TurbineClient.utcTimestampParserMode = wantUtcTimestamps;
         this.logging = config.logging ?? false;
-        this.dialect = config.dialect ?? dialect_js_1.postgresDialect;
+        this.dialect = dialect;
+        this.planCacheMode = planCacheMode;
         this.schema = schema;
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
@@ -682,7 +726,7 @@ class TurbineClient {
             if (config.ssl !== undefined) {
                 poolConfig.ssl = config.ssl;
             }
-            this.pool = new pg_1.default.Pool(poolConfig);
+            this.pool = new pg_1.default.Pool(TurbineClient.withPlanCacheMode(poolConfig, this.planCacheMode));
             this.ownsPool = true;
             this.pool.on('error', (err) => {
                 console.error('[turbine] Unexpected pool error:', err.message);
@@ -698,13 +742,13 @@ class TurbineClient {
         this.ownedReplicaPools = [];
         for (const replica of config.replicas ?? []) {
             if (typeof replica === 'string') {
-                const replicaPool = new pg_1.default.Pool({
+                const replicaPool = new pg_1.default.Pool(TurbineClient.withPlanCacheMode({
                     connectionString: replica,
                     max: config.poolSize ?? config.max ?? 10,
                     idleTimeoutMillis: config.idleTimeoutMs ?? config.idleTimeoutMillis ?? 30_000,
                     connectionTimeoutMillis: config.connectionTimeoutMs ?? config.connectionTimeoutMillis ?? 5_000,
                     ...(config.ssl !== undefined ? { ssl: config.ssl } : {}),
-                });
+                }, this.planCacheMode));
                 replicaPool.on('error', (err) => {
                     console.error('[turbine] Unexpected replica pool error:', err.message);
                 });
@@ -715,6 +759,27 @@ class TurbineClient {
                 this.replicaPools.push(replica);
             }
         }
+        // `planCacheMode` reaches a pool only where Turbine opens the connections.
+        // Warned here rather than in the external-pool branch above because the
+        // owned string replicas are built after it: with an external primary and
+        // owned replicas the option is applied to the replicas and dropped on the
+        // primary, and a warning that said it was "ignored" would be false.
+        // Deliberate no-op rather than a throw: the option is a performance knob,
+        // and an app that moves from an owned pool to a serverless driver should
+        // not stop booting over it. Same ownership rule as the type parsers, which
+        // also skip external pools silently.
+        if (this.planCacheMode !== undefined && !this.ownsPool && process.env.NODE_ENV !== 'production') {
+            if ((0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.planCacheModeIgnored, this.planCacheMode)) {
+                const replicaNote = this.ownedReplicaPools.length > 0
+                    ? ` It IS applied to the ${this.ownedReplicaPools.length} Turbine-owned read replica pool(s) on this ` +
+                        'client, so reads and writes would run under different plan-cache policies until the primary is set too.'
+                    : '';
+                console.warn(`[turbine] planCacheMode: '${this.planCacheMode}' was not applied to the primary: this client was given an ` +
+                    'external `pool`, whose connection lifecycle the caller owns, so Turbine never opens its connections. Set ' +
+                    `\`plan_cache_mode\` in the driver's own connection setup (or run \`SET plan_cache_mode = ${this.planCacheMode}\` ` +
+                    `on checkout) instead.${replicaNote}`);
+            }
+        }
         this.replicaTableCaches = this.replicaPools.map(() => new Map());
         if (this.logging && this.replicaPools.length > 0) {
             console.log(`[turbine] ${this.replicaPools.length} read replica(s) configured (${this.ownedReplicaPools.length} owned)`);
@@ -736,19 +801,128 @@ class TurbineClient {
         }
     }
     /**
-     * Refuse a `utcTimestamps` value that contradicts the one the process-global
-     * OID 1114 read parser was already settled on.
+     * Validate a caller-supplied `planCacheMode` and refuse it on an engine that
+     * has no plan cache to pin.
+     *
+     * Two refusals, both at construction rather than at first query, so a
+     * misconfigured client never opens a connection:
+     *
+     *   - a value outside {@link PLAN_CACHE_MODES} throws `ValidationError`
+     *     (E003). This is the security boundary as well as the usability one: a
+     *     GUC value cannot be a bind parameter in either place it can be set (a
+     *     `SET` statement or the connection `options` string), so the returned
+     *     value is a MEMBER OF THE FROZEN LIST, never the caller's string, and
+     *     there is no path by which caller text reaches the connection or the SQL.
+     *   - a dialect that does not report `supportsPlanCacheMode` throws
+     *     `UnsupportedFeatureError` (E017), in the same style as the other
+     *     capability refusals.
+     */
+    static resolvePlanCacheMode(mode, dialect) {
+        if (mode === undefined || mode === null)
+            return undefined;
+        const matched = PLAN_CACHE_MODES.find((m) => m === mode);
+        if (matched === undefined) {
+            throw new errors_js_1.ValidationError(`[turbine] Invalid planCacheMode: ${JSON.stringify(mode)}. Expected one of ${PLAN_CACHE_MODES.map((m) => `'${m}'`).join(', ')}.`);
+        }
+        if (dialect.supportsPlanCacheMode !== true) {
+            throw new errors_js_1.UnsupportedFeatureError(`The planCacheMode option (plan_cache_mode = ${matched})`, dialect.name, '`plan_cache_mode` is a PostgreSQL plan-cache setting with no equivalent on this engine. Remove the option, ' +
+                'or set it only on the PostgreSQL client.');
+        }
+        return matched;
+    }
+    /**
+     * Pin `plan_cache_mode` on every connection an OWNED pool opens, by putting
+     * it in the pool's **connection parameters** rather than issuing a `SET`.
+     *
+     * PostgreSQL's `options` startup parameter (`-c plan_cache_mode=...`) is
+     * applied by the backend as it starts the session, so the setting is in force
+     * for the connection's very first statement and for its whole life: every
+     * pooled checkout, `$transaction`, stream and pipeline on it inherits it.
+     * There is no per-checkout reset, and none is wanted, that IS the intent.
+     *
+     * Why not `pool.on('connect', c => c.query('SET ...'))`, the obvious
+     * alternative: pg hands the fresh client to the waiting caller in the same
+     * tick it emits `connect`, so the caller's first query is issued while the
+     * `SET` is still the active query. That path works today only through pg's
+     * deprecated same-client query queueing (it logs a DeprecationWarning per new
+     * connection and is slated for removal in pg 9), and it costs an extra round
+     * trip on every connection. The startup parameter costs nothing and cannot
+     * race.
+     *
+     * Nothing the caller already set is discarded, in either of the two places
+     * pg reads `options` from. pg's `ConnectionParameters` lets a value parsed
+     * out of a `connectionString` OVERRIDE the explicit `options` field, so when
+     * the URL already carries `?options=...` the GUC is appended THERE; and the
+     * explicit field itself falls back to `process.env.PGOPTIONS` only while it
+     * is unset, so setting it blind would silently drop a deployment's
+     * `PGOPTIONS` (its `search_path` or `statement_timeout`, not merely a slower
+     * plan). Both are read first and the GUC is appended to whichever applies.
+     *
+     * One deployment caveat: an `options` startup parameter is a connection-time
+     * parameter, and a connection pooler in front of Postgres may reject
+     * parameters it is not configured to pass through (PgBouncer's
+     * `ignore_startup_parameters`). A `SET` on checkout would survive that, at
+     * the cost of the race and the round trip above. Callers behind such a pooler
+     * should set the GUC on the server or role instead
+     * (`ALTER ROLE ... SET plan_cache_mode = ...`).
+     */
+    static withPlanCacheMode(poolConfig, mode) {
+        if (mode === undefined)
+            return poolConfig;
+        // `mode` is a member of PLAN_CACHE_MODES, never caller text (see
+        // resolvePlanCacheMode), which is what makes this literal safe: a GUC value
+        // cannot be a bind parameter.
+        const setting = `-c plan_cache_mode=${mode}`;
+        const merged = poolConfig.connectionString
+            ? TurbineClient.mergeConnectionStringOptions(poolConfig.connectionString, setting)
+            : null;
+        if (merged)
+            return { ...poolConfig, connectionString: merged };
+        // pg reads `config.options` when truthy and `process.env.PGOPTIONS`
+        // otherwise, so an unmerged setting would replace the caller's PGOPTIONS
+        // rather than add to it.
+        const existing = poolConfig.options || (typeof process !== 'undefined' ? process.env?.PGOPTIONS : undefined);
+        return { ...poolConfig, options: existing ? `${existing} ${setting}` : setting };
+    }
+    /**
+     * `connectionString` with `setting` appended to its existing `options` query
+     * parameter, or `null` when it carries no `options` (in which case the caller
+     * should use the `options` pool field, which is not overridden).
+     *
+     * Only the query string is rewritten, never the userinfo or host, so a
+     * percent-encoded password cannot be mangled by a round trip through `URL`.
+     * The split is on the first `?`, which is also where pg's own parser puts the
+     * query-string boundary: a connection string with an unencoded `?` inside the
+     * password is not parseable by pg either, so there is no shape this handles
+     * differently from the driver.
+     */
+    static mergeConnectionStringOptions(connectionString, setting) {
+        const q = connectionString.indexOf('?');
+        if (q === -1)
+            return null;
+        const params = new URLSearchParams(connectionString.slice(q + 1));
+        const existing = params.get('options');
+        if (existing === null)
+            return null;
+        params.set('options', `${existing} ${setting}`);
+        return connectionString.slice(0, q + 1) + params.toString();
+    }
+    /**
+     * Refuse a `utcTimestamps` value that contradicts the one an earlier client
+     * in this process settled the zone-less temporal read parsers (OIDs 1114,
+     * 1082, 1115, 1182) on.
      *
      * The flag has two halves. The WRITE half is per client: a bound `Date` on a
      * zone-less `date` / `timestamp` column is rewritten to a UTC literal unless
      * the owning client opted out (`coerceWriteValue` in query/writes.ts). The
-     * READ half is the pg type parser for OID 1114, and `pg.types.setTypeParser`
-     * installs ONE parser per OID for the whole process, shared by every pool,
-     * every raw query, and any other library using the same pg module. There is
-     * no per-pool parser hook to bind it to, and moving the coercion into
-     * `parseRow` instead would leave every non-ORM read (raw SQL, `client.sql`,
-     * a caller's own `pool.query`) on the driver's value while changing the
-     * default path's output type, so the read half stays process-wide.
+     * READ half is the pg type parsers for OIDs 1114 / 1082 / 1115 / 1182, and
+     * `pg.types.setTypeParser` installs ONE parser per OID for the whole process,
+     * shared by every pool, every raw query, and any other library using the same
+     * pg module. There is no per-pool parser hook to bind it to, and moving the
+     * coercion into `parseRow` instead would leave every non-ORM read (raw SQL,
+     * `client.sql`, a caller's own `pool.query`) on the driver's value while
+     * changing the default path's output type, so the read half stays
+     * process-wide.
      *
      * That makes the mixed shape unserveable rather than merely awkward: the
      * second client would write local calendar fields and read them back as UTC
@@ -756,16 +930,23 @@ class TurbineClient {
      * A client that silently does not round-trip is the worst of the three
      * outcomes, so construction fails with the two ways out.
      *
-     * Only Turbine-owned pools take part. An external pool (Neon, Vercel
-     * Postgres, Hyperdrive) inherits the caller's parser configuration and
-     * Turbine never registers on its behalf, so it has no read half to contradict.
+     * EVERY client takes part, not only the ones on a Turbine-owned pool. Only an
+     * owned pool REGISTERS the parsers, but registration is process-global, so a
+     * client on an external pool (Neon, Vercel Postgres, Hyperdrive) constructed
+     * alongside an owned one reads through them too. It is exactly the pairing
+     * that produced a silent read/write disagreement: an external-pool client
+     * with `utcTimestamps: false` writing local `date` literals while reading UTC
+     * ones, which walks the stored calendar day back a day per read-modify-write
+     * cycle. An external-pool client ALONE in a process is unaffected: it settles
+     * the value, registers nothing, and keeps the caller's parser configuration.
      */
     static assertUtcTimestampsAgree(want) {
         const settled = TurbineClient.utcTimestampParserMode;
         if (settled === undefined || settled === want)
             return;
         throw new errors_js_1.ValidationError(`[turbine] utcTimestamps: ${want} conflicts with utcTimestamps: ${settled}, which an earlier TurbineClient ` +
-            'in this process already applied. The timestamp READ parser (pg OID 1114) is process-global, so it cannot ' +
+            'in this process already applied. The zone-less temporal READ parsers (pg OIDs 1114, 1082, 1115, 1182) are ' +
+            'process-global, so they cannot ' +
             'differ per client, while the WRITE side is per client. Serving both values would give this client a ' +
             `${want ? 'UTC write' : 'local write'} and a ${settled ? 'UTC read' : 'local read'}, so every zone-less ` +
             '`timestamp` it writes would read back shifted by the process offset. Give every TurbineClient in this ' +

package/dist/cjs/dialect.d.ts

@@ -370,6 +370,30 @@ export interface Dialect {
     readonly supportsRLS: boolean;
     /** Whether this dialect/engine supports advisory-lock-style migration locking. */
     readonly supportsAdvisoryLock: boolean;
+    /**
+     * Whether this dialect/engine understands the `plan_cache_mode` session
+     * setting (`SET plan_cache_mode = auto | force_custom_plan |
+     * force_generic_plan`). Gates the opt-in `planCacheMode` client option.
+     *
+     * A capability flag rather than a `dialect.name === 'postgresql'` test, for
+     * the same reason every other refusal here is one: the setting is a property
+     * of the PostgreSQL PLAN CACHE, not of the SQL string, so a
+     * Postgres-compatible dialect that grows one can opt in without editing
+     * client.ts, and one that has the wire protocol but not the plan cache
+     * (which is why it is not simply inherited) can leave it off. Optional:
+     * absent is treated as `false`, so every engine that predates the flag keeps
+     * throwing {@link UnsupportedFeatureError} (E017).
+     *
+     * The flag speaks for the DIALECT, not for the server on the other end. A
+     * Postgres wire-compatible engine driven through `postgresDialect`
+     * (CockroachDB, YugabyteDB, or a pre-12 PostgreSQL) reports `true` here and
+     * will instead be refused by the server itself with `unrecognized
+     * configuration parameter` when the connection is opened. Turbine has no
+     * client-level seam that identifies those engines (`DatabaseAdapter` is a
+     * CLI/migration concern and defines no dialect), and the same is already true
+     * of the other Postgres-only capabilities on this dialect.
+     */
+    readonly supportsPlanCacheMode?: boolean;
     /**
      * Whether this dialect supports `LEFT JOIN LATERAL (...) ON true` in the FROM
      * clause. Gates the opt-in `plan: 'lateral'` pick-row ordering. Optional:

package/dist/cjs/dialect.js

@@ -61,6 +61,7 @@ exports.postgresDialect = {
     supportsListenNotify: true,
     supportsRLS: true,
     supportsAdvisoryLock: true,
+    supportsPlanCacheMode: true,
     supportsLateralJoin: true,
     explainQuery: { prefix: 'EXPLAIN' },
     paramPlaceholder(index) {

package/dist/cjs/index.d.ts

@@ -34,7 +34,7 @@
  */
 export type { DatabaseAdapter, IntrospectionOverrides } from './adapters/index.js';
 export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
-export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, type TurbineDriver, withRetry, } from './client.js';
+export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type PlanCacheMode, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, type TurbineDriver, withRetry, } from './client.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, ResultStrategy, StreamableConnection, UpsertStatementInput, } from './dialect.js';
 export { postgresDialect } from './dialect.js';
 export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, ReadOnlyError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';

package/dist/cjs/mssql.js

@@ -509,6 +509,7 @@ exports.mssqlDialect = {
     // SQL Server has OUTER APPLY, not FROM-clause LATERAL: the lateral pick plan
     // is Postgres-only (out of scope here).
     supportsLateralJoin: false,
+    supportsPlanCacheMode: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // No in-band EXPLAIN: SQL Server's SHOWPLAN is a session toggle

package/dist/cjs/mysql.js

@@ -391,6 +391,7 @@ exports.mysqlDialect = {
     // MySQL 8.0.14+ supports LATERAL, but the opt-in lateral pick plan stays
     // Postgres-only in this release (flipping it on is a one-line change + tests).
     supportsLateralJoin: false,
+    supportsPlanCacheMode: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // Plain `EXPLAIN` (one row of tabular plan columns) works on every supported

package/dist/cjs/powdb.js

@@ -159,6 +159,7 @@ exports.powdbDialect = {
     // PowQL has no LATERAL construct; PowqlInterface refuses pick ordering
     // earlier, this override keeps the flag truthful if a future path consults it.
     supportsLateralJoin: false,
+    supportsPlanCacheMode: false,
     beginStatement: () => 'begin',
     commitStatement: () => 'commit',
     rollbackStatement: () => 'rollback',

package/dist/cjs/query/builder.js

@@ -612,7 +612,8 @@ class QueryInterface {
             // the flag and rewrote binds the caller had opted out of.
             //
             // This half of the flag is PER CLIENT. The read half is not: it is the
-            // pg OID 1114 type parser, which `pg.types.setTypeParser` installs once
+            // pg type parsers for OIDs 1114 / 1082 / 1115 / 1182, which
+            // `pg.types.setTypeParser` installs once
             // per process. Two clients in one process therefore cannot hold
             // different values, and TurbineClient refuses the second one rather than
             // building a client whose writes and reads disagree (see
@@ -3078,10 +3079,18 @@ class QueryInterface {
                 // single Invalid Date, the column was unreadable on every strategy.
                 // The join strategy's string arrays are handled upstream instead, by
                 // the JSON-wire decode in relations.ts.
+                //
+                // A NUMBER is excluded for the same reason: the driver returns the
+                // JS numbers `Infinity` / `-Infinity` for the Postgres `infinity` /
+                // `-infinity` timestamp values, and re-coercing one ran
+                // `parseDbDate(String(Infinity))` = `parseDbDate('Infinity')`, which
+                // is an Invalid Date that JSON-encodes as null. The array form escaped
+                // this only because it took the branch above.
                 if ((dateCols.has(col) || camelDateFields.has(field)) &&
                     value !== null &&
                     !(value instanceof Date) &&
-                    !Array.isArray(value)) {
+                    !Array.isArray(value) &&
+                    typeof value !== 'number') {
                     // Offset-less strings (Postgres `timestamp`, json_agg output) are
                     // pinned to UTC so results don't depend on the server's time zone.
                     parsed[field] = this.utcTimestamps ? (0, utils_js_1.parseDbDate)(String(value)) : new Date(value);

package/dist/cjs/query/utils.d.ts

@@ -176,6 +176,90 @@ export declare function coerceTemporalValue(dbType: string | undefined, value: u
  * as-is.
  */
 export declare function parseDbDate(value: string): Date;
+/**
+ * Build the driver parser for Postgres `date` (OID 1082) that reads a
+ * zone-less calendar day as **UTC midnight**.
+ *
+ * The pg default builds the Date from the process's LOCAL zone, so the stored
+ * calendar day `2026-07-21` comes back as `2026-07-20T22:00:00Z` in
+ * `Europe/Berlin` and `2026-07-20T15:00:00Z` in `Asia/Tokyo`: the wrong
+ * calendar day everywhere east of UTC, and the wrong instant everywhere except
+ * UTC itself. It is also the exact mirror-image of the WRITE side, which
+ * already renders a bound `Date` from its UTC components
+ * ({@link toLocalDateTimeLiteral}), so today a read-modify-write cycle on a
+ * `date` column east of UTC walks the stored day one day earlier per cycle.
+ * This is the missing read half of `utcTimestamps`, matching what
+ * {@link parseDbDate} already does for the JSON path and what the OID 1114
+ * parser already does for `timestamp`.
+ *
+ * `fallback` is the parser this one REPLACES, and it must be captured with
+ * `pg.types.getTypeParser(1082, 'text')` BEFORE registration (reading it after
+ * would hand back this function and recurse forever). It keeps `infinity` /
+ * `-infinity` on the driver's `Infinity` / `-Infinity`.
+ *
+ * `setUTCFullYear` rather than the `Date` constructor, so a two-or-three-digit
+ * year is not silently mapped into the 1900s, and ` BC` maps to the
+ * astronomical year (`0044 BC` → -43) the way the driver's own parser does.
+ */
+export declare function createUtcDateParser(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * Build the driver parser for Postgres `timestamp` (OID 1114) that reads an
+ * offset-less date-time as UTC. Also lifted to the `_timestamp` array OID
+ * (1115), so the scalar and the array can never settle on different
+ * interpretations.
+ *
+ * `fallback` is the parser this one REPLACES and must be captured with
+ * `pg.types.getTypeParser(1114, 'text')` BEFORE registration (see
+ * {@link createUtcDateParser}). It is what keeps `infinity` / `-infinity` on
+ * the driver's `Infinity` / `-Infinity`: the earlier
+ * `new Date(text.replace(' ', 'T') + 'Z')` form turned `'infinity'` into
+ * `'infinityZ'` and so into an `Invalid Date` that flowed on silently.
+ *
+ * Component assembly rather than `Date` string parsing, for the same reason as
+ * the `date` parser: a year outside four digits and a ` BC` suffix are not
+ * parseable as ISO-8601 and would otherwise also become `Invalid Date`.
+ * Fractional seconds are truncated to milliseconds, which is what
+ * `Date`-string parsing did too.
+ */
+export declare function createUtcTimestampParser(fallback: (text: string) => unknown): (text: string) => unknown;
+/**
+ * The offset-less-timestamp-as-UTC reading, with no fallback: `text` must be a
+ * plain `YYYY-MM-DD HH:MM:SS[.ffffff]`. Used where the input shape is already
+ * known (tests, JSON-wire coercion); the DRIVER parser is
+ * {@link createUtcTimestampParser}, which delegates everything else.
+ */
+export declare function parseUtcTimestampText(text: string): Date;
+/**
+ * Lift an element parser to the matching Postgres array OID.
+ *
+ * Array OIDs do NOT inherit their element type's parser: registering a parser
+ * for `date` (1082) leaves `date[]` (1182) on the driver's default, so the same
+ * value read from a scalar column and from an array column would disagree by
+ * the process offset. Every scalar temporal parser Turbine registers is
+ * therefore registered in its array form too.
+ *
+ * `pg.types.arrayParser` is a public member of the `pg` module (it is what the
+ * driver's own `_text` / `_date` parsers are built from), so this adds no
+ * dependency. NULL elements stay `null` and are never handed to `element`.
+ */
+export declare function createPgArrayParser(element: (text: string) => unknown): (text: string) => unknown[];
+/**
+ * Register the UTC readings of the four zone-less temporal OIDs on the pg
+ * module: `timestamp` (1114), `date` (1082) and their array forms (1115, 1182).
+ *
+ * ONE place, because `pg.types.setTypeParser` is process-global and the pairing
+ * matters: registering a scalar without its array form, or a `date` without the
+ * `timestamp` beside it, produces two columns of the same row disagreeing about
+ * what the same wire text means. Both callers are processes Turbine owns the
+ * pg module in: `TurbineClient` on a pool it created (never on an external
+ * pool, whose parser configuration belongs to the caller), and `turbine studio`,
+ * which builds a raw pool of its own and must render what the application sees.
+ *
+ * Each fallback is read BEFORE its parser is installed, so an unrecognised wire
+ * value (`infinity`, and whatever a future server adds) still reaches the
+ * driver's own parser.
+ */
+export declare function registerUtcTemporalParsers(): void;
 /**
  * Postgres type name → OID, for every type family whose `json_build_object`
  * rendering is NOT the value the pg driver produces for the same column.
@@ -196,7 +280,7 @@ export declare function parseDbDate(value: string): Date;
  *   numeric      '1000.50'   (string)         1000.5    (number, LOSSY)
  *   int8         '9007199254740993'           9007199254740992 (LOSSY)
  *   bytea        Buffer                       '\xdeadbeef' (string)
- *   date         Date (local midnight)        Date (UTC midnight, off by tz)
+ *   date         Date (UTC midnight)          Date (UTC midnight, by coincidence)
  *   interval     { days, hours, … }           '1 day 02:03:04' (string)
  *   point        { x, y }                     '(1,2)'   (string)
  *   circle       { x, y, radius }             '<(1,2),3>' (string)