turbine-orm 0.19.1 → 0.19.2

package/dist/cjs/cli/studio.js

@@ -34,7 +34,6 @@ exports.apiBuilder = apiBuilder;
 exports.apiListSavedQueries = apiListSavedQueries;
 exports.apiCreateSavedQuery = apiCreateSavedQuery;
 exports.apiDeleteSavedQuery = apiDeleteSavedQuery;
-exports.isReadOnlyStatement = isReadOnlyStatement;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
@@ -550,35 +549,6 @@ function clampInt(value, fallback, min, max) {
         return fallback;
     return Math.min(Math.max(n, min), max);
 }
-/**
- * Accept only SELECT or WITH (CTE) statements. Reject any statement that
- * contains a semicolon followed by non-whitespace (prevents statement
- * stacking), and require the first non-comment keyword to be SELECT or WITH.
- *
- * This is a first-line filter — the transaction's READ ONLY mode is the
- * second line of defense. Both must fail before a destructive statement
- * could run.
- */
-function isReadOnlyStatement(sql) {
-    const stripped = stripSqlComments(sql).trim();
-    if (!stripped)
-        return false;
-    // Disallow statement stacking. A single trailing `;` is fine.
-    const withoutTrailingSemi = stripped.replace(/;+\s*$/, '');
-    if (withoutTrailingSemi.includes(';'))
-        return false;
-    const firstWord = withoutTrailingSemi.slice(0, 6).toUpperCase();
-    if (firstWord.startsWith('SELECT'))
-        return true;
-    if (firstWord.startsWith('WITH'))
-        return true;
-    return false;
-}
-function stripSqlComments(sql) {
-    // Strip -- line comments and /* block comments */. Not a full SQL parser,
-    // but sufficient to catch the common bypass attempts.
-    return sql.replace(/--[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
-}
 function serializeRow(row) {
     const out = {};
     for (const [k, v] of Object.entries(row)) {

package/dist/cjs/client.js

@@ -331,12 +331,14 @@ class TurbineClient {
     // Middleware — intercept all queries
     // -------------------------------------------------------------------------
     /**
-     * Register a middleware function that runs before/after every query.
+     * Register a middleware function that runs around every query.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      *
      * @example
      * ```ts
@@ -348,16 +350,13 @@ class TurbineClient {
      *   return result;
      * });
      *
-     * // Soft-delete middleware
+     * // Result transformation middleware — redact a field on the way out
      * db.$use(async (params, next) => {
-     *   if (params.action === 'findMany' || params.action === 'findUnique') {
-     *     params.args.where = { ...params.args.where, deletedAt: null };
-     *   }
-     *   if (params.action === 'delete') {
-     *     params.action = 'update';
-     *     params.args = { where: params.args.where, data: { deletedAt: new Date() } };
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
      *   }
-     *   return next(params);
+     *   return result;
      * });
      * ```
      */

package/dist/cjs/query/builder.js

@@ -80,6 +80,53 @@ function isUnmatchedPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
+ * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
+ * param pushed), so null-ness is part of the shape — without it a cache entry
+ * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ */
+function fingerprintOperatorShape(value) {
+    const obj = value;
+    const opKeys = Object.keys(obj)
+        .filter((k) => k !== 'mode')
+        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .sort();
+    const modeStr = value.mode === 'insensitive' ? ':i' : '';
+    return `op(${opKeys.join(',')}${modeStr})`;
+}
+/**
+ * Guard for the value of an `equals` operator reaching the plain-equality
+ * operator path. A plain object literal can only legitimately be an equality
+ * value on a json/jsonb column — and those route to the JSONB filter branch
+ * BEFORE the operator branch, so any plain object that reaches here is a
+ * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
+ * SQL-build path and the cache-hit param-collect path so a warmed cache can
+ * never skip the check.
+ */
+function assertBindableEqualsOperand(value, column) {
+    if (!isUnmatchedPlainObject(value))
+        return;
+    throw new errors_js_1.ValidationError(`[turbine] Plain-object value for operator 'equals' on ${column}: ` +
+        `objects are only valid 'equals' values on JSON (json/jsonb) columns, ` +
+        `where 'equals' is the JSONB containment filter.`);
+}
+/**
+ * Object keys in sorted order, mirroring the canonical order used by every
+ * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
+ * enumerate object keys in this exact order: fingerprints sort keys, so two
+ * where clauses with the same fields in different insertion order share one
+ * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
+ * Array order (OR/AND members) is positional and is never sorted.
+ */
+function sortedKeys(obj) {
+    return Object.keys(obj).sort();
+}
+/** {@link sortedKeys}, but yielding `[key, value]` pairs. */
+function sortedEntries(obj) {
+    return Object.entries(obj).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
 /** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
 const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
@@ -89,9 +136,11 @@ const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
  * appear in any other where-filter shape, so the presence of one of these is
  * an unambiguous signal that the user meant a JSON filter. Used by the
  * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
- * `WhereOperator` for LIKE) is not misclassified.
+ * `WhereOperator` for LIKE) is not misclassified. Note `equals` is NOT in this
+ * set: on non-JSON columns it is a plain equality operator (`WhereOperator`),
+ * so it must fall through instead of throwing.
  */
-const JSONB_UNIQUE_KEYS = new Set(['path', 'equals', 'hasKey']);
+const JSONB_UNIQUE_KEYS = new Set(['path', 'hasKey']);
 /** Check if a value is a JSONB filter object */
 function isJsonFilter(value) {
     if (value === null ||
@@ -392,10 +441,12 @@ class QueryInterface {
      * Execute a query through the middleware chain.
      * If no middlewares are registered, executes directly.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      */
     async executeWithMiddleware(action, args, executor) {
         this.currentAction = action;
@@ -434,8 +485,12 @@ class QueryInterface {
         const withFp = args.with ? this.withFingerprint(args.with) : '';
         const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}`;
         const params = [];
-        // Check if all where values are simple (plain equality, no operators/null/OR)
-        const whereKeys = Object.keys(whereObj).filter((k) => whereObj[k] !== undefined);
+        // Check if all where values are simple (plain equality, no operators/null/OR).
+        // Keys are sorted to match fingerprintWhere — insertion order here would let
+        // permuted where literals share a cache entry with misaligned params.
+        const whereKeys = Object.keys(whereObj)
+            .filter((k) => whereObj[k] !== undefined)
+            .sort();
         const isSimpleWhere = !whereObj.OR &&
             !whereObj.AND &&
             !whereObj.NOT &&
@@ -639,7 +694,8 @@ class QueryInterface {
             }
             let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
             if (args?.cursor) {
-                const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
+                // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
+                const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
@@ -680,9 +736,9 @@ class QueryInterface {
         if (args?.with) {
             this.collectWithParams(args.with, params);
         }
-        // 3. Cursor params
+        // 3. Cursor params — sorted (canonical) order, matching cursorFp and the build path.
         if (args?.cursor) {
-            const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
+            const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
             for (const [, v] of cursorEntries) {
                 params.push(v);
             }
@@ -1922,12 +1978,7 @@ class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
                 continue;
             }
             // Vector distance filter — metric (operator) and present comparators
@@ -2000,12 +2051,7 @@ class QueryInterface {
                 parts.push(`${key}:null`);
             }
             else if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
             }
             else if (isUnmatchedPlainObject(value)) {
                 parts.push(`${key}:obj(${Object.keys(value)
@@ -2026,7 +2072,8 @@ class QueryInterface {
      * @internal Exposed as package-private for testing.
      */
     collectWhereParams(where, params) {
-        const keys = Object.keys(where);
+        // Sorted (canonical) order — MUST match fingerprintWhere and buildWhereClause.
+        const keys = sortedKeys(where);
         for (const key of keys) {
             const value = where[key];
             if (value === undefined)
@@ -2111,7 +2158,7 @@ class QueryInterface {
             }
             // Operator objects
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(rawColumn, value, params);
                 continue;
             }
             // Plain equality — same strict validation as the build path, so a
@@ -2125,22 +2172,28 @@ class QueryInterface {
         const meta = this.schema.tables[targetTable];
         if (!meta)
             return;
-        for (const [field, value] of Object.entries(subWhere)) {
+        // Sorted (canonical) order — MUST match fingerprintRelFilter and buildSubWhereForRelation.
+        for (const field of sortedKeys(subWhere)) {
+            const value = subWhere[field];
             if (value === undefined)
                 continue;
             if (value === null)
                 continue;
+            const col = meta.columnMap[field] ?? (0, schema_js_1.camelToSnake)(field);
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(col, value, params);
                 continue;
             }
-            const col = meta.columnMap[field] ?? (0, schema_js_1.camelToSnake)(field);
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
         }
     }
     /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
-    collectOperatorParams(op, params) {
+    collectOperatorParams(column, op, params) {
+        if (op.equals !== undefined && op.equals !== null) {
+            assertBindableEqualsOperand(op.equals, `"${column}"`);
+            params.push(op.equals);
+        }
         if (op.gt !== undefined)
             params.push(op.gt);
         if (op.gte !== undefined)
@@ -2296,7 +2349,7 @@ class QueryInterface {
         const meta = this.schema.tables[table ?? this.table];
         if (!meta)
             return;
-        for (const [relName, relSpec] of Object.entries(withClause)) {
+        for (const [relName, relSpec] of sortedEntries(withClause)) {
             const relDef = meta.relations[relName];
             if (!relDef)
                 continue;
@@ -2323,7 +2376,7 @@ class QueryInterface {
                 params.push(Number(spec.limit));
             }
             if (spec.with) {
-                for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                     const nestedRelDef = targetMeta.relations[nestedRelName];
                     if (!nestedRelDef)
                         continue;
@@ -2337,7 +2390,7 @@ class QueryInterface {
         const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
         // Non-wrapped path: nested relations BEFORE where/limit
         if (!willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef)
                     continue;
@@ -2357,7 +2410,7 @@ class QueryInterface {
         }
         // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
         if (willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef)
                     continue;
@@ -2439,7 +2492,8 @@ class QueryInterface {
      * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
      */
     buildWhereClause(where, params) {
-        const keys = Object.keys(where);
+        // Sorted (canonical) order — MUST match fingerprintWhere and collectWhereParams.
+        const keys = sortedKeys(where);
         if (keys.length === 0)
             return null;
         const andClauses = [];
@@ -2646,7 +2700,9 @@ class QueryInterface {
             return null;
         const qt = this.q(targetTable);
         const conditions = [];
-        for (const [field, value] of Object.entries(subWhere)) {
+        // Sorted (canonical) order — MUST match fingerprintRelFilter and collectRelFilterParams.
+        for (const field of sortedKeys(subWhere)) {
+            const value = subWhere[field];
             if (value === undefined)
                 continue;
             const col = meta.columnMap[field] ?? (0, schema_js_1.camelToSnake)(field);
@@ -2711,7 +2767,9 @@ class QueryInterface {
      */
     buildAliasWhere(targetTable, targetMeta, alias, where, params) {
         const clauses = [];
-        for (const [key, value] of Object.entries(where)) {
+        // Sorted (canonical) order — MUST match fingerprintAliasWhere and collectAliasWhereParams.
+        for (const key of sortedKeys(where)) {
+            const value = where[key];
             if (value === undefined)
                 continue;
             if (key === 'OR' || key === 'AND') {
@@ -2753,7 +2811,9 @@ class QueryInterface {
     }
     /** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
     collectAliasWhereParams(targetTable, targetMeta, where, params) {
-        for (const [key, value] of Object.entries(where)) {
+        // Sorted (canonical) order — MUST match fingerprintAliasWhere and buildAliasWhere.
+        for (const key of sortedKeys(where)) {
+            const value = where[key];
             if (value === undefined)
                 continue;
             if (key === 'OR' || key === 'AND') {
@@ -2771,11 +2831,11 @@ class QueryInterface {
             }
             if (value === null)
                 continue;
+            const col = targetMeta.columnMap[key] ?? (0, schema_js_1.camelToSnake)(key);
             if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
+                this.collectOperatorParams(col, value, params);
                 continue;
             }
-            const col = targetMeta.columnMap[key] ?? (0, schema_js_1.camelToSnake)(key);
             this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
             params.push(value);
         }
@@ -2809,11 +2869,7 @@ class QueryInterface {
                 continue;
             }
             if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                parts.push(`${key}:op(${opKeys.join(',')}${mode === 'insensitive' ? ':i' : ''})`);
+                parts.push(`${key}:${fingerprintOperatorShape(value)}`);
                 continue;
             }
             if (isUnmatchedPlainObject(value)) {
@@ -2832,6 +2888,16 @@ class QueryInterface {
      */
     buildOperatorClauses(column, op, params) {
         const clauses = [];
+        if (op.equals !== undefined) {
+            if (op.equals === null) {
+                clauses.push(`${column} IS NULL`);
+            }
+            else {
+                assertBindableEqualsOperand(op.equals, column);
+                params.push(op.equals);
+                clauses.push(`${column} = ${this.p(params.length)}`);
+            }
+        }
         if (op.gt !== undefined) {
             params.push(op.gt);
             clauses.push(`${column} > ${this.p(params.length)}`);
@@ -3130,7 +3196,7 @@ class QueryInterface {
         const baseCols = cols.map((col) => `${qtbl}.${this.q(col)}`).join(', ');
         const relationSelects = [];
         const aliasCounter = { n: 0 };
-        for (const [relName, relSpec] of Object.entries(withClause)) {
+        for (const [relName, relSpec] of sortedEntries(withClause)) {
             const relDef = meta.relations[relName];
             if (!relDef) {
                 throw new errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" on table "${table}". ` +
@@ -3285,7 +3351,7 @@ class QueryInterface {
         }
         // Nested relations — only in the non-wrapped path (wrapped path builds them separately)
         if (!willWrap && spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef) {
                     throw new errors_js_1.RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3361,7 +3427,7 @@ class QueryInterface {
                 ]);
                 // Build nested relation subqueries referencing innerAlias
                 if (spec !== true && spec.with) {
-                    for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                    for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                         const nestedRelDef = targetMeta.relations[nestedRelName];
                         if (!nestedRelDef) {
                             throw new errors_js_1.RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3479,7 +3545,7 @@ class QueryInterface {
             ]);
             // Nested relations reference the inner alias.
             if (spec !== true && spec.with) {
-                for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+                for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                     const nestedRelDef = targetMeta.relations[nestedRelName];
                     if (!nestedRelDef) {
                         throw new errors_js_1.RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
@@ -3502,7 +3568,7 @@ class QueryInterface {
             `${talias}.${this.q(col)}`,
         ]);
         if (spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
+            for (const [nestedRelName, nestedSpec] of sortedEntries(spec.with)) {
                 const nestedRelDef = targetMeta.relations[nestedRelName];
                 if (!nestedRelDef) {
                     throw new errors_js_1.RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +

package/dist/cjs/query/utils.js

@@ -109,6 +109,7 @@ function sqlToPreparedName(sql) {
 }
 /** Known operator keys — used to detect operator objects vs plain values */
 exports.OPERATOR_KEYS = new Set([
+    'equals',
     'gt',
     'gte',
     'lt',

package/dist/cli/index.js

@@ -1129,13 +1129,15 @@ function showMigrateHelp() {
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
+    console.log(`    ${cyan('--auto')}            Auto-generate UP/DOWN SQL from schema diff ${dim('(create only)')}`);
     console.log(`    ${cyan('--step, -n')} ${dim('<N>')}    Number of migrations to apply/rollback`);
-    console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
-    console.log(`    ${cyan('--allow-drift')}      Bypass checksum validation ${dim('(migrate up only — advanced)')}`);
-    console.log(`    ${cyan('--verbose, -v')}      Show detailed output`);
+    console.log(`    ${cyan('--dry-run')}         Show SQL without executing`);
+    console.log(`    ${cyan('--allow-drift')}     Bypass checksum validation ${dim('(migrate up only — advanced)')}`);
+    console.log(`    ${cyan('--verbose, -v')}     Show detailed output`);
     newline();
     console.log(`  ${bold('Examples:')}`);
     console.log(`    ${dim('$')} npx turbine migrate create add_users_table`);
+    console.log(`    ${dim('$')} npx turbine migrate create add_email_index --auto`);
     console.log(`    ${dim('$')} npx turbine migrate up`);
     console.log(`    ${dim('$')} npx turbine migrate down --step 2`);
     console.log(`    ${dim('$')} npx turbine migrate status`);
@@ -1180,16 +1182,17 @@ function showHelp() {
     newline();
     console.log(`  ${bold('Commands:')}`);
     console.log(`    ${cyan('init')}               Initialize a Turbine project`);
-    console.log(`    ${cyan('generate')} ${dim('| pull')}   Introspect database ${symbols.arrow} generate types`);
+    console.log(`    ${cyan('generate')} ${dim('| pull')}    Introspect database ${symbols.arrow} generate types`);
     console.log(`    ${cyan('push')}               Apply schema definitions to database`);
-    console.log(`    ${cyan('migrate')} ${dim('<sub>')}     SQL migration management`);
-    console.log(`      ${dim('create <name>')}     Create a new migration file`);
+    console.log(`    ${cyan('migrate')} ${dim('<sub>')}      SQL migration management`);
+    console.log(`      ${dim('create <name>')}    Create a new migration file`);
     console.log(`      ${dim('up')}               Apply pending migrations`);
     console.log(`      ${dim('down')}             Rollback last migration`);
     console.log(`      ${dim('status')}           Show applied/pending migrations`);
     console.log(`    ${cyan('seed')}               Run seed file`);
-    console.log(`    ${cyan('status')} ${dim('| info')}     Show schema summary`);
+    console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
     console.log(`    ${cyan('studio')}             Launch local read-only web UI`);
+    console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}      Postgres connection string`);
@@ -1201,8 +1204,13 @@ function showHelp() {
     console.log(`    ${cyan('--verbose, -v')}        Show detailed output`);
     console.log(`    ${cyan('--force, -f')}          Overwrite existing files`);
     newline();
-    console.log(`  ${bold('Studio options:')}`);
-    console.log(`    ${cyan('--port')} ${dim('<n>')}           HTTP port ${dim('(default: 4983)')}`);
+    console.log(`  ${bold('Migrate options:')}`);
+    console.log(`    ${cyan('--auto')}               Auto-generate UP/DOWN SQL from schema diff ${dim('(create)')}`);
+    console.log(`    ${cyan('--step, -n')} ${dim('<N>')}       Number of migrations to apply/rollback`);
+    console.log(`    ${cyan('--allow-drift')}        Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
+    newline();
+    console.log(`  ${bold('Studio / observe options:')}`);
+    console.log(`    ${cyan('--port')} ${dim('<n>')}           HTTP port ${dim('(default: 4983 studio, 4984 observe)')}`);
     console.log(`    ${cyan('--host')} ${dim('<addr>')}        Bind address ${dim('(default: 127.0.0.1)')}`);
     console.log(`    ${cyan('--no-open')}            Don't auto-open the browser`);
     newline();

package/dist/cli/migrate.d.ts

@@ -113,8 +113,8 @@ export declare function deriveLockId(databaseName: string): number;
  */
 export declare function migrateUp(connectionString: string, migrationsDir: string, options?: {
     step?: number;
-    allowDrift?: boolean /** @deprecated use allowDrift */;
-    force?: boolean;
+    allowDrift?: boolean;
+    force?: boolean /** @deprecated use allowDrift */;
     adapter?: DatabaseAdapter;
     dialect?: Dialect;
 }): Promise<{