📚TypeORM 핵심 개념 정리

1. Migration의 개념

• Migration은 DB 스키마 변경 내역을 코드로 관리하는 방법.
• 장점:
  • 스키마 변경 기록이 남아 협업/배포 시 일관성 유지.
  • 로컬, 스테이징, 프로덕션에 동일하게 반영 가능.
• 구성:
  • up 메서드 → 변경 적용
  • down 메서드 → 변경 롤백

---

2. Migration 생성 방식 2가지

① 자동 생성 (migration:generate)

• 엔티티(Entity) 변경사항을 DB 스키마와 비교하여 자동으로 SQL 생성.

npm run typeorm migration:generate -- -d src/config/migration.config src/database/migrations/migration-name

• 장점: 편함. 엔티티 변경만 하면 됨.
• 단점:
  • Enum value 추가, View 변경 등은 감지 불가.
  • 설정된 dataSource 파일(-d 옵션) 필요.

② 수동 생성 (migration:create)

• 빈 마이그레이션 파일을 생성하고, SQL 직접 작성.
   

npm run migration:create --filename="update_<fileName>"

npm run typeorm migration:create src/modules/database/migrations/migration-name

 

• 장점: 자동 감지 불가한 변경(ENUM 추가, INDEX 수정 등) 가능.
• 단점: SQL 직접 작성해야 함.

---

3. TypeORM CLI 사용 포인트

• -d <path> → DataSource 설정 파일 경로 지정.
• DataSource는 DB 연결 정보, 엔티티, 마이그레이션 경로 등을 정의한 파일.
• NestJS에서는 TypeOrmModule.forRootAsync 방식과 별개로 CLI용 data-source.ts를 따로 두는 경우 많음.

---

4. 실제 시나리오 예시

(1) Entity 변경 → 자동 마이그레이션

 

# Entity 수정 후
npm run typeorm migration:generate -- -d src/config/migration.config src/database/migrations/add-user-table

(2) 자동 감지 불가 변경 → 수동 마이그레이션

 

npm run typeorm migration:create src/modules/database/migrations/update-user-table

 

// update-user.ts
import { MigrationInterface, QueryRunner } from "typeorm";

export class UpdateUser1691762712345 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`
      ALTER TYPE user_type_enum ADD VALUE 'admin';
    `);
  }
  public async down(queryRunner: QueryRunner): Promise<void> {
    // 롤백 로직
    `DROP TYPE "public"."user_type_enum"`,
  }
}

---

5. 마이그레이션 실행

 

# 최신 마이그레이션 적용
npm run typeorm migration:run -- -d src/config/migration.config

# 롤백 (최근 실행된 마이그레이션 취소)
npm run typeorm migration:revert -- -d src/config/migration.config

---

6. Best Practice

• 자동 + 수동 혼합 사용:
  • 일반 스키마 변경 → migration:generate
  • 복잡한 SQL, enum 변경 → migration:create
• 항상 **버전 관리(Git)**에 마이그레이션 파일 포함.
• 배포 전 로컬/스테이징 환경에서 migration:run 테스트.

<참고>

package.json