turbine-orm 0.53.0 → 0.54.0

package/dist/cjs/query/utils.js

@@ -22,6 +22,11 @@ exports.toLocalDateTimeLiteral = toLocalDateTimeLiteral;
 exports.temporalBindKind = temporalBindKind;
 exports.coerceTemporalValue = coerceTemporalValue;
 exports.parseDbDate = parseDbDate;
+exports.createUtcDateParser = createUtcDateParser;
+exports.createUtcTimestampParser = createUtcTimestampParser;
+exports.parseUtcTimestampText = parseUtcTimestampText;
+exports.createPgArrayParser = createPgArrayParser;
+exports.registerUtcTemporalParsers = registerUtcTemporalParsers;
 exports.jsonWireCoercionOid = jsonWireCoercionOid;
 exports.coerceJsonWireValue = coerceJsonWireValue;
 exports.closestName = closestName;
@@ -345,6 +350,151 @@ function parseDbDate(value) {
     return new Date(`${value.replace(' ', 'T')}Z`);
 }
 // ---------------------------------------------------------------------------
+// Driver type parsers for the zone-less temporal OIDs
+// ---------------------------------------------------------------------------
+/**
+ * A Postgres `date` wire value: `YYYY-MM-DD`, optionally with more than four
+ * year digits, optionally suffixed ` BC`. Anything else (`infinity`,
+ * `-infinity`, and any shape a future server adds) is deliberately NOT matched
+ * so it falls through to the driver's own parser untouched.
+ */
+const PG_DATE_TEXT_RE = /^(\d{4,})-(\d{2})-(\d{2})( BC)?$/;
+/**
+ * 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.
+ */
+function createUtcDateParser(fallback) {
+    return (text) => {
+        const m = PG_DATE_TEXT_RE.exec(text);
+        if (!m)
+            return fallback(text);
+        const year = m[4] ? -(Number(m[1]) - 1) : Number(m[1]);
+        const date = new Date(0);
+        date.setUTCFullYear(year, Number(m[2]) - 1, Number(m[3]));
+        date.setUTCHours(0, 0, 0, 0);
+        return date;
+    };
+}
+/**
+ * A Postgres `timestamp` (without time zone) wire value:
+ * `YYYY-MM-DD HH:MM:SS`, optionally with more than four year digits, optional
+ * fractional seconds, optional ` BC`. As with {@link PG_DATE_TEXT_RE},
+ * `infinity` / `-infinity` and any shape a future server adds deliberately do
+ * NOT match, so they fall through to the driver's own parser untouched.
+ */
+const PG_TIMESTAMP_TEXT_RE = /^(\d{4,})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?( BC)?$/;
+/**
+ * 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.
+ */
+function createUtcTimestampParser(fallback) {
+    return (text) => {
+        const m = PG_TIMESTAMP_TEXT_RE.exec(text);
+        if (!m)
+            return fallback(text);
+        const year = m[8] ? -(Number(m[1]) - 1) : Number(m[1]);
+        const ms = m[7] ? Number(m[7].slice(0, 3).padEnd(3, '0')) : 0;
+        const date = new Date(0);
+        date.setUTCFullYear(year, Number(m[2]) - 1, Number(m[3]));
+        date.setUTCHours(Number(m[4]), Number(m[5]), Number(m[6]), ms);
+        return date;
+    };
+}
+/**
+ * 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.
+ */
+function parseUtcTimestampText(text) {
+    return new Date(`${text.replace(' ', 'T')}Z`);
+}
+/**
+ * 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`.
+ */
+function createPgArrayParser(element) {
+    const arrayParser = pg_1.default.types.arrayParser;
+    return (text) => arrayParser.create(text, (entry) => (entry === null || entry === undefined ? null : element(entry))).parse();
+}
+/**
+ * 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.
+ */
+function registerUtcTemporalParsers() {
+    // pg-types declares get/setTypeParser over its own OID enum, which lists the
+    // scalar types only. The array OIDs are just as real, so both calls are
+    // retyped over a plain number rather than the incomplete enum.
+    const getParser = pg_1.default.types.getTypeParser;
+    const setParser = pg_1.default.types.setTypeParser;
+    const parseDate = createUtcDateParser(getParser(1082, 'text'));
+    const parseTimestamp = createUtcTimestampParser(getParser(1114, 'text'));
+    setParser(1114, parseTimestamp);
+    setParser(1082, parseDate);
+    // Array OIDs do not inherit their element parser, so `date[]` / `timestamp[]`
+    // would otherwise keep returning local-zone Dates while the scalar columns
+    // beside them returned UTC ones.
+    setParser(1182, createPgArrayParser(parseDate));
+    setParser(1115, createPgArrayParser(parseTimestamp));
+}
+// ---------------------------------------------------------------------------
 // JSON-wire value coercion (relationLoadStrategy: 'join')
 // ---------------------------------------------------------------------------
 /**
@@ -367,7 +517,7 @@ function parseDbDate(value) {
  *   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)

package/dist/cjs/query/warn-registry.d.ts

@@ -82,4 +82,10 @@ export declare const WARN_NS: {
      * the offenders, not one per column. The namespace name is historical.
      */
     readonly untypedDateColumn: "untypedDateColumn";
+    /**
+     * `planCacheMode` was set on a client given an EXTERNAL pool, where Turbine
+     * runs no connection setup, so the option is a no-op (client.ts constructor).
+     * Keyed on the requested mode.
+     */
+    readonly planCacheModeIgnored: "planCacheModeIgnored";
 };

package/dist/cjs/query/warn-registry.js

@@ -123,4 +123,10 @@ exports.WARN_NS = {
      * the offenders, not one per column. The namespace name is historical.
      */
     untypedDateColumn: 'untypedDateColumn',
+    /**
+     * `planCacheMode` was set on a client given an EXTERNAL pool, where Turbine
+     * runs no connection setup, so the option is a no-op (client.ts constructor).
+     * Keyed on the requested mode.
+     */
+    planCacheModeIgnored: 'planCacheModeIgnored',
 };

package/dist/cjs/sqlite.js

@@ -385,6 +385,7 @@ exports.sqliteDialect = {
     supportsAdvisoryLock: false,
     // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
     supportsLateralJoin: false,
+    supportsPlanCacheMode: false,
     // SQLite explains a compiled query with `EXPLAIN QUERY PLAN` (four columns:
     // id, parent, notused, detail), overriding the inherited Postgres `EXPLAIN`.
     explainQuery: { prefix: 'EXPLAIN QUERY PLAN' },

package/dist/cli/mcp.js

@@ -5,6 +5,7 @@ import pg from 'pg';
 import { findMissingRelationIndexes } from '../index-advisor.js';
 import { addAutoManyToManyRelations, buildRelationsFromForeignKeys, isUnknownTsType, } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
+import { registerUtcTemporalParsers } from '../query/utils.js';
 import { isDateType, pgArrayType, pgTypeToTs, snakeToCamel, } from '../schema.js';
 import { listMigrationFiles } from './migrate.js';
 import { applyPiiTags, loadPiiTags } from './pii-tags.js';
@@ -109,6 +110,11 @@ const TOOLS = [
 export function startMcpServer(options, transport = {}) {
     const input = transport.input ?? process.stdin;
     const output = transport.output ?? process.stdout;
+    // Read zone-less `date` / `timestamp` values as UTC, as TurbineClient does on
+    // a pool it owns. This server builds its own raw pool, so without it a
+    // `date` sampled here is serialized at the CLI process's local midnight while
+    // the application reading the same row through Turbine sees UTC midnight.
+    registerUtcTemporalParsers();
     const ctx = {
         options,
         pool: new pg.Pool({ connectionString: options.url, max: 2, idleTimeoutMillis: 10_000 }),

package/dist/cli/studio.js

@@ -48,7 +48,7 @@ import { introspect } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
 // `ownLookup` is not re-exported from the query barrel, so it is imported from
 // its defining leaf module rather than duplicated here.
-import { ownLookup } from '../query/utils.js';
+import { ownLookup, registerUtcTemporalParsers } from '../query/utils.js';
 import { applyPiiTags, loadPiiTags } from './pii-tags.js';
 import { callerKey, checkRateLimit } from './rate-limit.js';
 import { createDemoContext } from './studio-demo.js';
@@ -84,6 +84,16 @@ export async function startStudio(options) {
         statementTimeout = { sql: 'SELECT 1', params: [] };
     }
     else {
+        // Read zone-less `date` / `timestamp` values as UTC, exactly as
+        // TurbineClient does on a pool it owns. Studio builds a raw pg.Pool and
+        // never constructs a TurbineClient, so without this the viewer renders a
+        // `date` cell at the CLI process's local midnight while the application
+        // reading the same row through Turbine sees UTC midnight: the previous
+        // evening east of UTC. It also matters for `--write`, where the cell the
+        // UI echoes back is what gets stored. The CLI process is Turbine's own, so
+        // there is no foreign pg consumer to disturb, and the parsers are
+        // registered before the first query runs.
+        registerUtcTemporalParsers();
         // pg.Pool satisfies the PgCompatPool contract (same as the external-pool
         // seam in client.ts); the cast keeps one typed pool field for both modes.
         pool = new pg.Pool({

package/dist/client.d.ts

@@ -125,6 +125,11 @@ export interface TurbineDriver {
     /** SQL dialect: placeholders, transaction keywords, session-config, capability flags. */
     readonly dialect: Dialect;
 }
+/**
+ * The values PostgreSQL's `plan_cache_mode` accepts. See
+ * {@link TurbineConfig.planCacheMode}.
+ */
+export type PlanCacheMode = 'auto' | 'force_custom_plan' | 'force_generic_plan';
 export interface TurbineConfig {
     /**
      * An external pg-compatible pool. Use this to plug in serverless drivers
@@ -176,8 +181,11 @@ export interface TurbineConfig {
     warnOnUnlimited?: boolean | Record<string, boolean>;
     /**
      * Interpret Postgres `timestamp` (without time zone) values as UTC, both
-     * at the driver level (OID 1114 type parser, registered only when Turbine
-     * owns the pool) and when coercing nested-relation JSON dates. This is the
+     * at the driver level (type parsers for OIDs 1114 `timestamp`, 1082 `date`,
+     * and their array forms 1115 / 1182, registered only when Turbine owns the
+     * pool) and when coercing nested-relation JSON dates. A `date` column is
+     * zone-less too, so it reads back as UTC midnight rather than the process's
+     * local midnight. This is the
      * Prisma/Rails/Django convention and makes results independent of the
      * server's local time zone. Default: `true`. Set `false` for the legacy
      * local-time interpretation, which also turns off the matching WRITE-side
@@ -186,15 +194,76 @@ export interface TurbineConfig {
      *
      * PER PROCESS, NOT PER CLIENT. The read half is a pg type parser, and
      * `pg.types.setTypeParser` installs one parser per OID for the whole
-     * process. The first Turbine-owned client settles it for every later one, so
-     * constructing a second client with the OPPOSITE value throws a
-     * `ValidationError` rather than handing back a client whose writes and reads
-     * disagree. Give every client in the process the same value, or isolate the
-     * odd one in its own process. Clients on an EXTERNAL pool never register a
-     * parser and never take part in the check: they inherit whatever parser
-     * configuration the caller's driver has.
+     * process. The first client settles it for every later one, so constructing
+     * a second client with the OPPOSITE value throws a `ValidationError` rather
+     * than handing back a client whose writes and reads disagree. Give every
+     * client in the process the same value, or isolate the odd one in its own
+     * process. A client on an EXTERNAL pool never REGISTERS a parser (it inherits
+     * whatever configuration the caller's driver has, so a process containing
+     * only external-pool clients is untouched), but it does take part in the
+     * agreement check: registration is process-global, so once a Turbine-owned
+     * client has installed the parsers an external-pool client reads through them
+     * too, and a disagreeing one would write local `date` literals while reading
+     * UTC.
      */
     utcTimestamps?: boolean;
+    /**
+     * Pin `plan_cache_mode` on every connection this client opens, fixing how the
+     * PostgreSQL backend chooses between a custom plan (re-planned per parameter
+     * set) and a generic plan (planned once, blind to the values).
+     *
+     * Why it exists: Turbine sends NAMED prepared statements by default on a pool
+     * it owns, and PostgreSQL promotes a named statement to a generic plan after
+     * five executions. A generic plan is planned for the AVERAGE parameter, so a
+     * predicate whose selectivity varies wildly per value (the canonical case is a
+     * `tenant_id` / `user_id` equality on a shared table, where one value matches
+     * a handful of rows and another matches most of them) is planned blind to the
+     * value it will actually get, and it never reverts. `'force_custom_plan'`
+     * removes that, at the cost of re-planning each execution.
+     *
+     * Scope, measured rather than assumed: it applies to the statements Turbine
+     * itself promotes. `count()` on such a predicate is promoted after five
+     * executions and is controlled by this option; `findMany` / `findFirst` bind
+     * `LIMIT $n`, and a parameterized limit denies the planner the limit fraction
+     * that makes a skewed plan look cheap, so those are much less exposed. Treat
+     * the option as a targeted remedy for a plan that is measurably worse after
+     * its fifth execution, not a general speed-up.
+     *
+     * Default `undefined`: Turbine issues NOTHING and the backend keeps its own
+     * default (`auto`), byte-identical to not setting the option.
+     *
+     * SESSION-LEVEL, NOT PER QUERY. It is applied as a connection parameter
+     * (`options=-c plan_cache_mode=...`) when the pool opens a connection, so it
+     * is in force for that connection's very first statement and persists for its
+     * whole life: every pooled checkout, `$transaction`, stream and pipeline on
+     * that connection inherits it, and it is NOT reset between checkouts. A
+     * caller's own `SET` / `SET LOCAL` still overrides it for that session or
+     * transaction, exactly as it would over any other session default.
+     *
+     * POSTGRES-ONLY. Engines whose dialect does not report
+     * `supportsPlanCacheMode` throw {@link UnsupportedFeatureError} (E017) at
+     * construction. The capability flag can only speak for the DIALECT, though,
+     * and `plan_cache_mode` is PostgreSQL 12+: a Postgres wire-compatible engine
+     * driven through the default `postgresDialect` (CockroachDB, YugabyteDB, an
+     * older server) has no such setting, and rejects the connection parameter
+     * itself with `unrecognized configuration parameter` at the first checkout
+     * rather than with E017. Leave the option unset on those.
+     *
+     * EXTERNAL POOLS ARE NOT TOUCHED. When the caller supplies `pool`, they own
+     * connection lifecycle, and Turbine has no hook that runs on their
+     * connections without also mutating a pool it does not own. Same rule as the
+     * type parsers above. The option is then a no-op on that pool, with a
+     * dev-mode warning; a serverless/HTTP driver should set the GUC in its own
+     * connection setup. Turbine-OWNED string `replicas` are still Turbine's own
+     * connections and do get it, even next to an external primary, so setting it
+     * in that shape splits the policy between reads and writes.
+     *
+     * BEHIND A CONNECTION POOLER, the GUC travels as a connection-time `options`
+     * startup parameter, which a pooler may refuse to pass through (PgBouncer's
+     * `ignore_startup_parameters`). Set it on the role or server there
+     * (`ALTER ROLE ... SET plan_cache_mode = ...`) instead.
+     */
+    planCacheMode?: PlanCacheMode;
     /**
      * Refuse a nested `connect` / `connectOrCreate` that would re-parent a
      * to-many child already owned by a different parent. Off by default,
@@ -545,21 +614,33 @@ export declare class TurbineClient {
     readonly schema: SchemaMetadata;
     private static int8ParserRegistered;
     /**
-     * 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}.
      */
     private 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.
+     */
+    private static utcTimestampParsersRegistered;
     private readonly logging;
     /** Active SQL dialect, owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     private readonly dialect;
+    /** Validated `plan_cache_mode` to pin on every owned connection, or undefined to issue nothing. */
+    private readonly planCacheMode;
     private readonly tableCache;
     private readonly middlewares;
     private readonly queryListeners;
@@ -592,19 +673,89 @@ export declare class TurbineClient {
     private primaryView?;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
-     * 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.
+     */
+    private static resolvePlanCacheMode;
+    /**
+     * 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 = ...`).
+     */
+    private static withPlanCacheMode;
+    /**
+     * `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.
+     */
+    private static mergeConnectionStringOptions;
+    /**
+     * 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
@@ -612,9 +763,15 @@ export declare 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.
      */
     private static assertUtcTimestampsAgree;
     /**