turbine-orm 0.53.0 → 0.54.0

package/README.md

@@ -429,7 +429,7 @@ const db = turbine({
 });
 ```
 
-> **`utcTimestamps` is a process-wide decision, not a per-client one.** The two halves settle differently. The WRITE half is per client: a `Date` bound to a zone-less `date` / `timestamp` column is rewritten to a UTC literal unless that client opted out. The READ half is a pg type parser on OID 1114, and `pg.types.setTypeParser` installs one parser per OID for the whole pg module, shared by every pool, every raw query, and any other library on the same `pg`. The first Turbine-owned client in the process settles it for all the rest. Constructing a second Turbine-owned client with the **opposite** value therefore throws `ValidationError` (`TURBINE_E003`) at construction, rather than handing back a client that writes UTC and reads local (or the reverse) and so does not round-trip its own values. The message names both values and the two ways out: give every client in the process the same `utcTimestamps`, or run the odd one out in its own process. Clients built on an external pool (`pool: ...`, `turbineHttp()`) never register a parser, settle nothing, and are exempt from the check, they inherit whatever parser configuration the caller set up.
+> **`utcTimestamps` is a process-wide decision, not a per-client one.** The two halves settle differently. The WRITE half is per client: a `Date` bound to a zone-less `date` / `timestamp` column is rewritten to a UTC literal unless that client opted out. The READ half is a set of pg type parsers on OIDs 1114 (`timestamp`), 1082 (`date`) and their array forms 1115 / 1182, and `pg.types.setTypeParser` installs one parser per OID for the whole pg module, shared by every pool, every raw query, and any other library on the same `pg`. The first client in the process settles it for all the rest. Constructing a second client with the **opposite** value therefore throws `ValidationError` (`TURBINE_E003`) at construction, rather than handing back a client that writes UTC and reads local (or the reverse) and so does not round-trip its own values. The message names both values and the two ways out: give every client in the process the same `utcTimestamps`, or run the odd one out in its own process. Clients built on an external pool (`pool: ...`, `turbineHttp()`) never REGISTER a parser and settle nothing on their own, so a process holding only those keeps whatever parser configuration the caller set up. They are not exempt from the check, though: 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.
 
 > **Upgrading with `utcTimestamps: false`.** If you already set `false`, this release changes the **stored text** of your writes: the write path now honors the flag where it previously ignored it, so zone-less columns receive local-calendar literals instead of UTC ones. Rows written before the upgrade and rows written after carry two conventions in the same column until you backfill.
 
@@ -446,11 +446,16 @@ const db = turbine({
   preparedStatements: true,   // see the warning below
   sqlCache: true,             // SQL template cache (default true)
   sqlCacheSize: 1000,         // distinct query SHAPES retained per table (default 1000)
+  // Postgres only, opt-in, unset by default (Turbine then sends nothing).
+  // Pins how the backend picks between a custom and a generic plan.
+  // planCacheMode: 'force_custom_plan',
 });
 ```
 
 Where a pg-style alias exists (`max`, `idleTimeoutMillis`, `connectionTimeoutMillis`), the explicit Turbine field wins when both are set.
 
+> **`planCacheMode` (Postgres only, opt-in).** PostgreSQL promotes a **named** prepared statement to a generic plan on its sixth execution, and a generic plan is costed blind to the bound values. On a predicate whose selectivity swings per value (a `tenant_id` equality on a shared table, where one value matches a handful of rows and another matches most of them), the statement can be locked onto a plan chosen for the average value, and it never reverts. `planCacheMode: 'auto' | 'force_custom_plan' | 'force_generic_plan'` pins the backend's choice; `'force_custom_plan'` re-plans every execution and removes the cliff. It is applied as a connection parameter (`options=-c plan_cache_mode=...`) when Turbine opens a connection, so it is in force for that connection's first statement and for every checkout, `$transaction`, stream and pipeline on it, and it cannot race your first query. Leave it unset (the default) and Turbine sends nothing at all. Reach for it when you have measured a statement getting slower after its fifth execution: `count()` on a skewed predicate is the shape that promotes through Turbine, while `findMany` / `findFirst` bind `LIMIT $n` and are much less exposed. Three scope limits: it does nothing on an **external pool** (Turbine never opens those connections, so set the GUC in the driver's own setup; Turbine-owned string `replicas` on that same client DO get it); a Postgres wire-compatible engine without the setting (CockroachDB, YugabyteDB, pre-12 PostgreSQL) refuses the connection parameter itself; and a **connection pooler** may filter startup parameters (PgBouncer's `ignore_startup_parameters`), where `ALTER ROLE ... SET plan_cache_mode = ...` is the way in. Any value outside the three throws `ValidationError` at construction, and a non-Postgres engine throws `UnsupportedFeatureError` (`TURBINE_E017`).
+
 > **`preparedStatements` and connection poolers.** With prepared statements on, Turbine submits queries as `{ name, text, values }` so Postgres caches the parse and plan **per backend connection**. That is a real win against a database you connect to directly, and a hazard behind a transaction-pooling proxy (PgBouncer in `transaction` mode, Supabase's pooler port, some serverless poolers): the named statement is prepared on one backend and your next query may land on another, which fails with `prepared statement "..." does not exist`. Turbine defaults it to `true` only for pools it creates itself and `false` for external pools passed via `pool` / `turbineHttp()`, because serverless drivers are the common case there. If you are pointing a Turbine-owned pool at a transaction pooler, set `preparedStatements: false`. The environment variable `TURBINE_DISABLE_PREPARED=1` turns it off globally without a code change.
 
 ### Client escape hatches
@@ -1092,7 +1097,7 @@ Turbine maps Postgres types to TypeScript:
 | `int8` / `bigint` | `number` | Values > `Number.MAX_SAFE_INTEGER` (2^53 - 1) are returned as `string` at runtime to avoid precision loss. This affects < 0.01% of use cases (auto-increment IDs, counts, etc. are all safe). |
 | `numeric`, `money` | `string` | Arbitrary precision, kept as string to avoid JS float issues |
 | `text`, `varchar`, `uuid`, `citext` | `string` | |
-| `timestamptz`, `timestamp`, `date` | `Date` | `timestamp` (without time zone) is parsed as UTC by default (Prisma/Rails/Django convention), so the same row yields the same instant in every region. Opt out with `utcTimestamps: false`. Since v0.52 the flag also reaches the WRITE side on Postgres: it governs the `Date` values that `create` / `update` / `upsert` and `where` clauses bind to zone-less `date` / `timestamp` columns. Before v0.52 it reached the read path only, so a client that had set `false` was still binding UTC, and those statements (and the text they store) change on upgrade. The two halves settle at different scopes: the write half is per client, the read half is a process-global pg type parser, so two Turbine-owned clients in one process must agree or construction throws `ValidationError`. See [Relation loading and wire encoding](#relation-loading-and-wire-encoding). |
+| `timestamptz`, `timestamp`, `date` | `Date` | `timestamp` (without time zone) **and `date`** are parsed as UTC by default (Prisma/Rails/Django convention), so the same row yields the same instant in every region. Opt out with `utcTimestamps: false`. Since v0.52 the flag also reaches the WRITE side on Postgres: it governs the `Date` values that `create` / `update` / `upsert` and `where` clauses bind to zone-less `date` / `timestamp` columns. Before v0.52 it reached the read path only, so a client that had set `false` was still binding UTC, and those statements (and the text they store) change on upgrade. The two halves settle at different scopes: the write half is per client, the read half is a process-global pg type parser, so every client in one process must agree or construction throws `ValidationError`. Since v0.54 `date` reads at UTC midnight rather than the process's local midnight (its array form too), which moves the **epoch value** of a `date` by your process's UTC offset even though the calendar day it denotes is unchanged: format with `toISOString().slice(0, 10)`, not with local-component helpers like `toLocaleDateString()`. See [Relation loading and wire encoding](#relation-loading-and-wire-encoding). |
 | `boolean` | `boolean` | |
 | `json`, `jsonb` | `unknown` | |
 | `bytea` | `Buffer` | |

package/dist/cjs/cli/mcp.js

@@ -13,6 +13,7 @@ const pg_1 = __importDefault(require("pg"));
 const index_advisor_js_1 = require("../index-advisor.js");
 const introspect_js_1 = require("../introspect.js");
 const index_js_1 = require("../query/index.js");
+const utils_js_1 = require("../query/utils.js");
 const schema_js_1 = require("../schema.js");
 const migrate_js_1 = require("./migrate.js");
 const pii_tags_js_1 = require("./pii-tags.js");
@@ -117,6 +118,11 @@ const TOOLS = [
 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.
+    (0, utils_js_1.registerUtcTemporalParsers)();
     const ctx = {
         options,
         pool: new pg_1.default.Pool({ connectionString: options.url, max: 2, idleTimeoutMillis: 10_000 }),

package/dist/cjs/cli/studio.js

@@ -103,6 +103,16 @@ 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.
+        (0, utils_js_1.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_1.default.Pool({

package/dist/cjs/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;
     /**