1---
2title: Use Database Migrations
3impact: HIGH
4impactDescription: Enables safe, repeatable database schema changes
5tags: database, migrations, typeorm, schema
6---
7 
8## Use Database Migrations
9 
10Never use `synchronize: true` in production. Use migrations for all schema changes. Migrations provide version control for your database, enable safe rollbacks, and ensure consistency across all environments.
11 
12**Incorrect (using synchronize or manual SQL):**
13 
14```typescript
15// Use synchronize in production
16TypeOrmModule.forRoot({
17  type: 'postgres',
18  synchronize: true, // DANGEROUS in production!
19  // Can drop columns, tables, or data
20});
21 
22// Manual SQL in production
23@Injectable()
24export class DatabaseService {
25  async addColumn(): Promise<void> {
26    await this.dataSource.query('ALTER TABLE users ADD COLUMN age INT');
27    // No version control, no rollback, inconsistent across envs
28  }
29}
30 
31// Modify entities without migration
32@Entity()
33export class User {
34  @Column()
35  email: string;
36 
37  @Column() // Added without migration
38  newField: string; // Will crash in production if synchronize is false
39}
40```
41 
42**Correct (use migrations for all schema changes):**
43 
44```typescript
45// Configure TypeORM for migrations
46// data-source.ts
47export const dataSource = new DataSource({
48  type: 'postgres',
49  host: process.env.DB_HOST,
50  port: parseInt(process.env.DB_PORT),
51  username: process.env.DB_USERNAME,
52  password: process.env.DB_PASSWORD,
53  database: process.env.DB_NAME,
54  entities: ['dist/**/*.entity.js'],
55  migrations: ['dist/migrations/*.js'],
56  synchronize: false, // Always false in production
57  migrationsRun: true, // Run migrations on startup
58});
59 
60// app.module.ts
61TypeOrmModule.forRootAsync({
62  inject: [ConfigService],
63  useFactory: (config: ConfigService) => ({
64    type: 'postgres',
65    host: config.get('DB_HOST'),
66    synchronize: config.get('NODE_ENV') === 'development', // Only in dev
67    migrations: ['dist/migrations/*.js'],
68    migrationsRun: true,
69  }),
70});
71 
72// migrations/1705312800000-AddUserAge.ts
73import { MigrationInterface, QueryRunner } from 'typeorm';
74 
75export class AddUserAge1705312800000 implements MigrationInterface {
76  name = 'AddUserAge1705312800000';
77 
78  public async up(queryRunner: QueryRunner): Promise<void> {
79    // Add column with default to handle existing rows
80    await queryRunner.query(`
81      ALTER TABLE "users" ADD "age" integer DEFAULT 0
82    `);
83 
84    // Add index for frequently queried columns
85    await queryRunner.query(`
86      CREATE INDEX "IDX_users_age" ON "users" ("age")
87    `);
88  }
89 
90  public async down(queryRunner: QueryRunner): Promise<void> {
91    // Always implement down for rollback
92    await queryRunner.query(`DROP INDEX "IDX_users_age"`);
93    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "age"`);
94  }
95}
96 
97// Safe column rename (two-step)
98export class RenameNameToFullName1705312900000 implements MigrationInterface {
99  public async up(queryRunner: QueryRunner): Promise<void> {
100    // Step 1: Add new column
101    await queryRunner.query(`
102      ALTER TABLE "users" ADD "full_name" varchar(255)
103    `);
104 
105    // Step 2: Copy data
106    await queryRunner.query(`
107      UPDATE "users" SET "full_name" = "name"
108    `);
109 
110    // Step 3: Add NOT NULL constraint
111    await queryRunner.query(`
112      ALTER TABLE "users" ALTER COLUMN "full_name" SET NOT NULL
113    `);
114 
115    // Step 4: Drop old column (after verifying app works)
116    await queryRunner.query(`
117      ALTER TABLE "users" DROP COLUMN "name"
118    `);
119  }
120 
121  public async down(queryRunner: QueryRunner): Promise<void> {
122    await queryRunner.query(`ALTER TABLE "users" ADD "name" varchar(255)`);
123    await queryRunner.query(`UPDATE "users" SET "name" = "full_name"`);
124    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "full_name"`);
125  }
126}
127```
128 
129Reference: [TypeORM Migrations](https://typeorm.io/migrations)
130