typeorm-migrations/README.md

@lilith/typeorm-migrations

Migration utilities and CLI for TypeORM.

Features

• Migration Runner: Run and revert migrations programmatically
• Migration Generator: Generate migration files from templates
• CLI Tool: Command-line interface for migrations
• Status Tracking: Get pending and executed migrations

Installation

pnpm add @lilith/typeorm-migrations

Peer Dependencies

pnpm add typeorm

Quick Start

CLI Usage

# Run all pending migrations
npx typeorm-migrate run

# Revert last migration
npx typeorm-migrate revert

# Show pending migrations
npx typeorm-migrate pending

# Generate new migration
npx typeorm-migrate generate AddUserTable

Programmatic Usage

import { runMigrations, revertMigration } from '@lilith/typeorm-migrations';
import { dataSource } from './data-source';

// Run all pending migrations
const results = await runMigrations(dataSource);
console.log(`Ran ${results.length} migrations`);

// Revert last migration
await revertMigration(dataSource);

API Reference

runMigrations

Run all pending migrations:

import { runMigrations } from '@lilith/typeorm-migrations';

const results = await runMigrations(dataSource, {
  transaction: 'all', // 'all' | 'each' | 'none'
  fake: false,        // Mark as run without executing
});

for (const result of results) {
  console.log(`Ran: ${result.name} (${result.timestamp})`);
}

revertMigration

Revert the last executed migration:

import { revertMigration } from '@lilith/typeorm-migrations';

const result = await revertMigration(dataSource, {
  transaction: 'all',
  fake: false,
});

console.log(`Reverted: ${result.name}`);

getPendingMigrations

Get list of pending migrations:

import { getPendingMigrations } from '@lilith/typeorm-migrations';

const pending = await getPendingMigrations(dataSource);
console.log(`${pending.length} migrations pending`);

for (const migration of pending) {
  console.log(`- ${migration.name}`);
}

getExecutedMigrations

Get list of executed migrations:

import { getExecutedMigrations } from '@lilith/typeorm-migrations';

const executed = await getExecutedMigrations(dataSource);
console.log(`${executed.length} migrations executed`);

for (const migration of executed) {
  console.log(`- ${migration.name} (${migration.timestamp})`);
}

generateMigration

Generate a new migration file:

import { generateMigration } from '@lilith/typeorm-migrations';

await generateMigration({
  name: 'AddUserTable',
  directory: './src/migrations',
  template: 'default', // 'default' | 'empty'
});

// Creates: ./src/migrations/1234567890123-AddUserTable.ts

generateTimestamp

Generate a timestamp for migration naming:

import { generateTimestamp } from '@lilith/typeorm-migrations';

const timestamp = generateTimestamp();
// '1704067200000'

toClassName

Convert migration name to class name:

import { toClassName } from '@lilith/typeorm-migrations';

const className = toClassName('add-user-table');
// 'AddUserTable'

listMigrationFiles

List migration files in a directory:

import { listMigrationFiles } from '@lilith/typeorm-migrations';

const files = await listMigrationFiles('./src/migrations');
// ['1704067200000-CreateUsers.ts', '1704067201000-AddUserEmail.ts']

validateMigrationName

Validate a migration name:

import { validateMigrationName } from '@lilith/typeorm-migrations';

validateMigrationName('AddUserTable');    // OK
validateMigrationName('add user table');  // Throws error
validateMigrationName('123-invalid');     // Throws error

CLI Commands

typeorm-migrate run

Run pending migrations:

npx typeorm-migrate run [options]

Options:
  -c, --config <path>     Path to ormconfig/data-source file
  -t, --transaction <mode> Transaction mode: all|each|none (default: all)
  --fake                  Mark migrations as run without executing
  --dry-run               Show migrations that would run without executing

typeorm-migrate revert

Revert last migration:

npx typeorm-migrate revert [options]

Options:
  -c, --config <path>     Path to ormconfig/data-source file
  -t, --transaction <mode> Transaction mode: all|each|none (default: all)
  --fake                  Mark as reverted without executing

typeorm-migrate pending

Show pending migrations:

npx typeorm-migrate pending [options]

Options:
  -c, --config <path>  Path to ormconfig/data-source file

typeorm-migrate generate

Generate new migration:

npx typeorm-migrate generate <name> [options]

Arguments:
  name                  Migration name (PascalCase recommended)

Options:
  -d, --dir <path>      Output directory (default: ./src/migrations)
  -t, --template <type> Template type: default|empty (default: default)

Types

interface MigrationResult {
  name: string;
  timestamp: number;
  instance?: MigrationInterface;
}

interface RunMigrationsOptions {
  transaction?: 'all' | 'each' | 'none';
  fake?: boolean;
}

interface GenerateMigrationOptions {
  name: string;
  directory?: string;
  template?: 'default' | 'empty';
}

Migration Template

Generated migrations follow this template:

import { MigrationInterface, QueryRunner } from 'typeorm';

export class AddUserTable1704067200000 implements MigrationInterface {
  name = 'AddUserTable1704067200000';

  public async up(queryRunner: QueryRunner): Promise<void> {
    // Add your migration code here
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    // Add your rollback code here
  }
}

License

MIT