@rvoh/dream 2.20.0 → 2.21.1

package/dist/cjs/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)

package/dist/cjs/src/errors/NoColumnsToAlterMigration.js

@@ -0,0 +1,17 @@
+export default class NoColumnsToAlterMigration extends Error {
+    table;
+    alterDirection;
+    constructor(table, alterDirection) {
+        super();
+        this.table = table;
+        this.alterDirection = alterDirection;
+    }
+    get message() {
+        return `
+no valid columns to ${this.alterDirection === 'remove' ? 'drop from' : 'add to'} table '${this.table}' in this alter migration.
+
+Pass at least one column declaration with a resolvable type, e.g.:
+  name:string
+    `;
+    }
+}

package/dist/cjs/src/errors/UnparseableMigrationColumn.js

@@ -0,0 +1,16 @@
+export default class UnparseableMigrationColumn extends Error {
+    declaration;
+    constructor(declaration) {
+        super();
+        this.declaration = declaration;
+    }
+    get message() {
+        return `
+could not determine a column type for the following migration column declaration:
+  ${this.declaration}
+
+Make sure the column includes a type, e.g.:
+  ${this.declaration.split(':')[0]}:string
+    `;
+    }
+}

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/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)

package/dist/esm/src/errors/NoColumnsToAlterMigration.js

@@ -0,0 +1,17 @@
+export default class NoColumnsToAlterMigration extends Error {
+    table;
+    alterDirection;
+    constructor(table, alterDirection) {
+        super();
+        this.table = table;
+        this.alterDirection = alterDirection;
+    }
+    get message() {
+        return `
+no valid columns to ${this.alterDirection === 'remove' ? 'drop from' : 'add to'} table '${this.table}' in this alter migration.
+
+Pass at least one column declaration with a resolvable type, e.g.:
+  name:string
+    `;
+    }
+}

package/dist/esm/src/errors/UnparseableMigrationColumn.js

@@ -0,0 +1,16 @@
+export default class UnparseableMigrationColumn extends Error {
+    declaration;
+    constructor(declaration) {
+        super();
+        this.declaration = declaration;
+    }
+    get message() {
+        return `
+could not determine a column type for the following migration column declaration:
+  ${this.declaration}
+
+Make sure the column includes a type, e.g.:
+  ${this.declaration.split(':')[0]}:string
+    `;
+    }
+}

package/dist/esm/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/esm/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/types/src/cli/index.d.ts

@@ -14,7 +14,7 @@ export type SpawnOptions = Omit<NodeSpawnOptions, 'shell'> & {
     args?: string[];
 };
 export declare const CLI_INDENT = "                  ";
-export declare const baseColumnsWithTypesDescription = "space separated snake-case properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
+export declare const baseColumnsWithTypesDescription = "space separated snake-case properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                      - boolean\n                      - boolean[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
 export declare const columnsWithTypesDescriptionForStiChild: string;
 export default class DreamCLI {
     /**

package/dist/types/src/errors/NoColumnsToAlterMigration.d.ts

@@ -0,0 +1,6 @@
+export default class NoColumnsToAlterMigration extends Error {
+    table: string;
+    alterDirection: 'add' | 'remove';
+    constructor(table: string, alterDirection: 'add' | 'remove');
+    get message(): string;
+}

package/dist/types/src/errors/UnparseableMigrationColumn.d.ts

@@ -0,0 +1,5 @@
+export default class UnparseableMigrationColumn extends Error {
+    declaration: string;
+    constructor(declaration: string);
+    get message(): string;
+}

package/dist/types/src/helpers/cli/generateMigrationContent.d.ts

@@ -1,10 +1,20 @@
 import { LegacyCompatiblePrimaryKeyType } from '../../types/db.js';
-export default function generateMigrationContent({ connectionName, table, columnsWithTypes, primaryKeyType, createOrAlter, stiChildClassName, softDelete, }?: {
+export declare const MIGRATION_TABLE_NAME_PLACEHOLDER = "<table-name>";
+export default function generateMigrationContent({ connectionName, table, columnsWithTypes, primaryKeyType, createOrAlter, alterDirection, stiChildClassName, softDelete, }?: {
     connectionName?: string;
     table?: string | undefined;
     columnsWithTypes?: string[] | undefined;
     primaryKeyType?: LegacyCompatiblePrimaryKeyType | undefined;
     createOrAlter?: 'create' | 'alter' | undefined;
+    /**
+     * Only meaningful when `createOrAlter: 'alter'`. `'add'` (the default,
+     * matching a `-to-<table>`-suffixed migration name) emits column additions
+     * in `up` and the matching drops in `down`. `'remove'` (matching a
+     * `-from-<table>`-suffixed migration name) inverts this: `up` drops the
+     * named columns and `down` re-adds them with their declared types, so
+     * `down` is the rollback that restores what `up` removed.
+     */
+    alterDirection?: 'add' | 'remove' | undefined;
     stiChildClassName?: string | undefined;
     /**
      * When true (and creating a new table), auto-emits a nullable `deleted_at`