turbine-orm 0.35.0 → 0.36.0

package/dist/cjs/schema-builder.js

@@ -101,6 +101,7 @@ function resolveColumn(def) {
         vectorDimensions: def.dimensions ?? null,
         isArray: def.array ?? false,
         check: def.check ?? null,
+        pii: def.pii ?? false,
     };
 }
 /** Type guard: is this index declaration a doc-field expression index? */
@@ -254,6 +255,7 @@ class ColumnBuilder {
             vectorDimensions: null,
             isArray: false,
             check: null,
+            pii: false,
         };
     }
     serial() {
@@ -360,6 +362,10 @@ class ColumnBuilder {
         this._config.check = expression;
         return this;
     }
+    pii() {
+        this._config.pii = true;
+        return this;
+    }
     array() {
         this._config.isArray = true;
         return this;

package/dist/cjs/schema-metadata.js

@@ -340,6 +340,10 @@ function schemaDefToMetadata(def) {
                 arrayType: (0, schema_js_1.pgArrayType)(base),
                 pgArrayType: (0, schema_js_1.pgArrayType)(base),
                 ...(serial ? { isGenerated: true } : {}),
+                // PII is a code-first declaration; carry it through so query-layer
+                // default-projection exclusion and Studio redaction can honor it.
+                // Only set when true, keeping output byte-stable for untagged schemas.
+                ...(config.pii ? { pii: true } : {}),
                 ...(config.maxLength != null ? { maxLength: config.maxLength } : {}),
             };
             columns.push(col);

package/dist/cjs/schema-sql.js

@@ -9,20 +9,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DestructivePushRefusal = void 0;
 exports.referentialActionToSql = referentialActionToSql;
 exports.schemaToSQL = schemaToSQL;
+exports.describeIndexDefMismatch = describeIndexDefMismatch;
+exports.undeclaredIndexWarnings = undeclaredIndexWarnings;
 exports.buildAddForeignKeyStatement = buildAddForeignKeyStatement;
 exports.diffReferentialAction = diffReferentialAction;
 exports.diffEnumValues = diffEnumValues;
 exports.diffCheckConstraints = diffCheckConstraints;
 exports.schemaDiff = schemaDiff;
+exports.findDestructivePushStatements = findDestructivePushStatements;
 exports.schemaPush = schemaPush;
 exports.schemaToSQLString = schemaToSQLString;
 const pg_1 = __importDefault(require("pg"));
+const destructive_js_1 = require("./cli/destructive.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
 const schema_js_1 = require("./schema.js");
+const schema_builder_js_1 = require("./schema-builder.js");
 /** Map a {@link ReferentialAction} to its SQL keyword form. */
 function referentialActionToSql(action) {
     switch (action) {
@@ -124,6 +130,11 @@ function schemaToSQL(schema, options) {
         const indexes = generateForeignKeyIndexes(table, dialect);
         statements.push(...indexes);
     }
+    // Generate CREATE INDEX / CREATE UNIQUE INDEX for user-declared indexes.
+    for (const tableName of sorted) {
+        const table = schema.tables[tableName];
+        statements.push(...generateDeclaredIndexes(table, dialect));
+    }
     return statements;
 }
 /**
@@ -341,10 +352,16 @@ function normalizeDefault(val) {
  */
 function generateForeignKeyIndexes(table, dialect = dialect_js_1.postgresDialect) {
     const indexes = [];
+    // A declared index whose deterministic name matches the auto FK-index name
+    // takes precedence (it may be UNIQUE); emitting both would fail at apply time
+    // with "relation already exists".
+    const declared = declaredPlainIndexNames(table);
     for (const [fieldName, config] of Object.entries(table.columns)) {
         if (config.referencesTarget) {
             const snakeName = (0, schema_js_1.camelToSnake)(fieldName);
             const indexName = `idx_${table.name}_${snakeName}`;
+            if (declared.has(indexName))
+                continue;
             indexes.push(dialect.buildCreateIndexStatement({
                 name: dialect.quoteIdentifier(indexName),
                 table: dialect.quoteIdentifier(table.name),
@@ -354,6 +371,116 @@ function generateForeignKeyIndexes(table, dialect = dialect_js_1.postgresDialect
     }
     return indexes;
 }
+/**
+ * The deterministic SQL index name for a declared plain (column-list) index:
+ * the user-supplied `name`, else `idx_<table>_<col1>_<col2>...`, mirroring the
+ * FK-index convention in {@link generateForeignKeyIndexes}.
+ */
+function declaredIndexName(tableName, idx) {
+    if (idx.name)
+        return idx.name;
+    const cols = idx.columns.map(schema_js_1.camelToSnake);
+    return `idx_${tableName}_${cols.join('_')}`;
+}
+/**
+ * Compare a declared plain index against a pg_indexes `indexdef` string.
+ * Returns a human-readable description of the first mismatch (uniqueness or
+ * column list), or null when the definitions agree. Expression/partial indexes
+ * in the DB never structurally match a plain column list, which is the
+ * intended outcome: the operator gets a warning rather than a silent skip.
+ */
+function describeIndexDefMismatch(idx, indexdef) {
+    const dbUnique = /^\s*CREATE\s+UNIQUE\s+INDEX\b/i.test(indexdef);
+    const wantUnique = idx.unique === true;
+    if (dbUnique !== wantUnique) {
+        return wantUnique
+            ? 'declared UNIQUE, existing index is not unique'
+            : 'existing index is UNIQUE, declaration is not';
+    }
+    // pg_indexes.indexdef always reads `CREATE [UNIQUE] INDEX name ON tbl
+    // USING method (col, ...) [WHERE ...]`; anchor on the USING clause so a
+    // partial index's WHERE parentheses are never mistaken for the column list.
+    const parenMatch = indexdef.match(/USING\s+\w+\s*\(([^)]*)\)/i) ?? indexdef.match(/\(([^)]*)\)/);
+    const dbCols = parenMatch
+        ? parenMatch[1].split(',').map((c) => c
+            .trim()
+            .replace(/\s+(ASC|DESC|NULLS\s+(FIRST|LAST))\b/gi, '')
+            .replace(/^"(.*)"$/, '$1')
+            .trim())
+        : [];
+    const wantCols = idx.columns.map(schema_js_1.camelToSnake);
+    if (dbCols.length !== wantCols.length || dbCols.some((c, i) => c !== wantCols[i])) {
+        return `declared columns (${wantCols.join(', ')}) differ from existing (${dbCols.join(', ') || 'unparsed'})`;
+    }
+    if (/\bWHERE\b/i.test(indexdef))
+        return 'existing index is partial (has a WHERE clause)';
+    return null;
+}
+/**
+ * Pure decision for the "index exists in the DB but is not declared" warning
+ * pass. Extracted so the scope rule is unit-testable without a live database.
+ *
+ * The pass runs only when the table opts into index management by DEFINING an
+ * `indexes` array (`indexesDefined: true`), even when that array is empty or
+ * all-doc-field: deleting the last declared index must NOT silence the pass.
+ * Tables with no `indexes` key stay silent (the user is not managing indexes
+ * there). Recognized names (declared, unique-constraint / FK-column, `*_pkey`)
+ * are never flagged; everything else in the DB yields one warning.
+ */
+function undeclaredIndexWarnings(opts) {
+    if (!opts.indexesDefined)
+        return [];
+    const out = [];
+    for (const dbIdxName of opts.dbIndexNames) {
+        if (opts.declaredNames.has(dbIdxName) || opts.recognizedNames.has(dbIdxName) || dbIdxName.endsWith('_pkey')) {
+            continue;
+        }
+        out.push(`index "${dbIdxName}" on "${opts.tableName}" exists in the database but is not declared in the schema. ` +
+            `Turbine does not drop indexes automatically; drop it in a manual migration if it is no longer needed.`);
+    }
+    return out;
+}
+/** The deterministic SQL names of every declared plain index on a table. */
+function declaredPlainIndexNames(table) {
+    const names = new Set();
+    for (const idx of table.indexes ?? []) {
+        if ((0, schema_builder_js_1.isDocFieldIndexDef)(idx) || idx.columns.length === 0)
+            continue;
+        names.add(declaredIndexName(table.name, idx));
+    }
+    return names;
+}
+/**
+ * Build the `CREATE [UNIQUE] INDEX` statement for a declared plain index.
+ * `buildCreateIndexStatement` has no `unique` hook, so unique indexes are
+ * emitted directly here (still fully identifier-quoted via the dialect).
+ */
+function buildDeclaredIndexStatement(tableName, idx, dialect) {
+    const cols = idx.columns.map(schema_js_1.camelToSnake);
+    if (cols.length === 0)
+        return null;
+    const name = declaredIndexName(tableName, idx);
+    const quotedCols = cols.map((c) => dialect.quoteIdentifier(c)).join(', ');
+    const unique = idx.unique ? 'UNIQUE ' : '';
+    return `CREATE ${unique}INDEX ${dialect.quoteIdentifier(name)} ON ${dialect.quoteIdentifier(tableName)}(${quotedCols});`;
+}
+/**
+ * Generate `CREATE INDEX` / `CREATE UNIQUE INDEX` for a table's user-declared
+ * plain-column indexes. PowDB doc-field expression indexes ({@link DocFieldIndexDef})
+ * are skipped here (those stay PowDB-only, emitted by `powqlSchemaDDL`) and have
+ * no SQL equivalent.
+ */
+function generateDeclaredIndexes(table, dialect = dialect_js_1.postgresDialect) {
+    const out = [];
+    for (const idx of table.indexes ?? []) {
+        if ((0, schema_builder_js_1.isDocFieldIndexDef)(idx))
+            continue; // PowDB-only, no SQL emission
+        const stmt = buildDeclaredIndexStatement(table.name, idx, dialect);
+        if (stmt)
+            out.push(stmt);
+    }
+    return out;
+}
 /**
  * Build the `ADD CONSTRAINT ... FOREIGN KEY` statement for a FK with the given
  * referential actions. Default (`no action`) clauses are omitted, matching how
@@ -546,6 +673,16 @@ async function schemaDiff(schema, connectionString) {
                 dbChecks[row.table_name] = [];
             dbChecks[row.table_name].push({ name: row.conname, expression: (0, introspect_js_1.stripCheckWrapper)(row.definition) });
         }
+        // Existing index NAMES per table (for the declared-index diff). Covers PK,
+        // unique-constraint, FK, and user indexes alike; the diff only ADDs declared
+        // indexes whose name is missing and never auto-drops any (see below).
+        const indexResult = await client.query(`SELECT tablename, indexname, indexdef FROM pg_indexes WHERE schemaname = 'public'`);
+        const dbIndexes = {};
+        for (const row of indexResult.rows) {
+            if (!dbIndexes[row.tablename])
+                dbIndexes[row.tablename] = new Map();
+            dbIndexes[row.tablename].set(row.indexname, row.indexdef);
+        }
         // Build a set of DDL-facing snake_case table names that the schema defines.
         const schemaDdlNames = new Set();
         for (const def of Object.values(schema.tables))
@@ -578,6 +715,8 @@ async function schemaDiff(schema, connectionString) {
                 result.statements.push(generateCreateTable(tableDef, resolveRef, dialect));
                 const fkIndexes = generateForeignKeyIndexes(tableDef, dialect);
                 result.statements.push(...fkIndexes);
+                // User-declared indexes on a brand-new table (reversed by the DROP TABLE).
+                result.statements.push(...generateDeclaredIndexes(tableDef, dialect));
                 // Reverse: DROP TABLE (with indexes — they drop automatically)
                 result.reverseStatements.unshift(`DROP TABLE IF EXISTS ${dialect.quoteIdentifier(ddlName)} CASCADE;`);
             }
@@ -761,6 +900,67 @@ async function schemaDiff(schema, connectionString) {
                         `To intentionally replace it, rename the constraint or drop/re-add it in a manual migration.`);
                 }
             }
+            // --- User-declared indexes (TableDef.indexes) ---
+            // ADD any declared plain index whose NAME is missing from the DB (reverse:
+            // DROP INDEX). Doc-field indexes are PowDB-only and skipped. We never
+            // auto-drop DB indexes not in the schema, matching the column-drop posture.
+            // When the table declares at least one index (the user is actively managing
+            // indexes here), unrecognized extra DB indexes are surfaced as warnings so
+            // the operator can drop them by hand if intended. Recognized = PK, unique
+            // constraint, or FK-column index names, which the schema never declares.
+            // Run the whole index-management pass whenever the table DEFINES an
+            // `indexes` array (even empty or all-doc-field): a table with an `indexes`
+            // key is one the user is actively managing, so undeclared DB indexes stay
+            // worth surfacing. Deleting the last declared index must NOT silence the
+            // warning pass. Tables with no `indexes` key stay silent (not managed).
+            const declaredPlain = (tableDef.indexes ?? []).filter((i) => !(0, schema_builder_js_1.isDocFieldIndexDef)(i));
+            if (tableDef.indexes !== undefined) {
+                const dbIdx = dbIndexes[tableName] ?? new Map();
+                const dbIdxNames = new Set(dbIdx.keys());
+                const declaredNames = new Set();
+                for (const idx of declaredPlain) {
+                    if (idx.columns.length === 0)
+                        continue;
+                    const name = declaredIndexName(tableName, idx);
+                    declaredNames.add(name);
+                    const existingDef = dbIdx.get(name);
+                    if (existingDef === undefined) {
+                        const stmt = buildDeclaredIndexStatement(tableName, idx, dialect);
+                        if (!stmt)
+                            continue;
+                        result.statements.push(stmt);
+                        result.reverseStatements.unshift(`DROP INDEX IF EXISTS ${dialect.quoteIdentifier(name)};`);
+                    }
+                    else {
+                        // Name matches an existing index: verify the definition agrees.
+                        // Matching is by name, so a definition drift (a declared UNIQUE
+                        // index colliding with the plain auto FK index, or a changed
+                        // column list) would otherwise be silently skipped, leaving the
+                        // declared guarantee unenforced. Warn, never drop.
+                        const mismatch = describeIndexDefMismatch(idx, existingDef);
+                        if (mismatch) {
+                            result.warnings.push(`index "${name}" on "${tableName}": the declared definition does not match the existing ` +
+                                `database index (${mismatch}). Turbine matches indexes by name and never drops them ` +
+                                `automatically; drop and recreate it in a manual migration to apply the declared definition.`);
+                        }
+                    }
+                }
+                // Recognized (never-declared) index names: unique-constraint + FK-column.
+                const recognized = new Set(Object.values(dbUniques[tableName] ?? {}));
+                for (const [fieldName, config] of Object.entries(tableDef.columns)) {
+                    if (config.referencesTarget)
+                        recognized.add(`idx_${tableName}_${(0, schema_js_1.camelToSnake)(fieldName)}`);
+                }
+                for (const w of undeclaredIndexWarnings({
+                    tableName,
+                    indexesDefined: tableDef.indexes !== undefined,
+                    dbIndexNames: dbIdxNames,
+                    declaredNames,
+                    recognizedNames: recognized,
+                })) {
+                    result.warnings.push(w);
+                }
+            }
         }
         return result;
     }
@@ -850,15 +1050,70 @@ function defaultsMatch(schemaDefault, dbDefault) {
     const b = normalizeDbDefault(dbDefault).toLowerCase().trim();
     return a === b;
 }
+// ---------------------------------------------------------------------------
+// Schema Push — execute the diff against a live database
+// ---------------------------------------------------------------------------
+/**
+ * Scan a set of diff statements for data-destroying operations, using the same
+ * conservative scanner (`scanDestructiveSql`) that gates `migrate up`/`down`.
+ * Push mostly emits additive DDL, but a type change surfaces as a lossy
+ * `ALTER COLUMN ... TYPE` cast, exactly the kind of silent data loss `push`
+ * must never apply without an explicit opt-in.
+ */
+function findDestructivePushStatements(statements) {
+    const hits = [];
+    for (const stmt of statements)
+        hits.push(...(0, destructive_js_1.scanDestructiveSql)(stmt));
+    return hits;
+}
+/** Format the destructive-push refusal message (mirrors the migrate gate copy). */
+function formatDestructivePushError(hits) {
+    const lines = ['[turbine] Refusing to apply schema changes containing DESTRUCTIVE statements:', ''];
+    for (const h of hits) {
+        lines.push(`  - [${h.kind}] ${h.target}: ${destructive_js_1.DESTRUCTIVE_KIND_LABEL[h.kind]}`);
+    }
+    lines.push('');
+    lines.push('Review the statements above. To proceed: run `npx turbine push` interactively');
+    lines.push('and confirm, pass --allow-destructive, or set allowDestructive: true programmatically.');
+    return lines.join('\n');
+}
+/**
+ * Thrown by {@link schemaPush} when the diff contains data-destroying statements
+ * and `allowDestructive` was not set. A typed subclass of {@link ValidationError}
+ * (same `TURBINE_E003` code, no new taxonomy entry) so callers can branch on
+ * `instanceof DestructivePushRefusal` instead of sniffing the message text. The
+ * offending statements are carried on `.destructive` for programmatic display.
+ */
+class DestructivePushRefusal extends errors_js_1.ValidationError {
+    /** The destructive statements the push refused to apply. */
+    destructive;
+    constructor(destructive) {
+        super(formatDestructivePushError(destructive));
+        this.name = 'DestructivePushRefusal';
+        this.destructive = destructive;
+    }
+}
+exports.DestructivePushRefusal = DestructivePushRefusal;
 /**
  * Push a schema definition to a live database.
  *
  * Computes the diff, then executes the resulting DDL statements in a
- * single transaction. This is a destructive operation for ADD/ALTER —
- * it will NOT drop tables or columns unless explicitly configured.
+ * single transaction. It will NOT drop tables or columns.
+ *
+ * Data-loss gate: if the diff contains a destructive statement (e.g. a lossy
+ * `ALTER COLUMN ... TYPE` cast), `schemaPush` throws a
+ * {@link DestructivePushRefusal} (a {@link ValidationError} subclass carrying
+ * the offending statements on `.destructive`) listing the statements UNLESS
+ * `allowDestructive: true` is passed. The CLI (`turbine push`) catches this and
+ * prompts for the same typed confirmation as `migrate up`; programmatic callers
+ * must opt in explicitly.
  */
 async function schemaPush(schema, connectionString, options = {}) {
-    const diff = await schemaDiff(schema, connectionString);
+    // Accept a precomputed diff so a caller (the CLI) can diff ONCE, show the
+    // plan, confirm, and apply the EXACT statements it displayed. Without this,
+    // schemaPush would re-diff on the post-confirmation retry, so a concurrent
+    // schema change between confirm and apply could alter the applied set (TOCTOU).
+    const diff = options.precomputedDiff ?? (await schemaDiff(schema, connectionString));
     const result = {
         statementsExecuted: 0,
         statements: diff.statements,
@@ -868,6 +1123,13 @@ async function schemaPush(schema, connectionString, options = {}) {
     if (options.dryRun || diff.statements.length === 0) {
         return result;
     }
+    // Destructive-statement gate: refuse silent data loss unless opted in.
+    if (!options.allowDestructive) {
+        const destructive = findDestructivePushStatements(diff.statements);
+        if (destructive.length > 0) {
+            throw new DestructivePushRefusal(destructive);
+        }
+    }
     // Execute all statements in a transaction
     const client = new pg_1.default.Client({ connectionString });
     await client.connect();

package/dist/cjs/sqlite.js

@@ -434,7 +434,7 @@ exports.sqliteDialect = {
         return JSON.stringify(values ?? []);
     },
     buildReturningClause(selection = '*') {
-        return ` RETURNING ${selection}`;
+        return ` RETURNING ${selection === '*' ? '*' : selection.join(', ')}`;
     },
     buildInsertStatement(input) {
         return (`INSERT INTO ${input.table} (${input.columns.join(', ')}) ` +

package/dist/cli/index.d.ts

@@ -5,8 +5,8 @@
  * Commands:
  *   turbine init                  — Initialize a Turbine project
  *   turbine generate | pull       — Introspect database and generate TypeScript types
- *   turbine push                  — Apply schema-builder definitions to database
- *   turbine migrate create <name> — Create a new SQL migration file
+ *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
+ *   turbine migrate create <name> - Create a new SQL migration file (--auto | --recipe <name>)
  *   turbine migrate up            — Apply pending migrations
  *   turbine migrate deploy        — Apply pending migrations without prompts
  *   turbine migrate down          — Rollback last migration
@@ -41,6 +41,8 @@ export interface CliArgs {
     allowDrift?: boolean;
     allowEmpty?: boolean;
     allowDestructive?: boolean;
+    /** `migrate create --recipe <name>` scaffold selector. */
+    recipe?: string;
     fix?: boolean;
     zod?: boolean;
     includeViews?: boolean;
@@ -51,6 +53,10 @@ export interface CliArgs {
     noOpen?: boolean;
     /** Opt-in to bind Studio/Observe on a non-loopback host. */
     allowRemote?: boolean;
+    /** Opt-in to Studio single-row write mode (`studio --write`). */
+    write?: boolean;
+    /** Reveal PII-tagged column values in Studio instead of redacting (`--show-pii`). */
+    showPii?: boolean;
 }
 export declare function parseArgs(argv?: string[]): CliArgs;
 /** Where a resolved `DATABASE_URL` came from, after the `.env` load. */