Sequelize TypeScript Migration LTS

Common errors

• Error: Model not found for table 'your_table_name'

  cause The migration tool cannot locate or parse your Sequelize TypeScript models, likely due to incorrect model loading or missing decorators.
  fix Ensure your `Sequelize` instance is configured with the correct `models` path, typically using `models: [path.join(__dirname, 'models')]`, and that all models have `@Table` and `@Column` decorators.

• TypeError: Cannot read properties of undefined (reading 'makeMigration')

  cause The `SequelizeTypescriptMigration` class was not imported correctly or the package was not properly installed, leading to `makeMigration` being called on an undefined object.
  fix Verify the installation with `npm i sequelize-typescript-migration-lts` and ensure the import statement is `import { SequelizeTypescriptMigration } from 'sequelize-typescript-migration-lts';`.

• Migration 'XXXXXXXXXXXXXX-your-migration-name.js' failed: ... (during db:migrate:undo)

  cause The generated `down` function in a migration script encountered an error, possibly due to incorrect SQL logic or issues with foreign key constraints order during rollback, as noted in the documentation.
  fix Inspect the failing `down` function in the generated migration file. Manually adjust the SQL or Sequelize queries to ensure proper reversal of changes, paying close attention to relational dependencies and data integrity.

Warnings

• breaking The package has specific compatibility requirements with `sequelize` versions. Use version `~2.0.0` of this package for `sequelize@~6.0.0`, and `~1.0.0` for `sequelize@~4.0.0`.
  Fix: Refer to the compatibility section in the package's documentation to ensure the correct version of `sequelize-typescript-migration-lts` is installed for your `sequelize` ORM version.
• gotcha The `undo` (down) action of generated migrations may sometimes fail, particularly due to the ordering of model relations. Manual modification of the generated migration file might be necessary to resolve these issues.
  Fix: Before applying `down` migrations in production or critical environments, review the generated `down` functions for complex relational changes and manually adjust the order of operations if necessary.
• gotcha This tool strictly supports models defined with `sequelize-typescript` decorators and does not work with plain `sequelize` models.
  Fix: Ensure all models intended for migration generation are defined using `sequelize-typescript` decorators (`@Table`, `@Column`, etc.) and are registered correctly with your `sequelize-typescript` instance.
• gotcha While the tool automates migration generation, it may not always produce perfect migration scripts for highly complex schema changes. Manual review and adjustments of the generated files are often prudent.
  Fix: Always review the generated migration files (both `up` and `down` functions) before applying them, especially for significant schema alterations, to catch any potential issues or inefficiencies.

Install

• npm install sequelize-typescript-migration-lts npm
• yarn add sequelize-typescript-migration-lts yarn
• pnpm add sequelize-typescript-migration-lts pnpm

Imports

• SequelizeTypescriptMigration
  wrong:

  const SequelizeTypescriptMigration = require('sequelize-typescript-migration-lts');

  correct:

  import { SequelizeTypescriptMigration } from 'sequelize-typescript-migration-lts';

  This is the primary class for generating migrations. The package primarily uses ESM imports.
• MakeMigrationOptions

  import type { MakeMigrationOptions } from 'sequelize-typescript-migration-lts';

  Type import for configuring the `makeMigration` method. Available since v3.x.

Quickstart

This example demonstrates how to programmatically generate a new database migration file using `SequelizeTypescriptMigration.makeMigration`. It sets up a Sequelize instance, specifies an output directory for the migration, and names the migration file. This code should be executed after defining your Sequelize TypeScript models.

import { join } from 'path';
import { Sequelize } from "sequelize-typescript";
import { SequelizeTypescriptMigration, MakeMigrationOptions } from "sequelize-typescript-migration-lts";

const sequelize = new Sequelize({
  dialect: 'sqlite',
  storage: './database.sqlite',
  models: [join(__dirname, 'models')], // Ensure your models are loaded
  logging: false,
});

// Define a sample model in models/CarBrand.ts
// import { Table, Column, Model, DataType, Default } from 'sequelize-typescript';
// @Table
// export class CarBrand extends Model<CarBrand> {
//   @Column
//   name: string;
//   @Default(true)
//   @Column(DataType.BOOLEAN)
//   isCertified: boolean;
// }

async function runMigration() {
  try {
    const options: MakeMigrationOptions = {
      outDir: join(__dirname, './migrations'),
      migrationName: 'initial-schema-setup',
      preview: false,
      isTs: true, // Generate TypeScript migration files
    };
    await SequelizeTypescriptMigration.makeMigration(sequelize, options);
    console.log('Migration generated successfully. Run `npx sequelize-cli db:migrate` to apply.');
  } catch (error) {
    console.error('Error generating migration:', error);
  }
}

// In a real application, you'd integrate this with your CLI or startup process.
// For demonstration, we directly call it.
// Make sure your Sequelize instance is initialized and models are defined before calling this.
// For a quick test, you might call `runMigration()` after defining models.
// e.g., runMigration();