sonamu 0.10.11 → 0.10.13

package/src/migration/migrator.ts

@@ -1,10 +1,10 @@
 import assert from "assert";
-import { mkdir, readdir, unlink, writeFile } from "fs/promises";
+import { mkdir, readdir, writeFile } from "fs/promises";
 import path from "path";
 
 import chalk from "chalk";
 import { type Knex } from "knex";
-import { group, sum, unique } from "radashi";
+import { group, unique } from "radashi";
 
 import { Sonamu } from "../api/sonamu";
 import { DB } from "../database/db";
@@ -18,10 +18,22 @@ import { Naite } from "../naite/naite";
 import { type GenMigrationCode, type MigrationSet } from "../types/types";
 import { isLocal, isTest } from "../utils/controller";
 import { exists } from "../utils/fs-utils";
+import { isObjectValue, isStringValue } from "../utils/runtime-value";
 import { generateAlterCode, generateCreateCode } from "./code-generation";
 import { getMigrationSetFromEntity } from "./migration-set";
 import { PostgreSQLSchemaReader } from "./postgresql-schema-reader";
-import { type ConnString, type MigrationCode, type MigrationStatus } from "./types";
+import { SlackConfirm } from "./slack-confirm";
+import {
+  type ConnString,
+  type MigrationAction,
+  type MigrationCode,
+  type MigrationConnectionMeta,
+  type MigrationConnectionStatus,
+  type MigrationProgressEvent,
+  type MigrationRunOptions,
+  type MigrationStatus,
+  type MigrationTarget,
+} from "./types";
 
 export type MigrationResult = {
   connKey: string;
@@ -29,10 +41,25 @@ export type MigrationResult = {
   applied: string[];
 }[];
 
+function padDatePart(number: number, size: number = 2): string {
+  return number.toString().padStart(size, "0");
+}
+
+export class MigrationTargetExecutionError extends Error {
+  constructor(
+    public readonly connKey: MigrationTarget | "shadow",
+    cause: unknown,
+  ) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = "MigrationTargetExecutionError";
+  }
+}
+
 // 마이그레이션 상태 조회 시 DB 연결 확인 타임아웃(ms).
 // createKnexInstance의 커넥션 획득 타임아웃(30초)에 status/list/currentVersion이
 // 각각 걸리면 CLI/UI가 최대 수십 초 hang한다. 정상 응답은 수백 ms이므로 5초면 충분하다.
 const MIGRATION_CONN_TIMEOUT_MS = 5000;
+const LOCAL_DB_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1"]);
 
 /**
  * 주어진 Promise가 ms 안에 완료되지 않으면 onTimeout 에러로 reject한다.
@@ -54,24 +81,35 @@ function withTimeout<T>(promise: Promise<T>, ms: number, onTimeout: () => Error)
   });
 }
 
+/**
+ * Note 2026-08-26, 병준
+ * 이 클래스에서 deprecated 붙어있는 친구들은 현 CLI를 위한 하위 호환이니,
+ * CLI 리팩토링 시점에서 제거해주셔도 무방합니다.
+ */
 export class Migrator {
-  private isMissingMigrationTableError(error: unknown): boolean {
-    if (typeof error !== "object" || error === null) {
+  private isMissingMigrationTableError<Value>(error: Value): boolean {
+    if (!isObjectValue(error) || error === null) {
       return false;
     }
 
-    const maybePostgresError = error as { code?: unknown; message?: unknown };
+    const maybePostgresError =
+      /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ error as {
+        code?: unknown;
+        message?: unknown;
+      };
     return (
       maybePostgresError.code === "42P01" &&
-      typeof maybePostgresError.message === "string" &&
+      isStringValue(maybePostgresError.message) &&
       maybePostgresError.message.includes("knex_migrations")
     );
   }
 
-  private getMigrationTargetKeys(): (keyof SonamuDBConfig)[] {
-    const connKeys = Object.keys(Sonamu.dbConfig).filter(
-      (key) => !key.endsWith("_readonly"),
-    ) as (keyof SonamuDBConfig)[];
+  /** 현재 실행 환경에서 허용된 마이그레이션 대상 키를 반환합니다. */
+  getMigrationTargetKeys(): MigrationTarget[] {
+    const connKeys =
+      /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ Object.keys(
+        Sonamu.dbConfig,
+      ).filter((key) => !key.endsWith("_readonly")) as (keyof SonamuDBConfig)[];
 
     if (isLocal()) {
       return connKeys;
@@ -84,24 +122,143 @@ export class Migrator {
   private async runMigrationsSequentially(
     conns: { connKey: keyof SonamuDBConfig; knex: Knex }[],
     action: "apply" | "rollback",
+    options?: MigrationRunOptions,
   ): Promise<MigrationResult> {
     const results: MigrationResult = [];
 
     for (const { connKey, knex } of conns) {
-      const [batchNo, applied] =
-        action === "apply" ? await knex.migrate.latest() : await knex.migrate.rollback();
+      const progress = this.createProgressHooks(action, connKey, options);
+      let migrationResult: [number, string[]];
+      try {
+        migrationResult =
+          action === "apply"
+            ? await knex.migrate.latest(progress)
+            : await knex.migrate.rollback(progress);
+      } catch (caught) {
+        // lifecycle hook 이전의 연결·lock·목록 조회 실패도 실제 대상 DB에 귀속합니다.
+        throw new MigrationTargetExecutionError(connKey, caught);
+      }
+      const [batchNo, applied] = migrationResult;
 
       results.push({
         connKey,
         batchNo,
         applied,
       });
+      this.emitProgress(options, {
+        type: "target-complete",
+        action,
+        connKey,
+        batchNo,
+        files: applied,
+      });
     }
 
     return results;
   }
 
-  private async getMigrationCodes(): Promise<MigrationCode[]> {
+  private migrationName<Value>(migration: Value): string {
+    if (isStringValue(migration)) {
+      return path.basename(migration);
+    }
+    if (isObjectValue(migration) && migration !== null) {
+      const candidate =
+        /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ migration as {
+          file?: unknown;
+          name?: unknown;
+        };
+      if (isStringValue(candidate.file)) {
+        return path.basename(candidate.file);
+      }
+      if (isStringValue(candidate.name)) {
+        return path.basename(candidate.name);
+      }
+    }
+    return String(migration);
+  }
+
+  private emitProgress(options: MigrationRunOptions | undefined, event: MigrationProgressEvent) {
+    try {
+      options?.onProgress?.(event);
+    } catch (error) {
+      // 진행률 소비자의 실패가 이미 시작한 DB 작업과 정리를 방해하면 안 됩니다.
+      console.warn("Migration progress observer failed:", error);
+    }
+  }
+
+  private createProgressHooks(
+    action: MigrationAction,
+    connKey: MigrationTarget | "shadow",
+    options?: MigrationRunOptions,
+  ): Knex.MigratorConfigWithLifecycleHooks {
+    let files: string[] = [];
+    const emitFile = <Value>(type: "file-start" | "file-executed", migration: Value) => {
+      const file = this.migrationName(migration);
+      const index = Math.max(files.indexOf(file), 0);
+      this.emitProgress(options, {
+        type,
+        action,
+        connKey,
+        file,
+        index,
+        total: files.length,
+      });
+    };
+
+    return {
+      beforeAll: async (_knex, migrations) => {
+        files = migrations.map((migration) => this.migrationName(migration));
+        this.emitProgress(options, { type: "target-start", action, connKey, files });
+      },
+      beforeEach: async (_knex, migrations) => {
+        migrations.forEach((migration) => emitFile("file-start", migration));
+      },
+      afterEach: async (_knex, migrations) => {
+        migrations.forEach((migration) => emitFile("file-executed", migration));
+      },
+    };
+  }
+
+  private assertMigrationTarget(connKey: MigrationTarget): void {
+    if (!this.getMigrationTargetKeys().includes(connKey)) {
+      throw new Error(
+        `Migration target is not allowed in NODE_ENV=${getSonamuEnvironment()}: ${String(connKey)}`,
+      );
+    }
+  }
+
+  /**
+   * 마이그레이션 대상 커넥션의 정적 메타데이터를 반환합니다.
+   * DB에 연결하지 않으므로 CLI와 Web이 상태 조회 전에 즉시 사용할 수 있습니다.
+   *
+   * @category 분리형 마이그레이션 API
+   */
+  getConnections(): MigrationConnectionMeta[] {
+    const slackConfirm = new SlackConfirm();
+    return this.getMigrationTargetKeys().map((connKey) => {
+      const connection =
+        /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ Sonamu.dbConfig[
+          connKey
+        ].connection as Knex.PgConnectionConfig;
+      const host = connection.host ?? "localhost";
+      return {
+        connKey,
+        name: String(connKey),
+        host,
+        port: connection.port ?? 5432,
+        database: connection.database ?? "",
+        remote: !LOCAL_DB_HOSTS.has(host.toLowerCase()),
+        requiresApproval: slackConfirm.isTargetRequiresApproval(connKey),
+      };
+    });
+  }
+
+  /**
+   * 소스에 존재하는 마이그레이션 파일 목록을 반환합니다.
+   *
+   * @category 분리형 마이그레이션 API
+   */
+  async getMigrationCodes(): Promise<MigrationCode[]> {
     const srcMigrationsDir = path.join(Sonamu.apiRootPath, "src", "migrations"); // 이건 환경에 관계없이 항상 src에서 찾아야 해요.
 
     if (!(await exists(srcMigrationsDir))) {
@@ -123,183 +280,214 @@ export class Migrator {
   }
 
   /**
-   * 타겟별 마이그레이션 상태와 코드 생성/준비 상태를 구해옵니다.
-   * 실제로 DB에 접근도 하고 마이그레이션 코드 파일도 확인하고,
-   * 필요하다면 적용할 수 있는 코드를 생성까지 해옵니다.
+   * 커넥션 하나의 현재 버전과 pending 목록을 독립적으로 조회합니다.
+   * 여러 대상은 호출자가 병렬로 조립할 수 있습니다.
    *
-   * CLI와 Sonamu UI에서 사용됩니다.
-   *
-   * @returns
+   * @category 분리형 마이그레이션 API
    */
-  async getStatus(): Promise<MigrationStatus> {
+  async getConnectionStatus(connKey: MigrationTarget): Promise<MigrationConnectionStatus> {
+    this.assertMigrationTarget(connKey);
+    const startedAt = performance.now();
     const codes = await this.getMigrationCodes();
-    Naite.t("migrator:getStatus:codes", codes);
+    const knexOptions = Sonamu.dbConfig[connKey];
+    const connection =
+      /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ knexOptions.connection as Knex.PgConnectionConfig;
+    // SAFETY: Knex가 제공한 PostgreSQL 연결 구성을 복사해 timeout 필드만 덮어쓴다.
+    const tConn = createKnexInstance({
+      ...knexOptions,
+      connection: {
+        ...connection,
+        connectionTimeoutMillis: MIGRATION_CONN_TIMEOUT_MS,
+      },
+      pool: {
+        ...knexOptions.pool,
+        min: 0,
+        acquireTimeoutMillis: MIGRATION_CONN_TIMEOUT_MS,
+        createTimeoutMillis: MIGRATION_CONN_TIMEOUT_MS,
+        propagateCreateError: true,
+      },
+    });
 
-    const connKeys = this.getMigrationTargetKeys();
-
-    let migrationStatusError: string | undefined;
-
-    const statuses = await Promise.all(
-      connKeys.map(async (connKey) => {
-        const knexOptions = Sonamu.dbConfig[connKey];
-        const connection = knexOptions.connection as Knex.PgConnectionConfig;
-        // 상태 조회용 커넥션은 fail-fast로 만든다: 불통 DB에서 커넥션 획득을 무한정
-        // 재시도하며 CLI 프로세스가 종료되지 않는 것을 막는다.
-        // - connectionTimeoutMillis: 소켓 연결 자체를 5초 안에 포기 → 소켓이 정리되어 프로세스가 종료됨
-        // - propagateCreateError: 첫 연결 실패를 즉시 전파(풀 재시도 없이 바로 실패)
-        const tConn = createKnexInstance({
-          ...knexOptions,
-          connection: {
-            ...(connection as Record<string, unknown>),
-            connectionTimeoutMillis: MIGRATION_CONN_TIMEOUT_MS,
-          },
-          pool: {
-            ...knexOptions.pool,
-            min: 0,
-            acquireTimeoutMillis: MIGRATION_CONN_TIMEOUT_MS,
-            createTimeoutMillis: MIGRATION_CONN_TIMEOUT_MS,
-            propagateCreateError: true,
-          },
-        });
-        const connString =
-          `pg://${connection.user ?? ""}@${connection.host}:${connection.port}/${connection.database}` as ConnString;
-
-        try {
-          // DB 연결 확인: 불통 DB에서 status/list/currentVersion이 커넥션 획득
-          // 타임아웃까지 hang하는 것을 막기 위해, 먼저 5초 안에 응답하는지 확인한다.
-          try {
-            await withTimeout(
-              tConn.raw("select 1"),
-              MIGRATION_CONN_TIMEOUT_MS,
-              () =>
-                new Error(
-                  `DB 연결 시간 초과 (${MIGRATION_CONN_TIMEOUT_MS}ms) — ${connection.host}:${connection.port}/${connection.database}`,
-                ),
-            );
-          } catch (err) {
-            console.warn(
-              chalk.yellow(
-                `${connKey}의 마이그레이션 상태를 가져오는 데에 실패하였습니다. 데이터베이스에 연결할 수 없습니다.\n시도한 연결 설정:\n${JSON.stringify(knexOptions.connection, null, 2)}\n발생한 에러:\n${err}\n`,
-              ),
-            );
-            migrationStatusError = err instanceof Error ? err.message : String(err);
-            return {
-              name: connKey,
-              connKey,
-              connString,
-              currentVersion: "error" as const,
-              status: "error" as const,
-              pending: [] as string[],
-            };
-          }
+    try {
+      await withTimeout(tConn.raw("select 1"), MIGRATION_CONN_TIMEOUT_MS, () => {
+        return new Error(
+          `DB 연결 시간 초과 (${MIGRATION_CONN_TIMEOUT_MS}ms) — ${connection.host}:${connection.port}/${connection.database}`,
+        );
+      });
 
-          const status: number | "error" = await (async () => {
-            try {
-              return await tConn.migrate.status();
-            } catch (err) {
-              if (this.isMissingMigrationTableError(err)) {
-                return codes.length;
-              }
-
-              console.warn(
-                chalk.yellow(
-                  `${connKey}의 마이그레이션 상태를 가져오는 데에 실패하였습니다. 데이터베이스가 올바르게 구성되지 않은 것 같습니다. 확인하시고 다시 시도해주세요.\n시도한 연결 설정:\n${JSON.stringify(knexOptions.connection, null, 2)}\n발생한 에러:\n${err}\n`,
-                ),
-              );
-              migrationStatusError = err instanceof Error ? err.message : String(err);
-              return "error";
-            }
-          })();
-          const pending: string[] = await (async () => {
-            try {
-              const [, fdList] = await tConn.migrate.list();
-              return fdList.map((fd: { file: string }) => fd.file.replace(".ts", ""));
-            } catch (err) {
-              if (this.isMissingMigrationTableError(err)) {
-                return codes.map((code) => code.name);
-              }
-
-              migrationStatusError = err instanceof Error ? err.message : String(err);
-              return [];
-            }
-          })();
-          const currentVersion: string | "error" = await (async () => {
-            try {
-              return await tConn.migrate.currentVersion();
-            } catch (_err) {
-              if (this.isMissingMigrationTableError(_err)) {
-                return "none";
-              }
-
-              migrationStatusError = _err instanceof Error ? _err.message : String(_err);
-              return "error";
-            }
-          })();
-          Naite.t("migrator:getStatus:status", status);
-
-          return {
-            name: connKey,
-            connKey,
-            connString,
-            currentVersion,
-            status: status,
-            pending,
-          };
-        } finally {
-          // 불통 DB의 커넥션 정리가 커넥션 획득 타임아웃까지 hang하지 않도록 감싼다.
-          await withTimeout(
-            tConn.destroy(),
-            MIGRATION_CONN_TIMEOUT_MS,
-            () => new Error("connection destroy timeout"),
-          ).catch(() => {});
+      let error: string | undefined;
+      const status: number | "error" = await tConn.migrate.status().catch((caught) => {
+        if (this.isMissingMigrationTableError(caught)) {
+          return codes.length;
         }
-      }),
-    );
+        error = caught instanceof Error ? caught.message : String(caught);
+        return "error" as const;
+      });
+      const pending: string[] = await tConn.migrate.list().then(
+        ([, files]: [unknown[], { file: string }[]]) =>
+          files.map(({ file }) => file.replace(/\.ts$/, "")),
+        (cause: unknown) => {
+          if (this.isMissingMigrationTableError(cause)) {
+            return codes.map(({ name }) => name);
+          }
+          error ??= cause instanceof Error ? cause.message : String(cause);
+          return [];
+        },
+      );
+      const currentVersion: string | "none" | "error" = await tConn.migrate
+        .currentVersion()
+        .catch((cause: unknown) => {
+          if (this.isMissingMigrationTableError(cause)) {
+            return "none" as const;
+          }
+          error ??= cause instanceof Error ? cause.message : String(cause);
+          return "error" as const;
+        });
+      Naite.t("migrator:getStatus:status", status);
+      const connectionStatus: MigrationConnectionStatus = {
+        connKey,
+        currentVersion,
+        status,
+        pending,
+        latencyMs: performance.now() - startedAt,
+      };
+      if (error !== undefined) connectionStatus.error = error;
+      return connectionStatus;
+    } catch (caught) {
+      const error = caught instanceof Error ? caught.message : String(caught);
+      console.warn(
+        chalk.yellow(
+          `${String(connKey)}의 마이그레이션 상태를 가져오는 데에 실패하였습니다.\n${error}`,
+        ),
+      );
+      return {
+        connKey,
+        currentVersion: "error",
+        status: "error",
+        pending: [],
+        latencyMs: performance.now() - startedAt,
+        error,
+      };
+    } finally {
+      await withTimeout(tConn.destroy(), MIGRATION_CONN_TIMEOUT_MS, () => {
+        return new Error("connection destroy timeout");
+      }).catch(() => {});
+    }
+  }
 
-    Naite.t("migrator:getStatus:conns", statuses);
+  /**
+   * 최신 상태인 기준 DB와 엔티티 정의를 비교해 생성 예정 코드를 반환합니다.
+   *
+   * @category 분리형 마이그레이션 API
+   */
+  async getPreparedCodes(compareConnKey: MigrationTarget): Promise<GenMigrationCode[]> {
+    const status = await this.getConnectionStatus(compareConnKey);
+    if (status.status !== 0 || status.error !== undefined) {
+      throw new Error(
+        `Migration comparison requires an up-to-date database: ${String(compareConnKey)}`,
+      );
+    }
 
-    const preparedCodes: GenMigrationCode[] = await (async () => {
-      const status0conn = statuses.find((status) => status.status === 0);
-      if (status0conn === undefined) {
-        console.warn(
-          chalk.yellow(
-            `While trying to prepare migration codes, we found that there is no database to compare migrations. We need at least one database where every migration is applied(status === 0). You might want to apply your existing migrations to one of the databases.`,
-          ),
-        );
-        return [];
-      }
+    return this.compareWithConnection(compareConnKey);
+  }
 
-      const compareDBconn = createKnexInstance(Sonamu.dbConfig[status0conn.connKey]);
-      try {
-        return await this.compareMigrations(compareDBconn);
-      } finally {
-        await compareDBconn.destroy();
-      }
-    })();
+  private async compareWithConnection(compareConnKey: MigrationTarget) {
+    const compareDB = createKnexInstance(Sonamu.dbConfig[compareConnKey]);
+    try {
+      return await this.compareMigrations(compareDB);
+    } finally {
+      await compareDB.destroy();
+    }
+  }
+
+  /**
+   * @deprecated 신규 UI에서는 커넥션별 조회 API를 사용합니다.
+   * 기존 CLI와 스크립트 호환을 위해 전체 상태를 조립합니다.
+   * @category 호환용 마이그레이션 API
+   */
+  async getStatus(): Promise<MigrationStatus> {
+    const [codes, connections] = await Promise.all([
+      this.getMigrationCodes(),
+      Promise.resolve(this.getConnections()),
+    ]);
+    Naite.t("migrator:getStatus:codes", codes);
 
+    const connectionStatuses = await Promise.all(
+      connections.map(({ connKey }) => this.getConnectionStatus(connKey)),
+    );
+    const conns = connections.map((connection, index) => {
+      const status = connectionStatuses[index];
+      assert(status !== undefined);
+      const configured =
+        /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ Sonamu.dbConfig[
+          connection.connKey
+        ].connection as Knex.PgConnectionConfig;
+      return {
+        name: connection.name,
+        connKey: connection.connKey,
+        connString:
+          /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ `pg://${configured.user ?? ""}@${configured.host}:${configured.port}/${configured.database}` as ConnString,
+        currentVersion: status.currentVersion,
+        status: status.status,
+        pending: status.pending,
+      };
+    });
+    Naite.t("migrator:getStatus:conns", conns);
+
+    const compareConn = connectionStatuses.find(
+      ({ status, error }) => status === 0 && error === undefined,
+    );
+    const preparedCodes =
+      compareConn === undefined ? [] : await this.compareWithConnection(compareConn.connKey);
     Naite.t("migrator:getStatus:preparedCodes", preparedCodes);
 
     return {
-      conns: statuses,
+      conns,
       codes,
       preparedCodes,
-      error: migrationStatusError,
+      error: connectionStatuses.find(({ error }) => error !== undefined)?.error,
     };
   }
 
   /**
-   * 마이그레이션을 적용하거나 롤백합니다.
-   * Sonamu UI에서 마이그레이션 작업을 수행할 때 사용됩니다.
+   * 대상 DB에 pending 마이그레이션을 적용합니다.
+   * CLI와 Web은 같은 메서드를 사용하며, Web은 `onProgress`를 stream으로 변환합니다.
    *
-   * CLI와 Sonamu UI에서 사용됩니다.
+   * @category 분리형 마이그레이션 API
+   */
+  async apply(targets: MigrationTarget[], options?: MigrationRunOptions): Promise<MigrationResult> {
+    return this.runActionWithProgress("apply", targets, options);
+  }
+
+  /**
+   * 대상 DB에서 가장 최근 migration batch를 롤백합니다.
+   * CLI와 Web은 같은 메서드를 사용하며, Web은 `onProgress`를 stream으로 변환합니다.
    *
-   * @param action 작업 유형 (apply/rollback)
-   * @param targets 작업 대상 DB 설정 키 (keyof SonamuDBConfig)
-   * @returns 작업 결과
+   * @category 분리형 마이그레이션 API
+   */
+  async rollback(
+    targets: MigrationTarget[],
+    options?: MigrationRunOptions,
+  ): Promise<MigrationResult> {
+    return this.runActionWithProgress("rollback", targets, options);
+  }
+
+  /**
+   * @deprecated action 문자열 대신 {@link apply} 또는 {@link rollback}을 직접 사용합니다.
+   * 기존 외부 호출의 하위 호환만을 위해 유지합니다.
+   * @category 호환용 마이그레이션 API
    */
   async runAction(
     action: "apply" | "rollback",
     targets: (keyof SonamuDBConfig)[],
+  ): Promise<MigrationResult> {
+    return action === "apply" ? this.apply(targets) : this.rollback(targets);
+  }
+
+  private async runActionWithProgress(
+    action: "apply" | "rollback",
+    targets: MigrationTarget[],
+    options?: MigrationRunOptions,
   ): Promise<MigrationResult> {
     Naite.t("migrator:runAction:action", action);
     Naite.t("migrator:runAction:targets", targets);
@@ -320,10 +508,12 @@ export class Migrator {
           options: Sonamu.dbConfig[target],
         }))
         .filter((c) => c.options !== undefined),
-      ({ options }) =>
-        `${(options.connection as Knex.PgConnectionConfig).host}:${
-          (options.connection as Knex.PgConnectionConfig).port ?? 5432
-        }/${(options.connection as Knex.PgConnectionConfig).database}`,
+      ({ options: dbOptions }) =>
+        `${/* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ (dbOptions.connection as Knex.PgConnectionConfig).host}:${
+          /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ (
+            dbOptions.connection as Knex.PgConnectionConfig
+          ).port ?? 5432
+        }/${/* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ (dbOptions.connection as Knex.PgConnectionConfig).database}`,
     );
 
     // get connections
@@ -335,15 +525,7 @@ export class Migrator {
     );
 
     try {
-      // action
-      const result = await (async () => {
-        switch (action) {
-          case "apply":
-            return this.runMigrationsSequentially(conns, "apply");
-          case "rollback":
-            return this.runMigrationsSequentially(conns, "rollback");
-        }
-      })();
+      const result = await this.runMigrationsSequentially(conns, action, options);
 
       Naite.t("migrator:runAction:result", result);
 
@@ -357,65 +539,15 @@ export class Migrator {
     }
   }
 
-  /**
-   * 삭제 가능한 마이그레이션 코드 파일을 검증합니다.
-   *
-   * @param conns 마이그레이션 상태 배열
-   * @param codeNames 삭제할 마이그레이션 코드 파일 이름 배열
-   * @returns 삭제 가능 여부 및 적용된 마이그레이션 코드 파일 이름
-   */
-  validateDeletable(conns: MigrationStatus["conns"], codeNames: string[]) {
-    const appliedCodes = codeNames.filter((codeName) =>
-      conns.some((conn) => !conn.pending.includes(codeName)),
-    );
-
-    return {
-      canDelete: appliedCodes.length === 0,
-      appliedCodes,
-    };
-  }
-
-  /**
-   * 마이그레이션 코드 파일을 삭제합니다.
-   *
-   * Sonamu UI에서 사용됩니다.
-   *
-   * @param codeNames 삭제할 마이그레이션 코드 파일 이름 배열
-   * @returns 삭제된 마이그레이션 코드 파일 개수
-   */
-  async delCodes(codeNames: string[]): Promise<number> {
-    const { conns } = await this.getStatus();
-    const { canDelete, appliedCodes } = this.validateDeletable(conns, codeNames);
-    if (!canDelete) {
-      throw new Error(
-        `You cannot delete a migration file if there is already applied. Applied codes: ${appliedCodes.join(", ")}`,
-      );
-    }
-
-    return sum(
-      await Promise.all(
-        codeNames.map(async (codeName) => {
-          const filePath = `${Sonamu.apiRootPath}/src/migrations/${codeName}.ts`;
-          if (await exists(filePath)) {
-            await unlink(filePath);
-            return 1;
-          }
-          return 0;
-        }),
-      ),
-    );
-  }
-
   private genDateTag(index: number, baseDate: Date = new Date()): string {
     const date = new Date(baseDate.getTime() + index * 1000);
-    const pad = (num: number, size: number = 2) => num.toString().padStart(size, "0");
     return (
       date.getFullYear().toString() +
-      pad(date.getMonth() + 1) +
-      pad(date.getDate()) +
-      pad(date.getHours()) +
-      pad(date.getMinutes()) +
-      pad(date.getSeconds())
+      padDatePart(date.getMonth() + 1) +
+      padDatePart(date.getDate()) +
+      padDatePart(date.getHours()) +
+      padDatePart(date.getMinutes()) +
+      padDatePart(date.getSeconds())
     );
   }
 
@@ -426,8 +558,11 @@ export class Migrator {
    *
    * @returns 생성된 마이그레이션 코드 파일 개수
    */
-  async generatePreparedCodes(): Promise<number> {
-    const { preparedCodes } = await this.getStatus();
+  async generatePreparedCodes(compareConnKey?: MigrationTarget): Promise<number> {
+    const preparedCodes =
+      compareConnKey === undefined
+        ? (await this.getStatus()).preparedCodes
+        : await this.getPreparedCodes(compareConnKey);
     Naite.t("migrator:generatePreparedCodes:preparedCodes", preparedCodes);
     if (preparedCodes.length === 0) {
       console.log(chalk.green("\n현재 모두 싱크된 상태입니다."));
@@ -519,14 +654,15 @@ export class Migrator {
   }
 
   /**
-   * Shadow DB 테스트를 진행합니다.
+   * test DB의 snapshot으로 임시 Shadow DB를 만들고 전체 마이그레이션을 검증합니다.
+   * CLI와 Web은 `onProgress` 유무만 달리해 같은 실행 의미를 공유할 수 있습니다.
    *
-   * Sonamu UI에서 사용됩니다.
-   *
-   * @returns Shadow DB 테스트 결과
+   * @category 분리형 마이그레이션 API
    */
-  async runShadowTest(): Promise<MigrationResult> {
-    const baseTestConn = Sonamu.dbConfig.test.connection as Knex.PgConnectionConfig;
+  async runShadowTest(options?: MigrationRunOptions): Promise<MigrationResult> {
+    const baseTestConn =
+      /* SAFETY: Knex와 PostgreSQL 스키마 조회 계약이 이 값의 타입을 보장한다. */ Sonamu.dbConfig
+        .test.connection as Knex.PgConnectionConfig;
     const workerId = process.env.SONAMU_WORKER_DB === "true" ? process.env.VITEST_POOL_ID : null;
     const templateDatabase =
       workerId !== null ? `${baseTestConn.database}_${workerId ?? "1"}` : baseTestConn.database;
@@ -570,13 +706,22 @@ export class Migrator {
 
       // shadow DB 테스트 진행
       try {
-        const [batchNo, applied] = await sdb.migrate.latest();
+        const progress = this.createProgressHooks("shadow", "shadow", options);
+        const [batchNo, applied] = await sdb.migrate.latest(progress);
         !isTest() &&
           console.log(chalk.green("Shadow DB 테스트에 성공했습니다!"), {
             batchNo,
             applied,
           });
 
+        this.emitProgress(options, {
+          type: "target-complete",
+          action: "shadow",
+          connKey: "shadow",
+          batchNo,
+          files: applied,
+        });
+
         return [
           {
             connKey: "shadow",
@@ -586,7 +731,10 @@ export class Migrator {
         ];
       } catch (e) {
         console.error(e);
-        throw new ServiceUnavailableException(SD("sonamu.error.shadowDbTestFailed"));
+        throw new MigrationTargetExecutionError(
+          "shadow",
+          new ServiceUnavailableException(SD("sonamu.error.shadowDbTestFailed")),
+        );
       } finally {
         await sdb.destroy();
       }