turbine-orm 0.27.0 → 0.28.0

package/dist/cli/migrate.d.ts

@@ -97,6 +97,29 @@ export declare function createMigration(migrationsDir: string, name: string, aut
  * without contending on a single hardcoded lock ID.
  */
 export declare function deriveLockId(databaseName: string): number;
+export interface ChecksumMismatch {
+    name: string;
+    expected: string;
+    actual: string;
+    /** 'modified' if file changed, 'missing' if file deleted */
+    type: 'modified' | 'missing';
+}
+export interface MigrationDeployPlan {
+    pending: MigrationFile[];
+    mismatches: ChecksumMismatch[];
+}
+/**
+ * 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.
+ */
+export declare function planMigrationDeploy(migrationsDir: string, applied: AppliedMigration[]): MigrationDeployPlan;
+/**
+ * Inspect deploy status without applying migrations.
+ */
+export declare function inspectMigrationDeploy(connectionString: string, migrationsDir: string, options?: {
+    dialect?: Dialect;
+}): Promise<MigrationDeployPlan>;
 /**
  * Apply all pending migrations (UP).
  *
@@ -126,6 +149,20 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
         error: string;
     }>;
 }>;
+/**
+ * Production migration apply. This intentionally applies files as written and
+ * never performs interactive destructive confirmation.
+ */
+export declare function migrateDeploy(connectionString: string, migrationsDir: string, options?: {
+    adapter?: DatabaseAdapter;
+    dialect?: Dialect;
+}): Promise<{
+    applied: MigrationFile[];
+    errors: Array<{
+        file: MigrationFile;
+        error: string;
+    }>;
+}>;
 /**
  * Rollback the last N migrations (DOWN).
  *

package/dist/cli/migrate.js

@@ -280,6 +280,85 @@ async function validateChecksums(client, migrationsDir, dialect = postgresDialec
     }
     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.
+ */
+export 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(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.
+ */
+export async function inspectMigrationDeploy(connectionString, migrationsDir, options) {
+    const client = new pg.Client({ connectionString });
+    await client.connect();
+    const dialect = options?.dialect ?? 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).
  *
@@ -323,26 +402,7 @@ export 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 MigrationError(lines.join('\n'));
+                    throw new MigrationError(formatChecksumMismatchError(mismatches));
                 }
             }
             const applied = await getAppliedMigrations(client, dialect);
@@ -416,6 +476,18 @@ export async function migrateUp(connectionString, migrationsDir, options) {
         await client.end();
     }
 }
+/**
+ * Production migration apply. This intentionally applies files as written and
+ * never performs interactive destructive confirmation.
+ */
+export 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/cli/studio.d.ts

@@ -6,10 +6,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/cli/studio.js

@@ -6,10 +6,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/client.d.ts

@@ -26,7 +26,7 @@ import { type Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
-import { type DeferredQuery, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy } from './query/index.js';
+import { type DeferredQuery, type GlobalFilters, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy } from './query/index.js';
 import { type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
 import { TypedSqlQuery } from './typed-sql.js';
@@ -211,6 +211,54 @@ export interface TurbineConfig {
     sqlCache?: boolean;
     /** SQL dialect implementation. Defaults to PostgreSQL. Internal Phase-1 seam for dialect packages. */
     dialect?: Dialect;
+    /**
+     * Read replicas. When set, read-only operations issued outside a transaction
+     * (`findMany`, `findFirst`, `findUnique`, `*OrThrow`, `count`, `aggregate`,
+     * `groupBy`, `findManyStream`) are round-robin load-balanced across these
+     * pools; the primary handles them along with every write. ALL writes,
+     * `$transaction` bodies, `pipeline`, `raw`/`sql`, `$listen`/`$notify`, and
+     * observability flushes always use the primary.
+     *
+     *   - `string` entries are connection strings — Turbine constructs an owned
+     *     `pg.Pool` for each (same pool-tuning knobs as the primary, and the same
+     *     one-time, constructor-gated type-parser registration). `disconnect()`
+     *     closes them.
+     *   - `PgCompatPool` entries are external pools (Neon, Vercel, a shared
+     *     `pg.Pool`) — Turbine registers no type parsers on them and never ends
+     *     them; the caller owns their lifecycle.
+     *
+     * Use `client.$primary()` to get a view of the client that pins every
+     * operation (reads included) to the primary — e.g. to read your own write
+     * without replication lag. Omitting `replicas` (or passing `[]`) leaves the
+     * default single-pool path completely unchanged.
+     */
+    replicas?: readonly (string | PgCompatPool)[];
+    /**
+     * Automatic WHERE filters applied to every query, keyed by table accessor
+     * (`db[name]`). Each value is AND-merged into the compiled WHERE of every
+     * read and mutation on that table — and into every relation subquery that
+     * targets it — implementing soft-delete and multi-tenancy without repeating
+     * the predicate at each call site.
+     *
+     *   - A `WhereClause` value is a static filter (e.g. `{ deletedAt: null }`).
+     *   - A `() => WhereClause` value is evaluated at query-build time, so a
+     *     closure over per-request state (the current tenant id) yields a
+     *     request-scoped filter.
+     *
+     * `create`/`createMany` are never filtered. A per-query
+     * `skipGlobalFilters: true | string[]` opts out. The empty-`where` guard on
+     * `update`/`delete` still checks the USER-supplied `where`, so a global
+     * filter never turns an unguarded mass mutation into an allowed one.
+     *
+     * @example
+     * ```ts
+     * const db = turbine({ url, schema, globalFilters: {
+     *   posts: { deletedAt: null },              // soft-delete
+     *   orders: () => ({ tenantId: currentTenant() }), // per-request tenancy
+     * }});
+     * ```
+     */
+    globalFilters?: GlobalFilters;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {
@@ -314,6 +362,25 @@ export declare class TurbineClient {
     private readonly ownsPool;
     /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
     private readonly activeSubscriptions;
+    /**
+     * Read-replica pools in round-robin order. Empty when no replicas are
+     * configured, in which case `table()` takes the original single-pool path.
+     */
+    private readonly 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).
+     */
+    private readonly ownedReplicaPools;
+    /** Rotating index for round-robin replica selection (advances per read op). */
+    private replicaCursor;
+    /** Per-replica `table → QueryInterface` caches, indexed like {@link replicaPools}. */
+    private readonly replicaTableCaches;
+    /** Cache of per-table routing proxies (only used when replicas are present). */
+    private readonly routingProxyCache;
+    /** Lazily-built, cached primary-only view returned by {@link $primary}. */
+    private primaryView?;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
      * Register a middleware function that runs around every query.
@@ -353,8 +420,49 @@ export declare 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<T extends object = Record<string, unknown>>(name: string): QueryInterface<T>;
+    /** Get (and cache) the primary-pool-bound QueryInterface for a table. */
+    private primaryTableQI;
+    /**
+     * Advance the round-robin cursor and return the QueryInterface bound to the
+     * selected replica pool for `name` (cached per replica).
+     */
+    private nextReplicaTableQI;
+    /** Construct a QueryInterface bound to `pool` (honoring any injected factory). */
+    private buildTableQI;
+    /**
+     * 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.
+     */
+    private createRoutingAccessor;
+    /**
+     * 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(): TurbineClient;
     /**
      * Execute multiple queries in a single database round-trip.
      *
@@ -449,6 +557,33 @@ export declare class TurbineClient {
      * ```
      */
     $transaction<R>(fn: (tx: TransactionClient) => Promise<R>, options?: TransactionOptions): Promise<R>;
+    /**
+     * Batch form — run a tuple of {@link DeferredQuery} objects (produced by the
+     * `build*()` methods, e.g. `db.users.buildFindMany(...)`) atomically inside a
+     * single `BEGIN…COMMIT` on one connection. Returns a positionally-typed tuple
+     * of each query's transformed result; any failure rolls the whole batch back.
+     *
+     * Unlike {@link pipeline}, this never uses the extended-query pipeline
+     * protocol — it executes sequentially on the transaction connection, so it is
+     * safe on every driver (including HTTP/serverless pools).
+     *
+     * @example
+     * ```ts
+     * const [user, count] = await db.$transaction([
+     *   db.users.buildFindUnique({ where: { id: 1 } }),
+     *   db.posts.buildCount({ where: { userId: 1 } }),
+     * ]);
+     * ```
+     */
+    $transaction<T extends readonly DeferredQuery<unknown>[]>(queries: readonly [...T]): Promise<PipelineResults<T>>;
+    /**
+     * 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`.
+     */
+    private transactionBatch;
     /**
      * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
      * runs `fn` inside a transaction with the given session GUCs applied via