sonamu 0.7.4 → 0.7.5

package/src/migration/code-generation.ts

@@ -1,5 +1,5 @@
 import equal from "fast-deep-equal";
-import { alphabetical, diff, fork, omit } from "radashi";
+import { alphabetical, diff, omit } from "radashi";
 import { Naite } from "..";
 import type {
   GenMigrationCode,
@@ -11,6 +11,16 @@ import type {
 import { formatCode } from "../utils/formatter";
 import { differenceWith, intersectionBy } from "../utils/utils";
 
+/**
+ * 컬럼 정의 결과 타입
+ * - builder: Knex table builder 메서드로 실행할 구문 (table.xxx())
+ * - raw: knex.raw()로 실행할 구문
+ */
+type ColumnDefinitionResult = {
+  builder: string[];
+  raw: string[];
+};
+
 /**
  * 테이블 생성하는 케이스 - 컬럼/인덱스 생성
  */
@@ -19,11 +29,7 @@ async function generateCreateCode_ColumnAndIndexes(
   columns: MigrationColumn[],
   indexes: MigrationIndex[],
 ): Promise<GenMigrationCode> {
-  // fulltext index 분리
-  const [ngramIndexes, standardIndexes] = fork(
-    indexes,
-    (i) => i.type === "fulltext" && i.parser === "ngram",
-  );
+  const columnDefs = genColumnDefinitions(table, columns);
 
   // 컬럼, 인덱스 처리
   const lines: string[] = [
@@ -31,14 +37,12 @@ async function generateCreateCode_ColumnAndIndexes(
     "",
     "export async function up(knex: Knex): Promise<void> {",
     `await knex.schema.createTable("${table}", (table) => {`,
-    "// columns",
-    ...genColumnDefinitions(columns),
-    "",
-    "// indexes",
-    ...standardIndexes.map((index) => genIndexDefinition(index, table)),
+    ...columnDefs.builder,
     "});",
-    // ngram은 knex.raw로 처리하므로 createTable 밖에서 실행
-    ...ngramIndexes.map((index) => genIndexDefinition(index, table)),
+    // raw 구문 (Generated Column 등)
+    ...columnDefs.raw,
+    // index는 knex.raw로 처리하므로 createTable 밖에서 실행
+    ...indexes.map((index) => genIndexDefinition(index, table)),
     "}",
     "",
     "export async function down(knex: Knex): Promise<void> {",
@@ -55,65 +59,133 @@ async function generateCreateCode_ColumnAndIndexes(
 
 /**
  * MigrationColumn[] 읽어서 컬럼 정의하는 구문 생성
+ * @returns builder: table builder 메서드, raw: knex.raw() 구문
  */
-function genColumnDefinitions(columns: MigrationColumn[]): string[] {
-  return columns.map((column) => {
-    const chains: string[] = [];
-    if (column.name === "id") {
-      return `table.increments().primary();`;
+function genColumnDefinitions(table: string, columns: MigrationColumn[]): ColumnDefinitionResult {
+  const result: ColumnDefinitionResult = {
+    builder: [],
+    raw: [],
+  };
+
+  for (const column of columns) {
+    // Generated Column은 raw로 처리
+    if (column.generated) {
+      result.raw.push(genGeneratedColumnDefinition(table, column));
+      continue;
     }
 
-    // 배열 타입 처리
-    if (column.type.endsWith("[]")) {
-      const elementType = column.type.slice(0, -2); // "integer[]" -> "integer"
-      const pgType = getPgArrayType(column, elementType);
-      chains.push(`specificType('${column.name}', '${pgType}')`);
-    } else if (column.type === "numberOrNumeric") {
-      // number
-      if (column.numberType === "real") {
-        chains.push(`float('${column.name}')`);
-      } else if (column.numberType === "double precision") {
-        chains.push(`double('${column.name}')`);
-      } else if ((column.numberType ?? "numeric") === "numeric") {
-        chains.push(`decimal('${column.name}', ${column.precision}, ${column.scale})`);
-      }
-    } else if (column.type === "string") {
-      // string
-      if (column.length !== undefined) {
-        chains.push(`string('${column.name}', ${column.length})`);
-      } else {
-        chains.push(`text('${column.name}')`);
-      }
-    } else if (column.type === "date") {
-      // date
-      chains.push(`timestamp('${column.name}', { useTz: true })`);
-    } else if (column.type === "json") {
-      // json
-      chains.push(`jsonb('${column.name}')`);
+    // 일반 컬럼은 builder로 처리
+    result.builder.push(genNormalColumnDefinition(column));
+  }
+
+  return result;
+}
+
+/**
+ * Generated Column 정의 생성 (ALTER TABLE ADD COLUMN 사용)
+ */
+function genGeneratedColumnDefinition(table: string, column: MigrationColumn): string {
+  if (!column.generated) {
+    throw new Error("Generated column definition required");
+  }
+  const pgType = getPgTypeForColumn(column);
+  const storageType = column.generated.type === "VIRTUAL" ? " VIRTUAL" : " STORED";
+  const nullableClause = column.nullable ? "" : " NOT NULL";
+  return `await knex.raw(\`ALTER TABLE "${table}" ADD COLUMN "${column.name}" ${pgType} GENERATED ALWAYS AS (${column.generated.expression})${storageType}${nullableClause}\`);`;
+}
+
+/**
+ * 일반 컬럼 정의 생성 (table.xxx() 체인)
+ */
+function genNormalColumnDefinition(column: MigrationColumn): string {
+  const chains: string[] = [];
+
+  if (column.name === "id") {
+    return `table.increments().primary();`;
+  }
+
+  // 배열 타입 처리
+  if (column.type.endsWith("[]")) {
+    const elementType = column.type.slice(0, -2); // "integer[]" -> "integer"
+    const pgType = getPgArrayType(column, elementType);
+    chains.push(`specificType('${column.name}', '${pgType}')`);
+  } else if (column.type === "vector") {
+    // Knex는 vector 타입을 직접 지원하지 않으므로 specificType 사용
+    chains.push(`specificType('${column.name}', 'vector(${column.dimensions})')`);
+  } else if (column.type === "numberOrNumeric") {
+    // number
+    if (column.numberType === "real") {
+      chains.push(`float('${column.name}')`);
+    } else if (column.numberType === "double precision") {
+      chains.push(`double('${column.name}')`);
+    } else if ((column.numberType ?? "numeric") === "numeric") {
+      chains.push(`decimal('${column.name}', ${column.precision}, ${column.scale})`);
+    }
+  } else if (column.type === "string") {
+    // string
+    if (column.length !== undefined) {
+      chains.push(`string('${column.name}', ${column.length})`);
     } else {
-      // type, length
-      let extraType: string | undefined;
-      chains.push(
-        `${column.type}('${column.name}'${
-          column.length ? `, ${column.length}` : ""
-        }${extraType ? `, '${extraType}'` : ""})`,
-      );
+      chains.push(`text('${column.name}')`);
     }
+  } else if (column.type === "date") {
+    // date
+    chains.push(`timestamp('${column.name}', { useTz: true })`);
+  } else if (column.type === "json") {
+    // json
+    chains.push(`jsonb('${column.name}')`);
+  } else {
+    // type, length
+    let extraType: string | undefined;
+    chains.push(
+      `${column.type}('${column.name}'${
+        column.length ? `, ${column.length}` : ""
+      }${extraType ? `, '${extraType}'` : ""})`,
+    );
+  }
 
-    // nullable
-    chains.push(column.nullable ? "nullable()" : "notNullable()");
+  // nullable
+  chains.push(column.nullable ? "nullable()" : "notNullable()");
 
-    // defaultTo
-    if (column.defaultTo !== undefined) {
-      if (typeof column.defaultTo === "string" && column.defaultTo.startsWith(`"`)) {
-        chains.push(`defaultTo(${column.defaultTo})`);
-      } else {
-        chains.push(`defaultTo(knex.raw('${column.defaultTo}'))`);
-      }
+  // defaultTo
+  if (column.defaultTo !== undefined) {
+    if (typeof column.defaultTo === "string" && column.defaultTo.startsWith(`"`)) {
+      chains.push(`defaultTo(${column.defaultTo})`);
+    } else {
+      chains.push(`defaultTo(knex.raw('${column.defaultTo}'))`);
     }
+  }
 
-    return `table.${chains.join(".")};`;
-  });
+  return `table.${chains.join(".")};`;
+}
+
+/**
+ * MigrationColumn의 타입을 PostgreSQL 타입 문자열로 변환
+ */
+function getPgTypeForColumn(column: MigrationColumn): string {
+  if (column.type.endsWith("[]")) {
+    const elementType = column.type.slice(0, -2);
+    return getPgArrayType(column, elementType);
+  }
+
+  switch (column.type) {
+    case "string":
+      return column.length !== undefined ? `varchar(${column.length})` : "text";
+    case "bigInteger":
+      return "bigint";
+    case "numberOrNumeric":
+      if (column.numberType === "real") return "real";
+      if (column.numberType === "double precision") return "double precision";
+      return `numeric(${column.precision}, ${column.scale})`;
+    case "date":
+      return "timestamptz";
+    case "json":
+      return "jsonb";
+    case "vector":
+      return `vector(${column.dimensions})`;
+    default:
+      return column.type;
+  }
 }
 
 function getPgArrayType(column: MigrationColumn, elementType: string): string {
@@ -131,6 +203,7 @@ function getPgArrayType(column: MigrationColumn, elementType: string): string {
   if (elementType === "boolean") return "boolean[]";
   if (elementType === "uuid") return "uuid[]";
   if (elementType === "enum") return "text[]";
+  if (elementType === "vector") return `vector(${column.dimensions})[]`;
 
   throw new Error(`Unknown array element type: ${elementType}`);
 }
@@ -138,23 +211,64 @@ function getPgArrayType(column: MigrationColumn, elementType: string): string {
 /**
  * 개별 인덱스 정의 생성
  */
-function genIndexDefinition(index: MigrationIndex, table: string) {
+function genIndexDefinition(index: MigrationIndex, table: string): string {
+  if (index.type === "hnsw" || index.type === "ivfflat") {
+    return genVectorIndexDefinition(index, table);
+  }
+
   const methodMap = {
-    index: "index",
-    fulltext: "index",
-    unique: "unique",
+    index: "INDEX",
+    fulltext: "INDEX",
+    unique: "UNIQUE INDEX",
   };
 
-  if (index.type === "fulltext" && index.parser === "ngram") {
-    return `await knex.raw(\`ALTER TABLE ${table} ADD FULLTEXT INDEX ${index.name} (${index.columns.join(
-      ", ",
-    )}) WITH PARSER ngram\`);`;
+  const nullsNotDistinctClause =
+    index.nullsNotDistinct === undefined
+      ? ""
+      : ` NULLS ${index.nullsNotDistinct ? "NOT DISTINCT" : "DISTINCT"}`;
+
+  return `await knex.raw(
+  \`CREATE ${methodMap[index.type]} ${index.name} ON ${table} (${index.columns
+    .map((col) => {
+      const sortOrderClause = col.sortOrder === undefined ? "" : ` ${col.sortOrder}`;
+      const nullsFirstClause =
+        col.nullsFirst === undefined ? "" : ` NULLS ${col.nullsFirst ? "FIRST" : "LAST"}`;
+      return `${col.name}${sortOrderClause}${nullsFirstClause}`;
+    })
+    .join(", ")})${nullsNotDistinctClause};\`
+  );`;
+}
+
+/**
+ * @description
+ * - HNSW (Hierarchical Navigable Small World): 느린 빌드, 빠른 검색 속도, 높은 메모리 및 정확도
+ * - IVFFlat (Inverted File with Flat Compression): 빠른 빌드, 중간 검색 속도, 낮은 메모리
+ *
+ * @example
+ * // HNSW 인덱스 (권장 - 빠른 검색, 높은 정확도)
+ * CREATE INDEX idx_embedding ON items USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
+ *
+ * // IVFFlat 인덱스 (대용량 데이터, 비용 중요 시)
+ * CREATE INDEX idx_embedding ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+ */
+function genVectorIndexDefinition(index: MigrationIndex, table: string): string {
+  const column = index.columns[0];
+  const vectorOps = column.vectorOps ?? "vector_cosine_ops";
+
+  // HNSW (Hierarchical Navigable Small World) - 권장: 빠른 검색, 높은 정확도
+  if (index.type === "hnsw") {
+    const m = index.m ?? 16;
+    const efConstruction = index.efConstruction ?? 64;
+    return `await knex.raw(\`CREATE INDEX ${index.name} ON ${table} USING hnsw (${column.name} ${vectorOps}) WITH (m = ${m}, ef_construction = ${efConstruction})\`);`;
   }
 
-  return `table.${methodMap[index.type]}([${index.columns
-    .map((col) => `'${col}'`)
-    .join(",")}], '${index.name}'${index.type === "fulltext" ? ", 'FULLTEXT'" : ""}
-  );`;
+  // IVFFlat (Inverted File with Flat Compression) - 대용량, 비용 중요 시
+  if (index.type === "ivfflat") {
+    const lists = index.lists ?? 100;
+    return `await knex.raw(\`CREATE INDEX ${index.name} ON ${table} USING ivfflat (${column.name} ${vectorOps}) WITH (lists = ${lists})\`);`;
+  }
+
+  throw new Error(`Unknown raw SQL index type: ${index.type}`);
 }
 
 /**
@@ -268,28 +382,23 @@ async function generateAlterCode_ColumnAndIndexes(
   // 인덱스의 add, drop 여부 확인
   const alterIndexesTo = getAlterIndexesTo(entityIndexes, dbIndexes);
 
-  // fulltext index 분리
-  const [ngramIndexes, standardIndexes] = fork(
-    alterIndexesTo.add,
-    (i) => i.type === "fulltext" && i.parser === "ngram",
-  );
-
   // 인덱스가 삭제되는 경우, 컬럼과 같이 삭제된 케이스에는 drop에서 제외해야함!
   const indexNeedsToDrop = alterIndexesTo.drop.filter(
     (index) =>
-      index.columns.every((colName) =>
-        alterColumnsTo.drop.map((col) => col.name).includes(colName),
+      index.columns.every(({ name }) =>
+        alterColumnsTo.drop.map((col) => col.name).includes(name),
       ) === false,
   );
 
   // 빈 코드 생성 방지
-  if (
-    alterColumnLinesTo.add.up.length === 0 &&
-    alterColumnLinesTo.drop.up.length === 0 &&
-    alterColumnLinesTo.alter.up.length === 0 &&
-    standardIndexes.length === 0 &&
-    indexNeedsToDrop.length === 0
-  ) {
+  const hasUpChanges =
+    alterColumnLinesTo.add.up.builder.length > 0 ||
+    alterColumnLinesTo.add.up.raw.length > 0 ||
+    alterColumnLinesTo.drop.up.builder.length > 0 ||
+    alterColumnLinesTo.alter.up.builder.length > 0 ||
+    alterIndexesTo.add.length > 0 ||
+    indexNeedsToDrop.length > 0;
+  if (!hasUpChanges) {
     Naite.t("migrator:generateAlterCode_ColumnAndIndexes:emptyCodeGenerationError", {
       entityColumns,
       dbColumns,
@@ -304,48 +413,65 @@ async function generateAlterCode_ColumnAndIndexes(
     "alterColumnsTo.alter.length": alterColumnsTo.alter.length,
     "alterIndexesTo.add.length": alterIndexesTo.add.length,
     "alterIndexesTo.drop.length": alterIndexesTo.drop.length,
-    "standardIndexes.length": standardIndexes.length,
     "indexNeedsToDrop.length": indexNeedsToDrop.length,
   });
   // Naite.t("migrator:generateAlterCode_ColumnAndIndexes:alterColumnsTo", alterColumnsTo);
 
   // TODO: 인덱스명 변경된 경우 처리
 
-  const lines: string[] = [
-    'import { Knex } from "knex";',
-    "",
-    "export async function up(knex: Knex): Promise<void> {",
-    `await knex.schema.alterTable("${table}", (table) => {`,
-    // 1. add column
-    ...(alterColumnsTo.add.length > 0 ? alterColumnLinesTo.add.up : []),
-    // 2. drop column
-    ...(alterColumnsTo.drop.length > 0 ? alterColumnLinesTo.drop.up : []),
-    // 3. alter column
-    ...(alterColumnsTo.alter.length > 0 ? alterColumnLinesTo.alter.up : []),
-    // 4. add index
-    ...standardIndexes.map((index) => genIndexDefinition(index, table)),
-    // 5. drop index
+  // table builder 메서드로 실행할 코드 (drop → add → alter 순서)
+  const upBuilderLines = [
+    ...(alterColumnLinesTo.drop.up.builder.length > 0 ? alterColumnLinesTo.drop.up.builder : []),
+    ...(alterColumnLinesTo.add.up.builder.length > 0 ? alterColumnLinesTo.add.up.builder : []),
+    ...(alterColumnLinesTo.alter.up.builder.length > 0 ? alterColumnLinesTo.alter.up.builder : []),
     ...indexNeedsToDrop.map(genIndexDropDefinition),
-    "});",
-    // ngram은 knex.raw로 처리하므로 alterTable 밖에서 실행
-    ...ngramIndexes.map((index) => genIndexDefinition(index, table)),
-    "}",
-    "",
-    "export async function down(knex: Knex): Promise<void> {",
-    `return knex.schema.alterTable("${table}", (table) => {`,
-    ...(alterColumnsTo.add.length > 0 ? alterColumnLinesTo.add.down : []),
-    ...(alterColumnsTo.drop.length > 0 ? alterColumnLinesTo.drop.down : []),
-    ...(alterColumnsTo.alter.length > 0 ? alterColumnLinesTo.alter.down : []),
+  ];
+
+  // knex.raw()로 실행할 코드
+  const upRawLines = [
+    ...(alterColumnLinesTo.add.up.raw.length > 0 ? alterColumnLinesTo.add.up.raw : []),
+    ...alterIndexesTo.add.map((index) => genIndexDefinition(index, table)),
+  ];
+
+  // down은 up의 역순 (add.down = drop rollback, drop.down = add rollback)
+  const downBuilderLines = [
+    ...(alterColumnLinesTo.add.down.builder.length > 0 ? alterColumnLinesTo.add.down.builder : []),
+    ...(alterColumnLinesTo.alter.down.builder.length > 0
+      ? alterColumnLinesTo.alter.down.builder
+      : []),
+    ...(alterColumnLinesTo.drop.down.builder.length > 0
+      ? alterColumnLinesTo.drop.down.builder
+      : []),
     ...alterIndexesTo.add
       .filter(
         (index) =>
-          index.columns.every((colName) =>
-            alterColumnsTo.add.map((col) => col.name).includes(colName),
+          index.columns.every((indexCol) =>
+            alterColumnsTo.add.map((col) => col.name).includes(indexCol.name),
           ) === false,
       )
       .map(genIndexDropDefinition),
+  ];
+
+  const downRawLines = [
+    ...(alterColumnLinesTo.drop.down.raw.length > 0 ? alterColumnLinesTo.drop.down.raw : []),
     ...indexNeedsToDrop.map((index) => genIndexDefinition(index, table)),
-    "});",
+  ];
+
+  const lines: string[] = [
+    'import { Knex } from "knex";',
+    "",
+    "export async function up(knex: Knex): Promise<void> {",
+    ...(upBuilderLines.length > 0
+      ? [`await knex.schema.alterTable("${table}", (table) => {`, ...upBuilderLines, "});"]
+      : []),
+    ...upRawLines,
+    "}",
+    "",
+    "export async function down(knex: Knex): Promise<void> {",
+    ...(downBuilderLines.length > 0
+      ? [`await knex.schema.alterTable("${table}", (table) => {`, ...downBuilderLines, "});"]
+      : []),
+    ...downRawLines,
     "}",
   ];
 
@@ -374,6 +500,22 @@ async function generateAlterCode_ColumnAndIndexes(
   ];
 }
 
+/**
+ * 컬럼 비교를 위해 Generated Column의 expression을 제외한 객체를 생성
+ */
+function normalizeColumnForComparison(col: MigrationColumn): MigrationColumn {
+  if (col.generated) {
+    return {
+      ...col,
+      generated: {
+        type: col.generated.type,
+        expression: "",
+      },
+    };
+  }
+  return col;
+}
+
 /**
  * 각 컬럼 이름 기준으로 add, drop, alter 여부 확인
  */
@@ -386,8 +528,8 @@ function getAlterColumnsTo(entityColumns: MigrationColumn[], dbColumns: Migratio
 
   // 컬럼명 기준 비교
   const extraColumns = {
-    db: diff(dbColumns, entityColumns, (col) => col.name),
-    entity: diff(entityColumns, dbColumns, (col) => col.name),
+    db: diff(dbColumns, entityColumns, (col) => [col.name, col.generated?.type].join("///")),
+    entity: diff(entityColumns, dbColumns, (col) => [col.name, col.generated?.type].join("///")),
   };
   if (extraColumns.entity.length > 0) {
     columnsTo.add = columnsTo.add.concat(extraColumns.entity);
@@ -396,10 +538,14 @@ function getAlterColumnsTo(entityColumns: MigrationColumn[], dbColumns: Migratio
     columnsTo.drop = columnsTo.drop.concat(extraColumns.db);
   }
 
-  // 동일 컬럼명의 세부 필드 비교
+  // 동일 컬럼명의 세부 필드 비교 (Generated Column expression 제외)
   const sameDbColumns = intersectionBy(dbColumns, entityColumns, (col) => col.name);
   const sameMdColumns = intersectionBy(entityColumns, dbColumns, (col) => col.name);
-  columnsTo.alter = differenceWith(sameDbColumns, sameMdColumns, (a, b) => equal(a, b));
+  columnsTo.alter = differenceWith(
+    sameDbColumns,
+    sameMdColumns,
+    (a, b) => equal({ ...a, generated: undefined }, { ...b, generated: undefined }), // generated 컬럼은 alter로 처리하지 않음
+  );
 
   return columnsTo;
 }
@@ -415,25 +561,34 @@ function getAlterColumnLinesTo(
 ) {
   const linesTo = {
     add: {
-      up: [] as string[],
-      down: [] as string[],
+      up: { builder: [] as string[], raw: [] as string[] },
+      down: { builder: [] as string[], raw: [] as string[] },
     },
     drop: {
-      up: [] as string[],
-      down: [] as string[],
+      up: { builder: [] as string[], raw: [] as string[] },
+      down: { builder: [] as string[], raw: [] as string[] },
     },
     alter: {
-      up: [] as string[],
-      down: [] as string[],
+      up: { builder: [] as string[], raw: [] as string[] },
+      down: { builder: [] as string[], raw: [] as string[] },
     },
   };
 
-  linesTo.add = {
-    up: ["// add", ...genColumnDefinitions(columnsTo.add)],
-    down: [
-      "// rollback - add",
-      `table.dropColumns(${columnsTo.add.map((col) => `'${col.name}'`).join(", ")})`,
-    ],
+  // add columns
+  const addColumnDefs = genColumnDefinitions(table, columnsTo.add);
+  linesTo.add.up = {
+    builder: addColumnDefs.builder.length > 0 ? ["// add", ...addColumnDefs.builder] : [],
+    raw: addColumnDefs.raw.length > 0 ? ["// add (generated)", ...addColumnDefs.raw] : [],
+  };
+  linesTo.add.down = {
+    builder:
+      columnsTo.add.length > 0
+        ? [
+            "// rollback - add",
+            `table.dropColumns(${columnsTo.add.map((col) => `'${col.name}'`).join(", ")})`,
+          ]
+        : [],
+    raw: [],
   };
 
   // drop할 컬럼에 걸린 FK 찾기
@@ -449,20 +604,38 @@ function getAlterColumnLinesTo(
 
   const restoreFkLines = genForeignDefinitions(table, fkToDropBeforeColumn).up;
 
+  // drop의 rollback시에는 generated column도 복원해야 함
+  const dropColumnDefs = genColumnDefinitions(table, columnsTo.drop);
   linesTo.drop = {
-    up: [
-      ...(dropFkLines.length > 0
-        ? ["// drop foreign keys on columns to be dropped", ...dropFkLines]
-        : []),
-      "// drop columns",
-      `table.dropColumns(${columnsTo.drop.map((col) => `'${col.name}'`).join(", ")})`,
-    ],
-    down: [
-      "// rollback - drop columns",
-      ...genColumnDefinitions(columnsTo.drop),
-      ...(restoreFkLines.length > 0 ? ["// restore foreign keys", ...restoreFkLines] : []),
-    ],
+    up: {
+      builder: [
+        ...(dropFkLines.length > 0
+          ? ["// drop foreign keys on columns to be dropped", ...dropFkLines]
+          : []),
+        ...(columnsTo.drop.length > 0
+          ? [
+              "// drop columns",
+              `table.dropColumns(${columnsTo.drop.map((col) => `'${col.name}'`).join(", ")})`,
+            ]
+          : []),
+      ],
+      raw: [],
+    },
+    down: {
+      builder: [
+        ...(dropColumnDefs.builder.length > 0
+          ? ["// rollback - drop columns", ...dropColumnDefs.builder]
+          : []),
+        ...(restoreFkLines.length > 0 ? ["// restore foreign keys", ...restoreFkLines] : []),
+      ],
+      raw:
+        dropColumnDefs.raw.length > 0
+          ? ["// rollback - drop columns (generated)", ...dropColumnDefs.raw]
+          : [],
+    },
   };
+
+  // alter columns (Generated Column은 ALTER 불가하므로 drop 후 재생성)
   linesTo.alter = columnsTo.alter.reduce(
     (r, dbColumn) => {
       const entityColumn = entityColumns.find((col) => col.name === dbColumn.name);
@@ -472,21 +645,21 @@ function getAlterColumnLinesTo(
 
       // 컬럼 변경사항
       const columnDiffUp = diff(
-        genColumnDefinitions([entityColumn]),
-        genColumnDefinitions([dbColumn]),
+        genColumnDefinitions(table, [entityColumn]).builder,
+        genColumnDefinitions(table, [dbColumn]).builder,
       );
       const columnDiffDown = diff(
-        genColumnDefinitions([dbColumn]),
-        genColumnDefinitions([entityColumn]),
+        genColumnDefinitions(table, [dbColumn]).builder,
+        genColumnDefinitions(table, [entityColumn]).builder,
       );
       if (columnDiffUp.length > 0) {
-        r.up = [
-          ...r.up,
+        r.up.builder = [
+          ...r.up.builder,
           "// alter column",
           ...columnDiffUp.map((l) => `${l.replace(";", "")}.alter();`),
         ];
-        r.down = [
-          ...r.down,
+        r.down.builder = [
+          ...r.down.builder,
           "// rollback - alter column",
           ...columnDiffDown.map((l) => `${l.replace(";", "")}.alter();`),
         ];
@@ -495,8 +668,8 @@ function getAlterColumnLinesTo(
       return r;
     },
     {
-      up: [] as string[],
-      down: [] as string[],
+      up: { builder: [] as string[], raw: [] as string[] },
+      down: { builder: [] as string[], raw: [] as string[] },
     },
   );
 
@@ -512,9 +685,29 @@ function getAlterIndexesTo(entityIndexes: MigrationIndex[], dbIndexes: Migration
     add: [] as MigrationIndex[],
     drop: [] as MigrationIndex[],
   };
+
+  // 인덱스 고유 식별자 생성 (name을 제외한 모든 필드를 문자열로 변환하여 조합)
+  const identity = <T extends Record<string, unknown>>(index: T): string => {
+    const keys = Object.keys(index)
+      .filter((key) => key !== "name")
+      .sort();
+
+    return keys
+      .map((key) => {
+        if (key === "name") {
+          return undefined;
+        }
+        if (key === "columns") {
+          return (index[key] as MigrationIndex["columns"]).flatMap(identity);
+        }
+        return `${key}=${index[key as keyof MigrationIndex]}`;
+      })
+      .join("//");
+  };
+
   const extraIndexes = {
-    db: diff(dbIndexes, entityIndexes, (col) => [col.type, col.columns.join("-")].join("//")),
-    entity: diff(entityIndexes, dbIndexes, (col) => [col.type, col.columns.join("-")].join("//")),
+    db: diff(dbIndexes, entityIndexes.map(setMigrationIndexDefaults), identity),
+    entity: diff(entityIndexes.map(setMigrationIndexDefaults), dbIndexes, identity),
   };
   if (extraIndexes.entity.length > 0) {
     indexesTo.add = indexesTo.add.concat(extraIndexes.entity);
@@ -530,17 +723,27 @@ function getAlterIndexesTo(entityIndexes: MigrationIndex[], dbIndexes: Migration
  * 인덱스 삭제 정의 생성
  */
 function genIndexDropDefinition(index: MigrationIndex) {
-  const methodMap = {
-    index: "Index",
-    fulltext: "Index",
-    unique: "Unique",
-  };
-
-  return `table.drop${methodMap[index.type]}([${index.columns
-    .map((columnName) => `'${columnName}'`)
+  return `table.dropIndex([${index.columns
+    .map((column) => `'${column.name}'`)
     .join(",")}], '${index.name}')`;
 }
 
+/**
+ * DB 조회 결과와 비교하기 위한 인덱스 기본값 설정
+ */
+function setMigrationIndexDefaults(index: MigrationIndex): MigrationIndex {
+  return {
+    ...index,
+    columns: index.columns.map((col) => ({
+      ...col,
+      sortOrder: col.sortOrder ?? "ASC",
+      // sortOrder에 따라 nullsFirst의 default 값 설정
+      nullsFirst: col.nullsFirst ?? col.sortOrder === "DESC",
+    })),
+    nullsNotDistinct: index.nullsNotDistinct ?? false,
+  };
+}
+
 /**
  * 테이블 변경 케이스 - Foreign Key 변경
  */
@@ -724,12 +927,9 @@ export async function generateAlterCode(
         console.debug({ entityColumn, dbColumn });
          */
 
-  const entityIndexes = alphabetical(entitySet.indexes, (a) =>
-    [a.type, ...a.columns].join("-"),
-  );
-  const dbIndexes = alphabetical(dbSet.indexes, (a) =>
-    [a.type, ...a.columns].join("-"),
-  );
+  // ?
+  const entityIndexes = alphabetical(entitySet.indexes, (a) => [a.type, ...a.columns].join("-"));
+  const dbIndexes = alphabetical(dbSet.indexes, (a) => [a.type, ...a.columns].join("-"));
 
   const replaceNoActionOnMySQL = (f: MigrationForeign) => {
     // MySQL에서 RESTRICT와 NO ACTION은 동일함
@@ -754,9 +954,12 @@ export async function generateAlterCode(
   const alterCodes: (GenMigrationCode | GenMigrationCode[] | null)[] = [];
 
   // 1. columnsAndIndexes 처리
-  const isEqualColumns = equal(entityColumns, dbColumns);
+  const isEqualColumns = equal(
+    entityColumns.map(normalizeColumnForComparison),
+    dbColumns.map(normalizeColumnForComparison),
+  );
   const isEqualIndexes = equal(
-    entityIndexes.map((index) => omit(index, ["parser"])),
+    entityIndexes.map((index) => omit(index, ["parser"])).map(setMigrationIndexDefaults),
     dbIndexes,
   );
   if (!isEqualColumns || !isEqualIndexes) {