turbine-orm 0.27.0 → 0.28.0

package/dist/cjs/cli/migrate.js

@@ -25,7 +25,10 @@ exports.parseMigrationContent = parseMigrationContent;
 exports.parseMigrationSQL = parseMigrationSQL;
 exports.createMigration = createMigration;
 exports.deriveLockId = deriveLockId;
+exports.planMigrationDeploy = planMigrationDeploy;
+exports.inspectMigrationDeploy = inspectMigrationDeploy;
 exports.migrateUp = migrateUp;
+exports.migrateDeploy = migrateDeploy;
 exports.migrateDown = migrateDown;
 exports.migrateStatus = migrateStatus;
 const node_crypto_1 = require("node:crypto");
@@ -297,6 +300,85 @@ async function validateChecksums(client, migrationsDir, dialect = dialect_js_1.p
     }
     return mismatches;
 }
+function formatChecksumMismatchError(mismatches) {
+    const modified = mismatches.filter((m) => m.type === 'modified');
+    const missing = mismatches.filter((m) => m.type === 'missing');
+    const lines = [
+        '[turbine] Migration drift detected — refusing to apply pending migrations.',
+        '',
+        'Applied migrations should be immutable. The following files no longer match their applied state:',
+        '',
+    ];
+    for (const m of modified) {
+        lines.push(`  - ${m.name}.sql  (modified on disk)`);
+    }
+    for (const m of missing) {
+        lines.push(`  - ${m.name}.sql  (deleted from disk)`);
+    }
+    lines.push('');
+    lines.push('Fix one of these:');
+    lines.push('  1. Restore the file(s) to their original content, OR');
+    lines.push('  2. Roll back the affected migrations with `npx turbine migrate down`, OR');
+    lines.push('  3. Pass `--allow-drift` to bypass this check (advanced — make sure you know what you are doing).');
+    return lines.join('\n');
+}
+/**
+ * Build a deploy plan from local migration files and applied migration rows.
+ * This is pure file-system planning; callers with a database connection should
+ * use `inspectMigrationDeploy()` to preserve legacy checksum upgrades.
+ */
+function planMigrationDeploy(migrationsDir, applied) {
+    const allFiles = listMigrationFiles(migrationsDir);
+    const fileMap = new Map(allFiles.map((f) => [f.name, f]));
+    const appliedNames = new Set(applied.map((m) => m.name));
+    const mismatches = [];
+    for (const migration of applied) {
+        const file = fileMap.get(migration.name);
+        if (!file) {
+            mismatches.push({
+                name: migration.name,
+                expected: migration.checksum,
+                actual: '',
+                type: 'missing',
+            });
+            continue;
+        }
+        const currentHash = checksum((0, node_fs_1.readFileSync)(file.path, 'utf-8'));
+        if (currentHash !== migration.checksum && !isLegacyChecksum(migration.checksum)) {
+            mismatches.push({
+                name: migration.name,
+                expected: migration.checksum,
+                actual: currentHash,
+                type: 'modified',
+            });
+        }
+    }
+    return {
+        pending: allFiles.filter((f) => !appliedNames.has(f.name)),
+        mismatches,
+    };
+}
+/**
+ * Inspect deploy status without applying migrations.
+ */
+async function inspectMigrationDeploy(connectionString, migrationsDir, options) {
+    const client = new pg_1.default.Client({ connectionString });
+    await client.connect();
+    const dialect = options?.dialect ?? dialect_js_1.postgresDialect;
+    try {
+        await ensureTrackingTable(client, dialect);
+        const mismatches = await validateChecksums(client, migrationsDir, dialect);
+        const applied = await getAppliedMigrations(client, dialect);
+        const appliedNames = new Set(applied.map((m) => m.name));
+        return {
+            pending: listMigrationFiles(migrationsDir).filter((f) => !appliedNames.has(f.name)),
+            mismatches,
+        };
+    }
+    finally {
+        await client.end();
+    }
+}
 /**
  * Apply all pending migrations (UP).
  *
@@ -340,26 +422,7 @@ async function migrateUp(connectionString, migrationsDir, options) {
             if (!allowDrift) {
                 const mismatches = await validateChecksums(client, migrationsDir, dialect);
                 if (mismatches.length > 0) {
-                    const modified = mismatches.filter((m) => m.type === 'modified');
-                    const missing = mismatches.filter((m) => m.type === 'missing');
-                    const lines = [
-                        '[turbine] Migration drift detected — refusing to apply pending migrations.',
-                        '',
-                        'Applied migrations should be immutable. The following files no longer match their applied state:',
-                        '',
-                    ];
-                    for (const m of modified) {
-                        lines.push(`  - ${m.name}.sql  (modified on disk)`);
-                    }
-                    for (const m of missing) {
-                        lines.push(`  - ${m.name}.sql  (deleted from disk)`);
-                    }
-                    lines.push('');
-                    lines.push('Fix one of these:');
-                    lines.push('  1. Restore the file(s) to their original content, OR');
-                    lines.push('  2. Roll back the affected migrations with `npx turbine migrate down`, OR');
-                    lines.push('  3. Pass `--allow-drift` to bypass this check (advanced — make sure you know what you are doing).');
-                    throw new errors_js_1.MigrationError(lines.join('\n'));
+                    throw new errors_js_1.MigrationError(formatChecksumMismatchError(mismatches));
                 }
             }
             const applied = await getAppliedMigrations(client, dialect);
@@ -433,6 +496,18 @@ async function migrateUp(connectionString, migrationsDir, options) {
         await client.end();
     }
 }
+/**
+ * Production migration apply. This intentionally applies files as written and
+ * never performs interactive destructive confirmation.
+ */
+async function migrateDeploy(connectionString, migrationsDir, options) {
+    return migrateUp(connectionString, migrationsDir, {
+        allowDrift: false,
+        allowDestructive: true,
+        adapter: options?.adapter,
+        dialect: options?.dialect,
+    });
+}
 /**
  * Rollback the last N migrations (DOWN).
  *

package/dist/cjs/cli/studio.js

@@ -7,10 +7,11 @@
  * raw-SQL input surface — the Query tab builds `findMany` args that are
  * validated against introspected metadata and compiled by QueryInterface
  * (`/api/builder`). Pure Node (built-in `http` module), no runtime
- * dependencies beyond `pg`, bound to 127.0.0.1 only.
+ * dependencies beyond `pg`. CLI defaults to 127.0.0.1 and refuses non-loopback
+ * hosts unless `npx turbine studio --allow-remote` is set.
  *
  * Security model:
- *   • Bind 127.0.0.1 only (never 0.0.0.0 — no LAN exposure)
+ *   • Loopback by default; CLI refuses non-loopback without --allow-remote
  *   • Random auth token generated per process, required in Cookie header
  *   • No SQL input surface at all — every identifier in a builder request is
  *     validated against the introspected schema; all values are $N params

package/dist/cjs/client.js

@@ -75,6 +75,29 @@ const ISOLATION_LEVELS = {
  * rejecting loudly before it reaches the database.
  */
 const GUC_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+/**
+ * The read-only `QueryInterface` operations that a read-replica setup may route
+ * to a replica pool. Every other method (all writes, plus internals) stays on
+ * the primary. Kept as a Set so the routing proxy's `get` trap is O(1).
+ */
+const READ_OPERATIONS = new Set([
+    'findMany',
+    'findFirst',
+    'findUnique',
+    'findFirstOrThrow',
+    'findUniqueOrThrow',
+    'count',
+    'aggregate',
+    'groupBy',
+    'findManyStream',
+]);
+/**
+ * Internal marker on the config object that tells the `TurbineClient`
+ * constructor to build a lightweight "primary-only" view sharing an existing
+ * client's primary pool, dialect, query options, and middleware — instead of
+ * creating a fresh pool. Produced solely by `$primary()`; never public.
+ */
+const PRIMARY_VIEW = Symbol('turbine.primaryView');
 // ---------------------------------------------------------------------------
 // TransactionClient — provides typed table accessors within a transaction
 // ---------------------------------------------------------------------------
@@ -218,7 +241,55 @@ class TurbineClient {
     ownsPool = true;
     /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
     activeSubscriptions = new Set();
+    /**
+     * Read-replica pools in round-robin order. Empty when no replicas are
+     * configured, in which case `table()` takes the original single-pool path.
+     */
+    replicaPools;
+    /**
+     * The subset of {@link replicaPools} that Turbine created from connection
+     * strings and must close on `disconnect()`. External replica pools are not
+     * listed here (caller owns their lifecycle).
+     */
+    ownedReplicaPools;
+    /** Rotating index for round-robin replica selection (advances per read op). */
+    replicaCursor = 0;
+    /** Per-replica `table → QueryInterface` caches, indexed like {@link replicaPools}. */
+    replicaTableCaches;
+    /** Cache of per-table routing proxies (only used when replicas are present). */
+    routingProxyCache = new Map();
+    /** Lazily-built, cached primary-only view returned by {@link $primary}. */
+    primaryView;
     constructor(config = {}, schema) {
+        // Primary-only view: $primary() constructs this to share the parent's
+        // primary pool + derived state instead of creating a fresh pool. It owns
+        // no pool and no replicas, so every operation (reads included) runs on the
+        // primary and disconnect() is a no-op on the shared pool.
+        const seed = config[PRIMARY_VIEW];
+        if (seed) {
+            const parent = seed.parent;
+            this.schema = schema;
+            this.logging = parent.logging;
+            this.dialect = parent.dialect;
+            this.errorMessagesSafe = parent.errorMessagesSafe;
+            this.queryOptions = parent.queryOptions;
+            this.middlewares = parent.middlewares; // shared reference: $use on parent flows through
+            this.pool = parent.pool;
+            this.ownsPool = false;
+            this.replicaPools = [];
+            this.ownedReplicaPools = [];
+            this.replicaTableCaches = [];
+            for (const tableName of Object.keys(schema.tables)) {
+                const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+                if (!(camelName in this)) {
+                    Object.defineProperty(this, camelName, {
+                        get: () => this.table(tableName),
+                        enumerable: true,
+                    });
+                }
+            }
+            return;
+        }
         // Constructing without schema metadata previously crashed deep in the
         // constructor with an opaque "Cannot read properties of undefined
         // (reading 'tables')". Fail fast with an actionable message instead.
@@ -242,11 +313,16 @@ class TurbineClient {
          * of returning a string is correct and matches the generated TypeScript type
          * (numeric → string). Users who want number can cast explicitly in SQL.
          */
-        // Only register the int8 parser when we own the pg driver. External
-        // pools (Neon HTTP, Vercel Postgres) may ship their own pg-types fork
-        // and rely on their own parser configuration — don't mutate global state
-        // we don't own.
-        if (!config.pool && !TurbineClient.int8ParserRegistered) {
+        // Only register the int8 parser when the PRIMARY pool is Turbine-owned.
+        // External pools (Neon HTTP, Vercel Postgres) may ship their own pg-types
+        // fork and rely on their own parser configuration — registration is
+        // process-global, so flipping it because a string replica exists alongside
+        // an external primary would silently change the external primary's parsing
+        // too. String replicas configured next to an external primary therefore
+        // inherit the caller's parser configuration (documented). Registration is
+        // constructor-gated by the static flags, so it happens at most once.
+        const ownsAnyPool = !config.pool;
+        if (ownsAnyPool && !TurbineClient.int8ParserRegistered) {
             pg_1.default.types.setTypeParser(20, (val) => {
                 const n = Number(val);
                 return Number.isSafeInteger(n) ? n : val;
@@ -259,7 +335,7 @@ class TurbineClient {
         // ORM convention (Prisma, Rails, Django) — and the only interpretation
         // that round-trips what Postgres stores — is UTC. Same ownership rule as
         // the int8 parser: never mutate parser state on external pools.
-        if (!config.pool && config.utcTimestamps !== false && !TurbineClient.utcTimestampParserRegistered) {
+        if (ownsAnyPool && config.utcTimestamps !== false && !TurbineClient.utcTimestampParserRegistered) {
             pg_1.default.types.setTypeParser(1114, (val) => new Date(`${val.replace(' ', 'T')}Z`));
             TurbineClient.utcTimestampParserRegistered = true;
         }
@@ -275,6 +351,7 @@ class TurbineClient {
             utcTimestamps: config.utcTimestamps,
             relationLoadStrategy: config.relationLoadStrategy,
             jsonEncoding: config.jsonEncoding,
+            globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
             dialect: config.dialect,
@@ -339,6 +416,34 @@ class TurbineClient {
                 console.log(`[turbine] Pool created — max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
             }
         }
+        // Build read-replica pools (if any). String entries become owned pg.Pools
+        // sharing the primary's tuning knobs; PgCompatPool entries are external and
+        // used as-is. Replica selection is round-robin in this array order.
+        this.replicaPools = [];
+        this.ownedReplicaPools = [];
+        for (const replica of config.replicas ?? []) {
+            if (typeof replica === 'string') {
+                const replicaPool = new pg_1.default.Pool({
+                    connectionString: replica,
+                    max: config.poolSize ?? 10,
+                    idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
+                    connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
+                    ...(config.ssl !== undefined ? { ssl: config.ssl } : {}),
+                });
+                replicaPool.on('error', (err) => {
+                    console.error('[turbine] Unexpected replica pool error:', err.message);
+                });
+                this.replicaPools.push(replicaPool);
+                this.ownedReplicaPools.push(replicaPool);
+            }
+            else {
+                this.replicaPools.push(replica);
+            }
+        }
+        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)`);
+        }
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
             const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
@@ -390,8 +495,14 @@ class TurbineClient {
      */
     $use(middleware) {
         this.middlewares.push(middleware);
-        // Clear table cache so new QueryInterfaces pick up the middleware
+        // Clear table caches so new QueryInterfaces pick up the middleware. Covers
+        // the primary cache plus, when replicas are configured, the routing proxies
+        // and per-replica caches. The primary-view (if built) shares the middleware
+        // array by reference, so its QueryInterfaces observe the new middleware too.
         this.tableCache.clear();
+        this.routingProxyCache.clear();
+        for (const cache of this.replicaTableCaches)
+            cache.clear();
     }
     // -------------------------------------------------------------------------
     // Event emitter — subscribe to query lifecycle events
@@ -430,17 +541,110 @@ class TurbineClient {
     /**
      * Get a QueryInterface for a table.
      * Results are cached — calling `table('users')` twice returns the same instance.
+     *
+     * When read replicas are configured, this returns a thin routing proxy: the
+     * read-only operations in {@link READ_OPERATIONS} are dispatched to a
+     * round-robin replica-bound QueryInterface (so an entire read — base rows and
+     * any batched sub-queries — runs against a single consistent replica), while
+     * writes and every other member fall through to the primary-bound instance.
+     * With no replicas the original single-pool instance is returned directly.
      */
     table(name) {
+        if (this.replicaPools.length === 0) {
+            return this.primaryTableQI(name);
+        }
+        let proxy = this.routingProxyCache.get(name);
+        if (!proxy) {
+            proxy = this.createRoutingAccessor(name);
+            this.routingProxyCache.set(name, proxy);
+        }
+        return proxy;
+    }
+    /** Get (and cache) the primary-pool-bound QueryInterface for a table. */
+    primaryTableQI(name) {
         let qi = this.tableCache.get(name);
         if (!qi) {
-            qi = this.queryOptions?.queryInterfaceFactory
-                ? this.queryOptions.queryInterfaceFactory(this.pool, name, this.schema, this.middlewares, this.queryOptions)
-                : new index_js_1.QueryInterface(this.pool, name, this.schema, this.middlewares, this.queryOptions);
+            qi = this.buildTableQI(this.pool, name);
             this.tableCache.set(name, qi);
         }
         return qi;
     }
+    /**
+     * Advance the round-robin cursor and return the QueryInterface bound to the
+     * selected replica pool for `name` (cached per replica).
+     */
+    nextReplicaTableQI(name) {
+        const index = this.replicaCursor % this.replicaPools.length;
+        // Reset before overflow so the cursor never grows unbounded.
+        this.replicaCursor = this.replicaCursor + 1 >= Number.MAX_SAFE_INTEGER ? 0 : this.replicaCursor + 1;
+        // index is always in-bounds (`% length`); the pools/cache entries exist.
+        const cache = this.replicaTableCaches[index];
+        const pool = this.replicaPools[index];
+        let qi = cache.get(name);
+        if (!qi) {
+            qi = this.buildTableQI(pool, name);
+            cache.set(name, qi);
+        }
+        return qi;
+    }
+    /** Construct a QueryInterface bound to `pool` (honoring any injected factory). */
+    buildTableQI(pool, name) {
+        const asPgPool = pool;
+        return this.queryOptions?.queryInterfaceFactory
+            ? this.queryOptions.queryInterfaceFactory(asPgPool, name, this.schema, this.middlewares, this.queryOptions)
+            : new index_js_1.QueryInterface(asPgPool, name, this.schema, this.middlewares, this.queryOptions);
+    }
+    /**
+     * Build the read/write routing proxy for a table. The proxy targets the
+     * primary QueryInterface (so writes, `build*`, and every non-read member work
+     * unchanged); read operations are intercepted and dispatched to a replica.
+     */
+    createRoutingAccessor(name) {
+        const primaryQI = this.primaryTableQI(name);
+        const client = this;
+        return new Proxy(primaryQI, {
+            get(target, prop, receiver) {
+                if (typeof prop === 'string' && READ_OPERATIONS.has(prop)) {
+                    // Pick the replica at CALL time so round-robin advances per operation.
+                    return (...args) => {
+                        const replicaQI = client.nextReplicaTableQI(name);
+                        const method = replicaQI[prop];
+                        if (typeof method !== 'function') {
+                            return Reflect.get(target, prop, receiver);
+                        }
+                        return method.apply(replicaQI, args);
+                    };
+                }
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+    }
+    /**
+     * Return a view of this client that pins EVERY operation — reads included —
+     * to the primary pool, bypassing replica routing. Use it to read your own
+     * write without replication lag, or for any read that must see the latest
+     * committed data.
+     *
+     * The view shares the primary pool, schema, dialect, query options, and
+     * middleware; it owns nothing, so its `disconnect()` is a no-op. When no
+     * replicas are configured this simply returns the client itself (already
+     * primary-only). The view is cached — repeated calls return the same instance.
+     *
+     * @example
+     * ```ts
+     * await db.users.create({ data: { email: 'a@b.com' } });
+     * // Read-after-write: guaranteed to see the row just inserted.
+     * const user = await db.$primary().users.findFirst({ where: { email: 'a@b.com' } });
+     * ```
+     */
+    $primary() {
+        if (this.replicaPools.length === 0)
+            return this;
+        if (!this.primaryView) {
+            this.primaryView = new TurbineClient({ [PRIMARY_VIEW]: { parent: this } }, this.schema);
+        }
+        return this.primaryView;
+    }
     // -------------------------------------------------------------------------
     // Pipeline — batch multiple queries into one round-trip
     // -------------------------------------------------------------------------
@@ -581,29 +785,13 @@ class TurbineClient {
             client.release();
         }
     }
-    // -------------------------------------------------------------------------
-    // $transaction — Prisma-style typed transaction API
-    // -------------------------------------------------------------------------
-    /**
-     * Execute a function within a database transaction with full typed table accessors.
-     *
-     * The `tx` object provides the same table accessor API as the main client.
-     * Supports nested transactions via SAVEPOINTs, timeouts, and isolation levels.
-     *
-     * @example
-     * ```ts
-     * await db.$transaction(async (tx) => {
-     *   const user = await tx.users.create({ data: { email: 'a@b.com' } });
-     *   await tx.posts.create({ data: { userId: user.id, title: 'Hello' } });
-     * });
-     *
-     * // With options:
-     * await db.$transaction(async (tx) => {
-     *   // ...
-     * }, { timeout: 5000, isolationLevel: 'Serializable' });
-     * ```
-     */
-    async $transaction(fn, options) {
+    async $transaction(fnOrQueries, options) {
+        // Batch overload: an array of DeferredQuery objects runs atomically inside
+        // one BEGIN…COMMIT, reusing the raw transaction machinery below.
+        if (Array.isArray(fnOrQueries)) {
+            return this.transactionBatch(fnOrQueries);
+        }
+        const fn = fnOrQueries;
         const client = await this.pool.connect();
         const timeout = options?.timeout;
         /**
@@ -719,6 +907,38 @@ class TurbineClient {
             releaseOnce();
         }
     }
+    /**
+     * Execute a batch of {@link DeferredQuery} objects atomically inside one
+     * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
+     * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
+     * queries run sequentially on the single transaction connection and each
+     * result is passed through its query's `transform`.
+     */
+    async transactionBatch(queries) {
+        if (queries.length === 0) {
+            return [];
+        }
+        return this.transaction(async (client) => {
+            const results = [];
+            for (const dq of queries) {
+                let raw;
+                try {
+                    // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL)
+                    // attach a reselect plan that runs the write plus a follow-up SELECT;
+                    // running dq.sql alone would transform a row-less write result.
+                    raw =
+                        this.dialect.resultStrategy === 'reselect' && dq.reselect
+                            ? await dq.reselect((sql, params) => client.query(sql, params))
+                            : await client.query(dq.sql, dq.params);
+                }
+                catch (err) {
+                    throw (0, errors_js_1.wrapPgError)(err);
+                }
+                results.push(dq.transform(raw));
+            }
+            return results;
+        });
+    }
     /**
      * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
      * runs `fn` inside a transaction with the given session GUCs applied via
@@ -875,9 +1095,22 @@ class TurbineClient {
             }
             this.activeSubscriptions.clear();
         }
+        // Close owned (string-configured) replica pools regardless of whether the
+        // primary is owned — external replica pools are left untouched (caller owns
+        // their lifecycle), same contract as an external primary.
+        for (const replicaPool of this.ownedReplicaPools) {
+            try {
+                await replicaPool.end();
+            }
+            catch (err) {
+                if (this.logging) {
+                    console.error('[turbine] Error closing replica pool:', err.message);
+                }
+            }
+        }
         if (!this.ownsPool) {
             if (this.logging) {
-                console.log('[turbine] disconnect() skipped — external pool is not owned by Turbine');
+                console.log('[turbine] disconnect() skipped — external primary pool is not owned by Turbine');
             }
             return;
         }

package/dist/cjs/dialect.js

@@ -48,6 +48,7 @@ exports.postgresDialect = {
     name: 'postgresql',
     resultStrategy: 'returning',
     supportsReturning: true,
+    supportsUpsertUpdateWhere: true,
     supportsILike: true,
     jsonPathSupport: 'native',
     emptyJsonArrayLiteral: "'[]'::json",
@@ -121,6 +122,7 @@ exports.postgresDialect = {
     buildUpsertStatement(input) {
         return (`INSERT INTO ${input.table} (${input.insertColumns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})` +
             ` ON CONFLICT (${input.conflictColumns.join(', ')}) DO UPDATE SET ${input.updateSetClauses.join(', ')}` +
+            (input.updateWhere ? ` WHERE ${input.updateWhere}` : '') +
             this.buildReturningClause(input.returning));
     },
     buildInsensitiveLike(column, paramRef) {