TypeORM: synchronize 대신 migration

• 작성자: J045_김영호

---

Migration과 Synchronize

synchronize와 migration

TypeORM을 DB와 연결시키기 위해서는 DataSourceOption을 작성해야한다. 이때, DB의 Table과 Entity들을 연동시키기 위해 우리는 옵션에 synchronize: true을 추가하거나, migration을 수행하여야 한다.

여기서 synchronize는 어플리케이션이 실행될 때마다 데이터베이스 스키마를 동적으로 생성해주는 것을 의미한다. 다시 말해 Entity를 이용하여 항상 Table을 생성해준다는 뜻이다. 다만, 해당 옵션은 Data 손실 가능성이 있기 때문에 production 레벨에서는 사용해서는 안되며, 따라서 개발, 혹은 디버깅 목적으로 사용할 것을 권장한다.

synchronize 옵션은 왜 위험한가?

synchronize 옵션은 Entity와 설정을 동일하게 하기 위해 단순히 Column을 ADD/DROP 하는 형식으로 테이블을 변형한다. 그렇기에 만약 특정 Entity의 이름이 A에서 B로 바뀌었다면, sync 옵션이 켜진 경우 A Column을 Drop시키고, B Column을 Add하는 식으로 작업을 하기에 데이터가 소실되는 상황이 발생한다. 이러한 현상을 Entity 명이 바뀌어도 동일하게 생긴다. (이 상황은 심지어 Table 자체를 DROP 시키고 CREATE를 수행한다. 더 위험해졌다.)

우리는 해당 옵션을 DataSource 객체를 초기화하는 과정에서 옵션의 일부로 사용한다. 그렇다면, synchronize 옵션이 활성화되었을 때 어떤 동작을 하는지 살펴보는 것이 좋을 것이다. 이를 위해 TypeORM의 깃허브 레포지토리를 살펴보면, /src/data-source/DataSource.ts 에 DataSource 클래스가 정의되어있으며, 이 중 synchronize 옵션과 관련된 부분은 initialize() 메서드에서 해당 옵션이 켜져있을 경우 synchronize() 를 실행시키는 부분이다. initialize와 synchronize 메서드의 명세는 다음과 같다.

/**
 * Performs connection to the database.
 * This method should be called once on application bootstrap.
 * This method not necessarily creates database connection (depend on database type),
 * but it also can setup a connection pool with database to use.
 */
async initialize(): Promise<this> {
    if (this.isInitialized)
        throw new CannotConnectAlreadyConnectedError(this.name)

    // connect to the database via its driver
    await this.driver.connect()

    // connect to the cache-specific database if cache is enabled
    if (this.queryResultCache) await this.queryResultCache.connect()

    // set connected status for the current connection
    ObjectUtils.assign(this, { isInitialized: true })

    try {
        // build all metadatas registered in the current connection
        await this.buildMetadatas()

        await this.driver.afterConnect()

        // if option is set - drop schema once connection is done
        if (this.options.dropSchema) await this.dropDatabase()

        // if option is set - automatically synchronize a schema
        if (this.options.migrationsRun)
            await this.runMigrations({
                transaction: this.options.migrationsTransactionMode,
            })

        // if option is set - automatically synchronize a schema
        if (this.options.synchronize) await this.synchronize()
    } catch (error) {
        // if for some reason build metadata fail (for example validation error during entity metadata check)
        // connection needs to be closed
        await this.close()
        throw error
    }

    return this
}

async synchronize(dropBeforeSync: boolean = false): Promise<void> {
    if (!this.isInitialized)
        throw new CannotExecuteNotConnectedError(this.name)

    if (dropBeforeSync) await this.dropDatabase()

    const schemaBuilder = this.driver.createSchemaBuilder()
    await schemaBuilder.build()
}

명세 상에서 initialize 메서드는 synchronize에게 어떠한 매개변수도 전달하지 않으므로 synchronize의 dropDatabase는 무시해도 될 것이다. 그렇다면 실질적으로 Entity를 DB와 연동하는 역할을 수행하는 것은 schemaBuilder일 것이다.

여기서 driver는 DriverFactory 객체로부터 create 메서드를 실행함으로써 생성되며(this.driver = new DriverFactory().create(this) - 생성자 함수, 일부 생략), DriverFactory는 DataSource의 type 옵션에 따라 생성하고, 대부분은 RDBMS들의 경우 createSchemaBuilder로부터 RdbmsSchemaBuilder가 생성된다.

추적을 거듭한 결과, 우리는 schemaBuilder.build()의 명세를 찾아낼 수 있었고, 이는 하단과 같다.

/**
 * Creates complete schemas for the given entity metadatas.
 */
async build(): Promise<void> {
    this.queryRunner = this.connection.createQueryRunner()

    // this.connection.driver.database || this.currentDatabase;
    this.currentDatabase = this.connection.driver.database
    this.currentSchema = this.connection.driver.schema

    // CockroachDB implements asynchronous schema sync operations which can not been executed in transaction.
    // E.g. if you try to DROP column and ADD it again in the same transaction, crdb throws error.
    // In Spanner queries against the INFORMATION_SCHEMA can be used in a read-only transaction,
    // but not in a read-write transaction.
    const isUsingTransactions =
        !(this.connection.driver.options.type === "cockroachdb") &&
        !(this.connection.driver.options.type === "spanner") &&
        this.connection.options.migrationsTransactionMode !== "none"

    await this.queryRunner.beforeMigration()

    if (isUsingTransactions) {
        await this.queryRunner.startTransaction()
    }

    try {
        await this.createMetadataTableIfNecessary(this.queryRunner)
        // Flush the queryrunner table & view cache
        const tablePaths = this.entityToSyncMetadatas.map((metadata) =>
            this.getTablePath(metadata),
        )

        await this.queryRunner.getTables(tablePaths)
        await this.queryRunner.getViews([])

        await this.executeSchemaSyncOperationsInProperOrder()

        // if cache is enabled then perform cache-synchronization as well
        if (this.connection.queryResultCache)
            await this.connection.queryResultCache.synchronize(
                this.queryRunner,
            )

        if (isUsingTransactions) {
            await this.queryRunner.commitTransaction()
        }
    } catch (error) {
        try {
            // we throw original error even if rollback thrown an error
            if (isUsingTransactions) {
                await this.queryRunner.rollbackTransaction()
            }
        } catch (rollbackError) {}
        throw error
    } finally {
        await this.queryRunner.afterMigration()

        await this.queryRunner.release()
    }
}

위의 코드들 중에서 DB를 조작하는 것은 this.executeSchemaSyncOperationsInProperOrder() 이다. 이 메서드를 살펴보면, 일부 경우를 제외하고는 컬럼을 drop한 뒤 add를 수행하거나, table을 drop한 뒤 create하는 형식으로 동작한다.

/**
 * Executes schema sync operations in a proper order.
 * Order of operations matter here.
 */
protected async executeSchemaSyncOperationsInProperOrder(): Promise<void> {
    await this.dropOldViews()
    await this.dropOldForeignKeys()
    await this.dropOldIndices()
    await this.dropOldChecks()
    await this.dropOldExclusions()
    await this.dropCompositeUniqueConstraints()
    // await this.renameTables();
    await this.renameColumns()
    await this.createNewTables()
    await this.dropRemovedColumns()
    await this.addNewColumns()
    await this.updatePrimaryKeys()
    await this.updateExistColumns()
    await this.createNewIndices()
    await this.createNewChecks()
    await this.createNewExclusions()
    await this.createCompositeUniqueConstraints()
    await this.createForeignKeys()
    await this.createViews()
}

그렇다면 예외 케이스는 무엇인가? renameColumns의 경우, 오로지 Table에서 단 하나의 Column만이 변경된 경우에는 Rename으로 처리하며, 이러한 처리를 각 Table에 대해 수행하는 식으로 동작한다. 간단하게 파악하고자 할 경우 주석을 참고한다.

renameColumns의 주석 (세부 처리는 코드를 확인할 것.)

• Renames columns.
• Works if only one column per table was changed.
• Changes only column name. If something besides name was changed, these changes will be ignored.

따라서 Entity 내에서 여러 컬럼이 변경된 경우 Column을 Drop한 뒤 Add하는 형식으로 처리될 것이라 짐작할 수 있다.

메서드 명이 updateExistColumns여서 컬럼의 메타데이터만 변경될 것 같은 이 메서드는 changeColumns라는 QueryRunner의 메서드를 사용하는데, 해당 함수를 살펴보면 일부 조건의 경우 Drop 후 Add를 수행하는 것을 볼 수 있다. 이 외의 경우 ALTER ~ CHANGE COLUMN 형식으로 처리된다.

• Column의 타입이 변경되었음.

• Column의 length(혹은 size)가 변경됨. (ex. varchar(50)→varchar(60))

• 기존과 새 컬럼 둘 다 generatedType이 정의되어있지만, 둘의 generatedType이 서로 다름.

• generatedType이 VIRTUAL에서 undefined가 되거나, 그 역일 경우

  이렇게 synchronize를 사용하는 경우 데이터를 최대한 보존해주기 위해 안전장치를 최대한 마련하지만, 그럼에도 불구하고 Column 자체가 날아갔다가 추가되는 현상이 발생할 수도 있기 때문에, synchronize는 안전하지 않다고 하는 것이다.

  이에 반하여 migration의 경우 개발자가 직접 이전 Entity에서 변경된 Entity로 수정하기 위해 필요한 쿼리문을 직접 작성하기 때문에, 데이터 손실에서 그나마 안전하다고 할 수 있는 것이다.

Migration 해보기

마이그레이션 준비 - DataSourceOption 작성

마이그레이션을 하기 위해서는 어떤 폴더에 마이그레이션 정보가 담겨있고, 어떤 Table에 여태까지 실행해왔던 마이그레이션들에 대한 정보가 담겨있는지 정의해야 한다. 이러한 정보들은 DataSourceOption에서 작성할 수 있으며, 해당 옵션은 Nest.js의 경우 TypeOrmModule.forRoot()에서 작성하거나, 아니면 config 파일을 따로 작성하여 이를 이용할 수 있다. (보통은 ormconfig.ts로 쓴다.)

DataSourceOption에는 DBMS 타입, DB 접근 방법, 사용할 Entity, migrations, migrationsTableName을 정의하여 DB와 Entity와의 연동 및 마이그레이션 처리를 정의할 수 있다.

• migrations

  • 마이그레이션을 수행할 MigrationInterface 구현체 파일 목록.
  • 일반적으로 마이그레이션 파일들을 저장한 파일 경로를 저장한다.
  • ex. migrations: ['src/migrations/**/*.ts']

• migrationsTableName

  • 이미 마이그레이션에 사용한 MigrationInterface의 목록을 저장할 테이블 이름.
  • 미지정 시 migrations로 지정된다.
  • ex. migrationsTableName: "migrations"

  마이그레이션 처리 시 TypeORM은 DB에 반영하지 않은 (=Pending 상태인) MigrationInterface 구현체들을 추출하여 이들을 가장 오래된 것들부터 실행한다. 마이그레이션 과정은 모두 Transaction으로 처리되며, 따라서 도중에 실패한다고 한들 Table이 깨져버리는 불상사는 발생하지 않는다.

  이를 적용한 프로젝트의 ormconfig.ts는 다음과 같이 작성하였다. 주의할 점은, 해당 파일에서 export하는 DataSource는 반드시 단 한개만 존재하여야 하며, 반드시 존재하여야 한다.

import { join } from 'path';
import { DataSource, DataSourceOptions } from 'typeorm';
import * as dotenv from 'dotenv';

dotenv.config();
export const config: DataSourceOptions = {
  type: 'mysql',
  host: process.env.MYSQL_HOST,
  port: parseInt(process.env.MYSQL_PORT),
  username: process.env.MYSQL_USERNAME,
  password: process.env.MYSQL_PASSWORD,
  database: process.env.MYSQL_DATABASE,
  entities: [join(__dirname, '/**/*.entity{.ts,.js}')],
  migrationsRun: true,
  migrations: [process.env.NODE_ENV === 'develop' ? 'src/migrations/**/*.ts' : 'dist/migrations/**/*.js'],
  migrationsTableName: 'migrations',
  synchronize: process.env.NODE_ENV === 'develop',
};
export default new DataSource(config);

CLI를 통한 마이그레이션 수행

마이그레이션을 수동으로 수행하려면, typeorm-cli가 필요하다. 이를 따로 설치할 필요는 없고, TypeScript를 사용하는 경우 package.json에 script로 등록하여 사용하게 된다. (JS를 쓰는 경우 단순히 typeorm 설치 후 npx typeorm <param> 형식으로 사용한다.)

TypeORM의 CLI는 오로지 js 파일을 실행할 목적으로 작성되었기에, TypeScript 프로젝트에서는 이를 트랜스파일링할 도구가 필요하다. 그렇기에 ts-node를 설치한 뒤, package.json에 다음과 같이 스크립트를 추가하며, 추후 npx typeorm 이나 npm run typeorm 이라는 식으로 CLI를 사용한다.

// commonjs 프로젝트일 경우
"script": {
	// ...
	"typeorm": "typeorm-ts-node-commonjs"
}
// ESM 프로젝트일 경우
"script": {
	// ...
	"typeorm": "typeorm-ts-node-esm"
}

만약 npm 스크립트에게 넘겨야 할 파라미터가 있을 경우, --을 추가한다. 일반적으로 다음과 같이 명령을 수행한다.

# Case 1
npm run typeorm -- migration:run -d <dataSource File location>
# Case 2
npm run typeorm migration:run -- -d <dataSource File location>

실행 예제는 다음과 같다.

# 마이그레이션 관련 명령 =========================================
# 마이그레이션 실행
npm run typeorm -- migration:run -d <dataSource File location>
# 가장 최근에 실행된 migrationInterface 구현체의 실행을 취소
npm run typeorm -- migration:revert -d <dataSource File location>
# 마이그레이션 목록 출력 (반영 = [X], 미반영 = [ ])
npm run typeorm -- migration:show -d <dataSource File location>
# 마이그레이션 템플릿 생성
npm run typeorm -- migration:create <저장 디렉토리 경로>/<template 파일명>
# 마이그레이션 자동 생성
npm run typeorm -- migration:generate <저장 디렉토리 경로>/<template 파일명>

# 참고 ==========================================================
# synchronization 수행 (synchronize=true 시의 처리를 수동으로 실행, 주의 요구)
npm run typeorm -- schema:sync
# sync 요구 시 처리할 쿼리문 목록 확인 (가짜로 sync를 실행한다.)
npm run typeorm -- schema:log

migration:create와 migration:generate

위의 CLI 예제를 보면, migration:create는 마이그레이션 템플릿을 생성하며, migration:generate는 현재 Entity와 DB의 스키마를 서로 비교하여, 실행하여야할 쿼리문들을 생성하여 이를 마이그레이션으로 출력한다. 두 명령 모두 이름을 케밥 케이스로 이름을 지정해주면, 마이그레이션 파일 이름은 {TIME_STAMP}-{Kebap-case-name}.ts 형식으로 마이그레이션 파일을 생성하며, 구현체의 이름은 {camelCaseName}{TIME_STAMP} 형식으로 생성해준다.

하지만 내용물은 조금 다르다. migration:create의 경우 마이그레이션의 보일러 플레이트만을 생성하며, 내용물을 개발자가 직접 채우도록 요구한다. 아래 코드는 마이그레이션의 보일러 플레이트, 다시 말해 migration:create로 생성된 파일의 내용물이다.

 import { MigrationInterface, QueryRunner } from 'typeorm';

export class addThumbnailOnWorkspace1669037051304 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {}

  public async down(queryRunner: QueryRunner): Promise<void> {}
}

MigrationInterface는 구현체에게 up과 down을 구현할 것을 요구한다. 해당 메서드들에게는 DataSource를 이용하여 DB와 연결된 QueryRunner가 주입되며, 이를 이용하여 쿼리를 정의하면 된다.

• up

  • 마이그레이션 실행 시 처리할 쿼리를 정의한다.
  • migration:run 실행 시 처리할 쿼리를 작성한다.

• down

  • 마이그레이션을 취소하고자 할 때 실행할 쿼리를 정의한다.
  • migration:revert 실행 시 처리할 쿼리를 정의한다.

  하단의 코드는 Entity에 Column이 하나 추가됨에 따라 프로젝트에서 보일러 플레이트에 작성한 코드이다.

import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';

export class addThumbnailOnWorkspace1669037051304 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.addColumn(
      'workspace',
      new TableColumn({
        name: 'thumbnail',
        type: 'varchar',
        length: '2083',
        isNullable: true,
      }),
    );
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.dropColumn('workspace', 'thumbnail');
  }
}

이에 반해 migration:generate는 DB의 스키마와 현 Entity를 비교하여 쿼리가 이미 작성되어있는 마이그레이션 파일을 자동으로 생성해준다. 따라서 개발자가 직접 마이그레이션 코드를 작성할 필요가 없다. 다만 주의할 점은, 이 또한 synchronize와 비슷한 코드가 도출될 수 있기에 데이터 손실의 우려가 발생할 수 있으며, 따라서 generate된 파일의 쿼리문을 직접 확인해볼 필요가 있다.

마이그레이션 쿼리 작성 시

마이그레이션은 QueryRunner를 활용하므로, 작성 시에 이의 API를 어느정도 인지할 필요가 있다. 자세한 사항은 링크를 참조한다.

마이그레이션 트러블슈팅

• 마이그레이션을 시도하면 MODULE_NOT_FOUND 오류가 발생
  • 프로젝트 내부에서 모듈들을 모두 상대경로로 import 하였는지 확인.
  • 절대경로로 import 된 모듈이 있는 경우 위의 오류가 발생함.
  • https://stackoverflow.com/questions/66991600/typeorm-migration-error-cannot-find-module

---

참고자료

• https://typeorm.io/data-source-options
• https://www.reddit.com/r/typescript/comments/pp86s8/can_some_one_explain_to_me_migration_vs/
• https://github.com/typeorm/typeorm
• https://typeorm.io/using-cli
• https://github.com/typeorm/typeorm/blob/4ec04fa1205ec9587946869c56077dae5454a063/src/migration/MigrationExecutor.ts#L14