@rvoh/dream 2.19.0 → 2.21.1

package/dist/cjs/src/helpers/cli/ASTConnectionBuilder.js

@@ -11,6 +11,7 @@ import intersection from '../intersection.js';
 import sortBy from '../sortBy.js';
 import uniq from '../uniq.js';
 import ASTBuilder from './ASTBuilder.js';
+import resolveIgnoredColumns from './resolveIgnoredColumns.js';
 /**
  * @internal
  *
@@ -265,12 +266,48 @@ may need to update the table getter in the corresponding Dream.
                 default: uniq(models.flatMap(model => model['scopes'].default.map(scopeStatement => scopeStatement.method))),
                 named: uniq(models.flatMap(model => model['scopes'].named.map(scopeStatement => scopeStatement.method))),
             },
-            columns: await this.getColumnData(tableName, associationData),
+            columns: this.withoutIgnoredColumns(await this.getColumnData(tableName, associationData), tableName),
             virtualColumns: uniq(models.flatMap(model => model['virtualAttributes'].map(prop => prop.property) || [])),
             associations: associationData,
             serializerKeys,
         };
     }
+    /**
+     * @internal
+     *
+     * resolves the ignored columns declared by the models backed by the
+     * given table (validating the declarations; see resolveIgnoredColumns)
+     */
+    ignoredColumnsForTable(tableName) {
+        const dreamApp = DreamApp.getOrFail();
+        const allModels = Object.values(dreamApp.models).filter(model => model.prototype?.connectionName === this.connectionName);
+        const models = allModels.filter(model => model.table === tableName);
+        return resolveIgnoredColumns(models, tableName, allModels);
+    }
+    /**
+     * @internal
+     *
+     * returns the provided column data without the columns that the table's
+     * models declare in ignoredColumns. This is what removes ignored columns
+     * from the generated dream schema file: `columns()` reads the generated
+     * schema at runtime, so every column enumeration built from `columns()`
+     * (preload and join-load select lists, save hydration, attribute
+     * definition) inherits this filtering. A column that is ignored but not
+     * present in the introspected table (e.g. after the drop migration has
+     * run but before the declaration is removed) is a no-op.
+     */
+    withoutIgnoredColumns(columnData, tableName) {
+        const ignoredColumns = this.ignoredColumnsForTable(tableName);
+        if (!ignoredColumns.size)
+            return columnData;
+        return Object.keys(columnData)
+            .filter(columnName => !ignoredColumns.has(columnName))
+            .reduce((filtered, columnName) => {
+            ;
+            filtered[columnName] = columnData[columnName];
+            return filtered;
+        }, {});
+    }
     /**
      * @internal
      *

package/dist/cjs/src/helpers/cli/ASTKyselyCodegenEnhancer.js

@@ -25,6 +25,7 @@ export default class ASTKyselyCodegenEnhancer extends ASTConnectionBuilder {
     async enhance() {
         let dbSourceFile = await this.getDbSourceFile();
         dbSourceFile = this.camelizeKeys(dbSourceFile);
+        dbSourceFile = this.removeIgnoredColumns(dbSourceFile);
         dbSourceFile = this.replaceTimestampExport(dbSourceFile);
         dbSourceFile = await this.replaceTimeFieldsInInterfaces(dbSourceFile);
         dbSourceFile = this.addMissingImports(dbSourceFile);
@@ -283,6 +284,65 @@ ${output}`);
         const result = ts.transform(dbSourceFile, [transformer]);
         return result.transformed[0];
     }
+    /**
+     * @internal
+     *
+     * removes columns declared in model `ignoredColumns` getters from the
+     * table interfaces generated by kysely-codegen. This is what removes
+     * ignored columns from the generated db types file: every column-name
+     * level type (`DreamColumnNames`, `UpdateableProperties`, where-clause
+     * statements) derives from the Kysely `DB` interface, so filtering here
+     * turns any remaining code reference to an ignored column into a type
+     * error. Runs after camelizeKeys so that member names align with the
+     * camelCase column names models declare in ignoredColumns.
+     */
+    removeIgnoredColumns(dbSourceFile) {
+        const dbInterface = this.findDbExport(dbSourceFile, 'DB');
+        if (!dbInterface)
+            return dbSourceFile;
+        // the DB interface maps table names to table interfaces (e.g.
+        // `collars: Collars`), so it provides the table name each table
+        // interface corresponds to
+        const ignoredColumnsByInterfaceName = {};
+        dbInterface.members.forEach(member => {
+            if (!ts.isPropertySignature(member))
+                return;
+            if (!member.type || !ts.isTypeReferenceNode(member.type))
+                return;
+            if (!ts.isIdentifier(member.type.typeName))
+                return;
+            const tableName = ts.isIdentifier(member.name)
+                ? member.name.text
+                : ts.isStringLiteral(member.name)
+                    ? member.name.text
+                    : null;
+            if (!tableName)
+                return;
+            const ignoredColumns = this.ignoredColumnsForTable(tableName);
+            if (ignoredColumns.size)
+                ignoredColumnsByInterfaceName[member.type.typeName.text] = ignoredColumns;
+        });
+        if (!Object.keys(ignoredColumnsByInterfaceName).length)
+            return dbSourceFile;
+        // @ts-expect-error cannot lock this type down, though implementation is correct
+        const transformer = context => {
+            const visit = node => {
+                const interfaceNode = this.exportedInterfaceOrNull(node);
+                const ignoredColumns = interfaceNode
+                    ? ignoredColumnsByInterfaceName[interfaceNode.name.text]
+                    : undefined;
+                if (interfaceNode && ignoredColumns) {
+                    return f.updateInterfaceDeclaration(interfaceNode, interfaceNode.modifiers, interfaceNode.name, interfaceNode.typeParameters, interfaceNode.heritageClauses, interfaceNode.members.filter(member => !(ts.isPropertySignature(member) &&
+                        (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)) &&
+                        ignoredColumns.has(member.name.text))));
+                }
+                return ts.visitEachChild(node, visit, context);
+            };
+            return node => ts.visitNode(node, visit);
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
     /**
      * @internal
      *

package/dist/cjs/src/helpers/cli/generateMigration.js

@@ -1,6 +1,6 @@
 import * as path from 'node:path';
 import pluralize from 'pluralize-esm';
-import generateMigrationContent from '../cli/generateMigrationContent.js';
+import generateMigrationContent, { MIGRATION_TABLE_NAME_PLACEHOLDER, } from '../cli/generateMigrationContent.js';
 import primaryKeyType from '../db/primaryKeyType.js';
 import hyphenize from '../hyphenize.js';
 import migrationVersion from '../migrationVersion.js';
@@ -9,6 +9,18 @@ import dreamPath from '../path/dreamPath.js';
 import snakeify from '../snakeify.js';
 import generateStiMigrationContent from './generateStiMigrationContent.js';
 import writeGeneratedFile from './writeGeneratedFile.js';
+/**
+ * Equivalent to `migrationName.match(new RegExp(`${marker}(.+)$`))?.[1]`, but
+ * without a regex: CodeQL flags `.+` anchored to `$` as a polynomial-ReDoS
+ * shape, and a plain `indexOf`/`slice` does the same leftmost-match-to-end
+ * job with no backtracking risk.
+ */
+function tableNameFromSuffix(migrationName, marker) {
+    const markerIndex = migrationName.indexOf(marker);
+    if (markerIndex === -1)
+        return undefined;
+    return migrationName.slice(markerIndex + marker.length) || undefined;
+}
 export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete = false, }) {
     const migrationsBasePath = connectionName === 'default'
         ? path.join(dreamPath('db'), 'migrations')
@@ -33,12 +45,17 @@ export default async function generateMigration({ migrationName, columnsWithType
         });
     }
     else {
-        const tableName = migrationName.match(/-to-(.+)$/)?.[1];
+        const toTableName = tableNameFromSuffix(migrationName, '-to-');
+        const fromTableName = toTableName
+            ? undefined
+            : tableNameFromSuffix(migrationName, '-from-');
+        const tableName = toTableName || fromTableName;
         content = generateMigrationContent({
-            table: tableName ? pluralize(snakeify(tableName)) : '<table-name>',
+            table: tableName ? pluralize(snakeify(tableName)) : MIGRATION_TABLE_NAME_PLACEHOLDER,
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
             createOrAlter: 'alter',
+            alterDirection: fromTableName ? 'remove' : 'add',
         });
     }
     await writeGeneratedFile({

package/dist/cjs/src/helpers/cli/generateMigrationContent.js

@@ -2,11 +2,19 @@ import pluralize from 'pluralize-esm';
 import lookupModelByGlobalName from '../../dream-app/helpers/lookupModelByGlobalName.js';
 import Query from '../../dream/Query.js';
 import InvalidDecimalFieldPassedToGenerator from '../../errors/InvalidDecimalFieldPassedToGenerator.js';
+import NoColumnsToAlterMigration from '../../errors/NoColumnsToAlterMigration.js';
+import UnparseableMigrationColumn from '../../errors/UnparseableMigrationColumn.js';
 import camelize from '../camelize.js';
 import compact from '../compact.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
+// Sentinel table name used by generateMigration.ts when a standalone
+// migration name matches neither a `-to-<table>` nor `-from-<table>` suffix.
+// That path intentionally produces a stub the user is expected to hand-edit
+// (e.g. an index-only migration with no column operations at all), so it's
+// exempt from the "no valid columns" check below.
+export const MIGRATION_TABLE_NAME_PLACEHOLDER = '<table-name>';
 const STI_TYPE_COLUMN_NAME = 'type';
 // deleted_at is deliberately NOT in this list: the SoftDelete default scope's
 // `WHERE deleted_at IS NULL` is unselective on healthy tables, Dream internals
@@ -15,8 +23,9 @@ const STI_TYPE_COLUMN_NAME = 'type';
 // default. See spec/unit/cli/generateMigrationContent.spec.ts
 // ("deleted_at is deliberately NOT indexed") and the CHANGELOG.
 const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
-export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
+export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', alterDirection = 'add', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
+    const removingInUp = altering && alterDirection === 'remove';
     let requireCitextExtension = false;
     const checkConstraints = [];
     // When creating a new table, we automatically emit `created_at`,
@@ -65,7 +74,17 @@ export default function generateMigrationContent({ connectionName = 'default', t
         // when creating a migration for an STI child, we don't want to include notNull;
         // instead, we'll add a check constraint that uses the STI child class name
         const sqlAttributeType = getAttributeType(attributeType, descriptors);
-        if (attributeType === undefined || ['hasone', 'hasmany'].includes(processedAttrType))
+        if (attributeType === undefined) {
+            // In alter mode (both `-to-`/add and `-from-`/remove), a column whose
+            // type can't be resolved (e.g. a mistyped declaration with no `:type`
+            // segment) must not silently vanish from the generated migration —
+            // that's especially dangerous for `-from-` migrations, whose whole
+            // premise is describing removed columns so `down` can restore them.
+            if (altering)
+                throw new UnparseableMigrationColumn(attributeDeclaration);
+            return acc;
+        }
+        if (['hasone', 'hasmany'].includes(processedAttrType))
             return acc;
         if (attributeType === 'citext')
             requireCitextExtension = true;
@@ -169,6 +188,25 @@ export async function down(db: Kysely<any>): Promise<void> {
 }\
 `;
     }
+    // An alter migration (either `-to-`/add or `-from-`/remove) with no valid
+    // columns to add/drop would otherwise emit a bare `.alterTable(...).execute()`
+    // with no column operation at all, which Postgres rejects at migration-run
+    // time rather than generation time. Fail loudly here instead.
+    //
+    // This guard is scoped to the standalone `g:migration` `-to-`/`-from-` flow
+    // only (`stiChildClassName` is unset there). `g:sti-child` legitimately
+    // calls this function in alter mode with zero `columnsWithTypes` — a
+    // zero-attribute STI child is a documented use case (see `g:sti-child`'s
+    // help example in src/cli/index.ts), and `generateStiMigrationContent`
+    // handles the type-column/check-constraint machinery separately from the
+    // `columnDefs` this check inspects, so an empty `columnDefs` there is
+    // expected, not a sign of a mistyped/unparseable column list.
+    if (altering &&
+        columnDefs.length === 0 &&
+        table !== MIGRATION_TABLE_NAME_PLACEHOLDER &&
+        !stiChildClassName) {
+        throw new NoColumnsToAlterMigration(table, alterDirection);
+    }
     const citextExtension = requireCitextExtension
         ? `  await DreamMigrationHelpers.createExtension(db, 'citext')\n\n`
         : '';
@@ -179,7 +217,22 @@ export async function down(db: Kysely<any>): Promise<void> {
     const newlineIndent = '\n  ';
     const newlineDoubleIndent = '\n    ';
     const doubleNewlineIndent = '\n\n  ';
-    const columnDefLines = columnDefs.length ? newlineDoubleIndent + columnDefs.join(newlineDoubleIndent) : '';
+    // For a `-from-` migration (`alterDirection: 'remove'`), `down` re-adds the
+    // column(s) that `up` removed. The generator has no way to know the
+    // column's original default, so a non-optional (`.notNull()`) column with
+    // no default emitted here will fail at migration-run time against a table
+    // that already has rows. We can't fix that without a lot more heavy
+    // lifting (and the risk that comes with it), so flag it with a comment
+    // instead of silently generating a `down` that's likely to break.
+    const NO_KNOWN_DEFAULT_COMMENT = "// NOTE: the generator doesn't know this column's original default; this addColumn will fail against a table with existing rows unless you add a default by hand.";
+    const finalColumnDefs = removingInUp
+        ? columnDefs.map(def => def.includes('.notNull()') && !def.includes('.defaultTo(')
+            ? `${NO_KNOWN_DEFAULT_COMMENT}\n    ${def}`
+            : def)
+        : columnDefs;
+    const columnDefLines = finalColumnDefs.length
+        ? newlineDoubleIndent + finalColumnDefs.join(newlineDoubleIndent)
+        : '';
     const columnDropLines = columnDrops.length
         ? newlineDoubleIndent + columnDrops.join(newlineDoubleIndent) + newlineDoubleIndent
         : '';
@@ -190,21 +243,33 @@ export async function down(db: Kysely<any>): Promise<void> {
             newlineDoubleIndent +
             ".addColumn('updated_at', 'timestamp', col => col.notNull())" +
             (emitDeletedAtColumn ? newlineDoubleIndent + ".addColumn('deleted_at', 'timestamp')" : '');
+    // For `alterDirection: 'remove'` (a `-from-` migration), the enum *type*
+    // itself must never be created or dropped here, even when the column
+    // declaration includes inline enum values — enums are frequently reused
+    // across columns/tables, so `up` must drop only the column (no `dropType`)
+    // and `down` must re-add only the column (no `createType`), identical to
+    // referencing an existing enum by name with no values.
+    const enumCreateStatements = removingInUp ? '' : generateEnumStatements(columnsWithTypes);
+    const enumDropStatements = removingInUp ? '' : generateEnumDropStatements(columnsWithTypes);
+    const addColumnsBody = `${citextExtension}${enumCreateStatements}  await db.schema
+    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${timestampColumnLines}
+    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(doubleNewlineIndent)}${checkConstraints.join('')}`;
+    const removeColumnsBody = `  ${altering
+        ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
+        : `await db.schema.dropTable('${table}').execute()`}${enumDropStatements}`;
+    const upBody = removingInUp ? removeColumnsBody : addColumnsBody;
+    const downBody = removingInUp ? addColumnsBody : removeColumnsBody;
     return `\
 ${dreamDbImports.length ? `import { ${dreamDbImports.join(', ')} } from '@rvoh/dream/db'\n` : ''}import { ${kyselyImports.join(', ')} } from 'kysely'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function up(db: Kysely<any>): Promise<void> {
-${citextExtension}${generateEnumStatements(columnsWithTypes)}  await db.schema
-    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${timestampColumnLines}
-    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(doubleNewlineIndent)}${checkConstraints.join('')}
+${upBody}
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function down(db: Kysely<any>): Promise<void> {
-  ${altering
-        ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
-        : `await db.schema.dropTable('${table}').execute()`}${generateEnumDropStatements(columnsWithTypes)}
+${downBody}
 }\
 `;
 }

package/dist/cjs/src/helpers/cli/resolveIgnoredColumns.js

@@ -0,0 +1,198 @@
+import scopeArray from '../../decorators/field/sortable/helpers/scopeArray.js';
+import CannotIgnoreAssociationColumn from '../../errors/schema-builder/CannotIgnoreAssociationColumn.js';
+import CannotIgnoreEncryptedColumn from '../../errors/schema-builder/CannotIgnoreEncryptedColumn.js';
+import CannotIgnorePrimaryKey from '../../errors/schema-builder/CannotIgnorePrimaryKey.js';
+import CannotIgnoreSoftDeleteColumn from '../../errors/schema-builder/CannotIgnoreSoftDeleteColumn.js';
+import CannotIgnoreSortablePositionColumn from '../../errors/schema-builder/CannotIgnoreSortablePositionColumn.js';
+import CannotIgnoreSortableScopeColumn from '../../errors/schema-builder/CannotIgnoreSortableScopeColumn.js';
+import CannotIgnoreStiTypeColumn from '../../errors/schema-builder/CannotIgnoreStiTypeColumn.js';
+import ConflictingIgnoredColumns from '../../errors/schema-builder/ConflictingIgnoredColumns.js';
+import IgnoredColumnMustBeCamelCase from '../../errors/schema-builder/IgnoredColumnMustBeCamelCase.js';
+import camelize from '../camelize.js';
+import uniq from '../uniq.js';
+/**
+ * @internal
+ *
+ * Resolves the set of ignored columns for a table from the `ignoredColumns`
+ * declarations of every model backed by that table, validating the
+ * declarations along the way. Called while `sync` builds the generated types
+ * files (the declarations have no runtime behavior; see the `ignoredColumns`
+ * getter on Dream), so each of these guards fails the sync command loudly
+ * rather than surfacing as broken behavior at runtime:
+ *
+ * - ignored columns must be declared in camelCase, since generated column
+ *   names are camelized, so any other shape can never match a generated
+ *   column and would be silently inert
+ * - a model may never ignore its primary key
+ * - an STI model may never ignore the STI "type" column
+ * - a model may never ignore an @Sortable position field or a plain-column
+ *   @Sortable scope, the backing column of an @Encrypted property, or (on a
+ *   SoftDelete model) its deletedAtField — the framework reads and writes
+ *   those columns by name
+ * - models sharing a table must agree on their ignored columns, since there
+ *   is only one generated schema per table (STI children inherit the base
+ *   model's getter, so agreement is automatic unless a child overrides it)
+ * - no association anywhere in the app may name an ignored column as the
+ *   foreign key (or polymorphic type field) it reads and writes on this
+ *   table — a BelongsTo on a model backed by this table names a foreign key
+ *   on this table, and so does a HasMany/HasOne on any other model that
+ *   points at a model backed by this table
+ * - no association anywhere in the app may name an ignored column as its
+ *   primaryKeyOverride — the column the association's foreign key points
+ *   at, which lives on the associated model's table for a BelongsTo and on
+ *   the declaring model's own table for a HasMany/HasOne
+ *
+ * @param models - every model backed by the table
+ * @param tableName - the table whose ignored columns are being resolved
+ * @param allModels - every model in the app (on the table's connection);
+ *   required because associations declared on other models can name foreign
+ *   keys on this table
+ * @returns the set of column names to omit from the table's generated types
+ */
+export default function resolveIgnoredColumns(models, tableName, allModels) {
+    models.forEach(modelClass => {
+        const ignoredColumns = modelClass.prototype.ignoredColumns;
+        ignoredColumns.forEach(columnName => {
+            if (camelize(columnName) !== columnName)
+                throw new IgnoredColumnMustBeCamelCase(modelClass, columnName);
+        });
+        if (ignoredColumns.includes(modelClass.primaryKey))
+            throw new CannotIgnorePrimaryKey(modelClass);
+        if (ignoredColumns.includes('type') && (modelClass['isSTIBase'] || modelClass['isSTIChild']))
+            throw new CannotIgnoreStiTypeColumn(modelClass);
+        modelClass['sortableFields'].forEach(sortableFieldConfig => {
+            if (ignoredColumns.includes(sortableFieldConfig.positionField))
+                throw new CannotIgnoreSortablePositionColumn(modelClass, sortableFieldConfig.positionField);
+            // a Sortable scope entry names either a column or a BelongsTo
+            // association on the model (getColumnForSortableScope resolves columns
+            // first, then falls back to association metadata), so an ignored scope
+            // entry only breaks @Sortable when no association answers to the name
+            scopeArray(sortableFieldConfig.scope).forEach(scopeEntry => {
+                if (ignoredColumns.includes(scopeEntry) &&
+                    modelClass['associationMetadataMap']()[scopeEntry] === undefined)
+                    throw new CannotIgnoreSortableScopeColumn(modelClass, scopeEntry, sortableFieldConfig.positionField);
+            });
+        });
+        // the Encrypted decorator records each backing column it manages in
+        // explicitUnsafeParamColumns (which nothing else populates)
+        modelClass['explicitUnsafeParamColumns'].forEach(columnName => {
+            if (ignoredColumns.includes(columnName))
+                throw new CannotIgnoreEncryptedColumn(modelClass, columnName);
+        });
+        if (modelClass['softDelete']) {
+            const deletedAtField = modelClass.prototype['_deletedAtField'];
+            if (ignoredColumns.includes(deletedAtField))
+                throw new CannotIgnoreSoftDeleteColumn(modelClass, deletedAtField);
+        }
+    });
+    const distinctDeclarations = uniq(models.map(modelClass => JSON.stringify(uniq([...modelClass.prototype.ignoredColumns]).sort())));
+    if (distinctDeclarations.length > 1)
+        throw new ConflictingIgnoredColumns(tableName, models);
+    const ignoredColumns = new Set(models.flatMap(modelClass => [...modelClass.prototype.ignoredColumns]));
+    if (ignoredColumns.size)
+        guardAssociationColumns(ignoredColumns, tableName, allModels);
+    return ignoredColumns;
+}
+/**
+ * @internal
+ *
+ * fails the sync when an ignored column of the table is the foreign key (or
+ * polymorphic type field) that any association in the app reads and writes
+ * on this table, or the primaryKeyOverride column that any association's
+ * foreign key points at on this table. A BelongsTo association names a
+ * foreign key on the declaring model's own table and a primaryKeyOverride
+ * on the associated model's table; a HasMany/HasOne association names a
+ * foreign key on the associated model's table and a primaryKeyOverride on
+ * the declaring model's own table — so the load-bearing association may be
+ * declared on any model in the app, not just the models backed by this
+ * table.
+ */
+function guardAssociationColumns(ignoredColumns, tableName, allModels) {
+    for (const modelClass of allModels) {
+        for (const associationName of modelClass.associationNames) {
+            const associationMetaData = modelClass['associationMetadataMap']()[associationName];
+            if (associationMetaData === undefined)
+                continue;
+            // a through association names no foreign key of its own; the source
+            // association it travels through is guarded directly
+            if (associationMetaData.through)
+                continue;
+            // unlike foreignKey(), primaryKeyOverride is a plain string on the
+            // association statement, so it can be guarded without consulting the
+            // generated schema — before the foreignKey-specific short-circuits below
+            const primaryKeyOverride = associationMetaData.primaryKeyOverride;
+            if (primaryKeyOverride &&
+                ignoredColumns.has(primaryKeyOverride) &&
+                primaryKeyOverrideTableForAssociationMatches(associationMetaData, modelClass, tableName))
+                throw new CannotIgnoreAssociationColumn(tableName, primaryKeyOverride, modelClass, associationMetaData, 'primary key override');
+            if (!foreignKeyTableForAssociationMatches(associationMetaData, modelClass, tableName))
+                continue;
+            // NOTE
+            // this try-catch mirrors getAssociationData in ASTConnectionBuilder:
+            // computing foreignKey() introspects columns via the generated schema
+            // file, so it may throw — on the first sync pass because the schema
+            // file has not been regenerated yet, and on the second pass because
+            // the regenerated schema omits the ignored column. So in orderings
+            // where foreignKey() throws on the first pass, it throws on the second
+            // pass too, and these guards never see the association's foreign key;
+            // the InvalidComputedForeignKey / ExplicitForeignKeyRequired errors
+            // swallowed here resurface at runtime as the backstop.
+            let foreignKey = null;
+            let foreignKeyTypeColumn = null;
+            try {
+                foreignKey = associationMetaData.foreignKey();
+                foreignKeyTypeColumn = associationMetaData.polymorphic
+                    ? associationMetaData.foreignKeyTypeField()
+                    : null;
+            }
+            catch {
+                continue;
+            }
+            if (ignoredColumns.has(foreignKey))
+                throw new CannotIgnoreAssociationColumn(tableName, foreignKey, modelClass, associationMetaData, 'foreign key');
+            if (foreignKeyTypeColumn && ignoredColumns.has(foreignKeyTypeColumn))
+                throw new CannotIgnoreAssociationColumn(tableName, foreignKeyTypeColumn, modelClass, associationMetaData, 'polymorphic type field');
+        }
+    }
+}
+/**
+ * @internal
+ *
+ * returns whether the given association's foreign key physically lives on
+ * the given table: on the declaring model's own table for a BelongsTo, and
+ * on the associated model's table for a HasMany/HasOne
+ */
+function foreignKeyTableForAssociationMatches(associationMetaData, modelClass, tableName) {
+    if (associationMetaData.type === 'BelongsTo')
+        return modelClass.table === tableName;
+    const dreamClassOrClasses = associationMetaData.modelCB();
+    // a missing associated class raises FailedToIdentifyAssociation while the
+    // builder gathers association data; it is not this guard's concern
+    if (!dreamClassOrClasses)
+        return false;
+    return Array.isArray(dreamClassOrClasses)
+        ? dreamClassOrClasses.some(dreamClass => dreamClass.table === tableName)
+        : dreamClassOrClasses.table === tableName;
+}
+/**
+ * @internal
+ *
+ * returns whether the given association's primaryKeyOverride column
+ * physically lives on the given table — the opposite side from the foreign
+ * key (see associationPrimaryKeyAccessors in
+ * decorators/field/association/shared.ts): on the associated model's table
+ * for a BelongsTo, and on the declaring model's own table for a
+ * HasMany/HasOne
+ */
+function primaryKeyOverrideTableForAssociationMatches(associationMetaData, modelClass, tableName) {
+    if (associationMetaData.type !== 'BelongsTo')
+        return modelClass.table === tableName;
+    const dreamClassOrClasses = associationMetaData.modelCB();
+    // a missing associated class raises FailedToIdentifyAssociation while the
+    // builder gathers association data; it is not this guard's concern
+    if (!dreamClassOrClasses)
+        return false;
+    return Array.isArray(dreamClassOrClasses)
+        ? dreamClassOrClasses.some(dreamClass => dreamClass.table === tableName)
+        : dreamClassOrClasses.table === tableName;
+}

package/dist/esm/src/Dream.js

@@ -1461,6 +1461,12 @@ export default class Dream {
      * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.preload('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.preload(...).findEach(...)` avoids instantiating massive amounts of data at once
+     * 6. leftJoinPreload must enumerate every compiled column of every joined
+     * model, so unlike base-model reads, `preload`/`load`, and saves, it does
+     * not tolerate schema/image skew from an unplanned column drop during a
+     * rolling deploy; see {@link Query.leftJoinPreload} and the
+     * `ignoredColumns` getter for the two-deploy process that makes a
+     * planned drop safe.
      *
      * ```ts
      * const user = await User.leftJoinPreload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
@@ -2340,6 +2346,83 @@ export default class Dream {
     get table() {
         throw new DreamMissingRequiredOverride(this.constructor, 'table');
     }
+    /**
+     * Columns that Dream should behave as though they do not exist.
+     *
+     * Declaring a column ignored removes it from the generated types the next
+     * time `sync` runs: it is omitted from both the db types file (the Kysely
+     * `DB` interface) and the dream schema file, so it disappears from
+     * `columns()` and from every place that flows from `columns()` — select
+     * lists built for `preload`/`load` and `leftJoinPreload`, save hydration,
+     * attribute definition, and param safety. References to the column in
+     * application code become type errors, which is the point: they must be
+     * removed before the column can be dropped.
+     *
+     * This enables safely dropping a column under rolling deploys — the same
+     * problem Rails solves with `ignored_columns`. The safety requirement is
+     * that no image that can run against the post-drop schema names the
+     * column in any SQL it generates. To satisfy it: remove all application
+     * code that uses the column, declare it here, and run `sync`; then let
+     * the drop migration run only once no image lacking the declaration can
+     * run against the database — whether the migration ships in a later
+     * deploy of its own, or together with the declaration in a pipeline that
+     * runs migrations only after the new images have rolled out. Once the
+     * column is dropped, remove this declaration and resync.
+     *
+     * Precondition: as soon as an image built with this declaration runs,
+     * the column is never placed in INSERT column lists, so before that
+     * image can run, the column must be nullable or carry a database
+     * default — a live `NOT NULL` column without a default fails every
+     * create against the table.
+     *
+     * Dropping the column while an image that names it can still run leaves
+     * a window during which those containers (including a rolled-back image)
+     * fail with `42703 column does not exist` — `leftJoinPreload` in
+     * particular has no runtime tolerance for this, since it must enumerate
+     * aliased columns.
+     *
+     * This is a mechanism for the drop window, not for permanently hiding
+     * wide columns: the ignored column is still transferred from the
+     * database on every `RETURNING *` / `select *` until it is actually
+     * dropped.
+     *
+     * The declaration is read only while `sync` generates the types files; it
+     * has no runtime behavior of its own. A declared-but-not-synced model is
+     * therefore not yet protected — CI should verify that `sync` produces no
+     * diff. `sync` will fail loudly if a declared name is not camelCase
+     * (generated column names are camelized, so any other shape could never
+     * match and would be silently inert), if models sharing a table declare
+     * different ignored columns, or if a model attempts to ignore a column
+     * the framework itself reads and writes by name: its primary key, an STI
+     * model's `type` column, any association's foreign key, polymorphic type
+     * field, or `primaryKeyOverride` column, an `@Sortable` position field or
+     * plain-column `@Sortable` scope, an `@Encrypted` backing column, or a
+     * SoftDelete model's `deletedAt` column.
+     *
+     * Because an ignored column vanishes from `columns()`, runtime access via
+     * type escape hatches behaves exactly like any unknown attribute: reads
+     * return `undefined`, and writes assign a plain instance property that is
+     * never persisted.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   public override get ignoredColumns() {
+     *     return ['legacyEmail'] as const
+     *   }
+     * }
+     * ```
+     *
+     * NOTE: this getter is intentionally typed as `readonly string[]` rather
+     * than as a union of known column names: during the deploy that declares
+     * a column ignored, the regenerated types no longer contain the column,
+     * so a column-name-derived type would reject the very declaration that
+     * removed it.
+     *
+     * @returns The list of column names this model should ignore
+     */
+    get ignoredColumns() {
+        return [];
+    }
     /**
      * @internal
      *

package/dist/esm/src/cli/index.js

@@ -45,6 +45,8 @@ ${INDENT}    - timetz
 ${INDENT}    - timetz[]
 ${INDENT}    - integer
 ${INDENT}    - integer[]
+${INDENT}    - boolean
+${INDENT}    - boolean[]
 ${INDENT}
 ${INDENT}    - decimal:
 ${INDENT}    - decimal[]:
@@ -153,16 +155,17 @@ ${INDENT}  # Add columns to an existing table (suffix with -to-<table_name> for
 ${INDENT}  pnpm psy g:migration add-timezone-to-users timezone:string
 ${INDENT}  pnpm psy g:migration add-bio-to-users bio:text:optional avatar_url:string:optional
 ${INDENT}
-${INDENT}  # Remove columns (suffix with -from-<table_name>)
-${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts
+${INDENT}  # Remove columns (suffix with -from-<table_name>; columns are described with
+${INDENT}  # their types, same shorthand as -to-, so the rollback (down) can recreate them)
+${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts legacy_status:string
 ${INDENT}
 ${INDENT}  # General schema change (no table suffix — generates empty up/down methods)
 ${INDENT}  pnpm psy g:migration create-unique-index-on-invitations`)
             .argument('<migrationName>', `Kebab-case name describing the change. End with -to-<table_name> or -from-<table_name> to auto-generate an alterTable scaffold for that table.
 ${INDENT}
 ${INDENT}Examples:
-${INDENT}  add-phone-to-users          # scaffolds alterTable('users', ...)
-${INDENT}  remove-status-from-posts    # scaffolds alterTable('posts', ...)
+${INDENT}  add-phone-to-users phone:encrypted           # scaffolds alterTable('users', ...)
+${INDENT}  remove-status-from-posts status:string      # scaffolds alterTable('posts', ...)
 ${INDENT}  create-join-table-host-places  # empty migration (no table suffix match)`)
             .option('--connection-name <connectionName>', 'the database connection to use for this migration. Only needed for multi-database setups; defaults to "default"')
             .argument('[columnsWithTypes...]', columnsWithTypesDescriptionForMigration)