🗄️ Database
Migrations
Database migrations manage schema changes across environments in a controlled, versioned manner.
Overview
| ORM | Migration System | Directory |
|---|---|---|
| TypeORM | TypeORM migrations | packages/core/src/lib/database/migrations/ |
| MikroORM | MikroORM migrations | packages/core/src/lib/database/migrations/ |
| Knex | Knex migrations | packages/core/src/lib/database/knex-migrations/ |
TypeORM Migrations
Generate a Migration
# Auto-generate from entity changes
yarn typeorm migration:generate -n AddEmployeeSkillsColumnTypeORM compares the current entity definitions with the database schema and generates the necessary SQL.
Create an Empty Migration
# Create empty migration shell
yarn typeorm migration:create -n CustomMigrationMigration File Format
import { MigrationInterface, QueryRunner } from "typeorm";
export class AddEmployeeSkillsColumn1704067200000
implements MigrationInterface
{
name = "AddEmployeeSkillsColumn1704067200000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE "employee"
ADD COLUMN "skills" text
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE "employee"
DROP COLUMN "skills"
`);
}
}Running Migrations
# Run all pending migrations
yarn typeorm migration:run
# Revert the last migration
yarn typeorm migration:revert
# Show migration status
yarn typeorm migration:showDatabase-Specific Migrations
Migrations are organized by database type:
packages/core/src/lib/database/migrations/
├── postgres/ # PostgreSQL-specific migrations
├── mysql/ # MySQL-specific migrations
└── sqlite/ # SQLite-specific migrationsMikroORM Migrations
Generate a Migration
yarn mikro-orm migration:create --initial # First migration
yarn mikro-orm migration:create # Subsequent migrationsRunning Migrations
yarn mikro-orm migration:up # Run pending
yarn mikro-orm migration:down # Revert last
yarn mikro-orm migration:list # Show status
yarn mikro-orm migration:fresh # Drop all & re-run (dev only)Knex Migrations
Creating a Knex Migration
yarn knex migrate:make migration_nameKnex Migration Format
import { Knex } from "knex";
export async function up(knex: Knex): Promise<void> {
await knex.schema.createTable("custom_table", (table) => {
table.uuid("id").primary().defaultTo(knex.raw("uuid_generate_v4()"));
table.string("name").notNullable();
table.uuid("tenant_id").notNullable().references("tenant.id");
table.timestamps(true, true);
});
}
export async function down(knex: Knex): Promise<void> {
await knex.schema.dropTable("custom_table");
}Running Knex Migrations
yarn knex migrate:latest # Run all pending
yarn knex migrate:rollback # Rollback last batch
yarn knex migrate:status # Show statusMigration Best Practices
DO
- ✅ Always write both
upanddownmethods - ✅ Test migrations against all supported databases (PostgreSQL, MySQL, SQLite)
- ✅ Include
tenantIdcolumns and foreign keys for new tables - ✅ Use transactions for data migrations
- ✅ Name migrations descriptively with timestamps
DON'T
- ❌ Use
DB_SYNCHRONIZE=truein production - ❌ Modify existing migrations (create new ones instead)
- ❌ Delete migration files from version control
- ❌ Run production migrations without backup
Production Checklist
- ✅ Backup the database
- ✅ Run migrations in staging first
- ✅ Verify
migration:showstatus - ✅ Monitor migration execution time
- ✅ Test rollback procedure
Configuration
# Auto-synchronize (development only!)
DB_SYNCHRONIZE=false
# Migration logging
DB_LOGGING=schema,migrationRelated Pages
- Database Overview — general database info
- Seeding — demo data
- TypeORM Setup — TypeORM configuration