@rdbms-erd/core 0.1.0

package/package.json

@@ -0,0 +1,11 @@
+{
+    "name": "@rdbms-erd/core",
+    "version": "0.1.0",
+    "license": "MIT",
+    "type": "module",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": "./src/index.ts"
+    }
+}

package/src/__tests__/alignment.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { alignNodePositions } from "../alignment";
+
+describe("alignNodePositions", () => {
+  it("aligns left to min x", () => {
+    const positions = { a: { x: 10, y: 0 }, b: { x: 50, y: 0 } };
+    const out = alignNodePositions(["a", "b"], positions, "left");
+    expect(out.a.x).toBe(10);
+    expect(out.b.x).toBe(10);
+  });
+
+  it("distributes horizontal gap", () => {
+    const positions = { a: { x: 0, y: 0 }, b: { x: 100, y: 0 }, c: { x: 200, y: 0 } };
+    const out = alignNodePositions(["a", "b", "c"], positions, "h-gap");
+    expect(out.a.x).toBe(0);
+    expect(out.b.x).toBe(100);
+    expect(out.c.x).toBe(200);
+  });
+});

package/src/__tests__/benchmark.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { createLargeDesign, roundTripDesign, serializeDesign } from "../index";
+
+describe("large model (500 tables)", () => {
+  it("serializes and round-trips within reasonable time", () => {
+    const doc = createLargeDesign(500, "postgres");
+    const t0 = performance.now();
+    const json = serializeDesign(doc);
+    const parsed = roundTripDesign(JSON.parse(json) as typeof doc);
+    const ms = performance.now() - t0;
+    expect(parsed.model.tables).toHaveLength(500);
+    expect(ms).toBeLessThan(8000);
+  });
+});

package/src/__tests__/ddl-diagnostics.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { analyzeDdlDocument, createColumn, createEmptyDesign, formatDdlDiagnostic, generateDdlWithDiagnostics } from "../index";
+
+describe("analyzeDdlDocument / formatDdlDiagnostic", () => {
+  it("formats diagnostics with unified template", () => {
+    const line = formatDdlDiagnostic({
+      severity: "warning",
+      code: "DDL_REL_MISSING_COLUMNS",
+      message: "소스/타겟 컬럼이 지정되지 않아 FK DDL을 생략한다.",
+      context: "relationship:r1"
+    });
+    expect(line).toBe(
+      "[WARN][DDL_REL_MISSING_COLUMNS] 소스/타겟 컬럼이 지정되지 않아 FK DDL을 생략한다. | relationship:r1"
+    );
+  });
+
+  it("warns on relationship without column ids", () => {
+    const doc = createEmptyDesign("postgres");
+    doc.model.tables.push({
+      id: "a",
+      logicalName: "A",
+      physicalName: "TA",
+      columns: [createColumn("postgres", { id: "c1", logicalName: "x", logicalType: "TEXT" })]
+    });
+    doc.model.tables.push({
+      id: "b",
+      logicalName: "B",
+      physicalName: "TB",
+      columns: [createColumn("postgres", { id: "c2", logicalName: "y", logicalType: "TEXT" })]
+    });
+    doc.model.relationships.push({
+      id: "r1",
+      sourceTableId: "a",
+      targetTableId: "b"
+    });
+    const d = analyzeDdlDocument(doc);
+    expect(d.some((x) => x.code === "DDL_REL_MISSING_COLUMNS")).toBe(true);
+  });
+
+  it("generateDdlWithDiagnostics returns sql and same analyze list", () => {
+    const doc = createEmptyDesign("mysql");
+    doc.model.tables.push({
+      id: "t1",
+      logicalName: "T",
+      physicalName: "TT",
+      columns: [createColumn("mysql", { id: "c1", logicalName: "id", logicalType: "NUMBER", nullable: false })]
+    });
+    const { sql, diagnostics } = generateDdlWithDiagnostics(doc);
+    expect(sql).toContain("CREATE TABLE");
+    expect(diagnostics.length).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/__tests__/ddl-snapshot.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { createColumn, createEmptyDesign, generateDdl, generateIndexDdl } from "../index";
+
+function minimalDoc(dialect: "mssql" | "oracle" | "mysql" | "postgres") {
+  const doc = createEmptyDesign(dialect);
+  doc.model.tables.push({
+    id: "parent",
+    logicalName: "부모",
+    physicalName: "TB_PARENT",
+    columns: [
+      createColumn(dialect, {
+        id: "pk",
+        logicalName: "식별자",
+        logicalType: "NUMBER",
+        nullable: false
+      })
+    ]
+  });
+  doc.model.tables.push({
+    id: "child",
+    logicalName: "자식",
+    physicalName: "TB_CHILD",
+    columns: [
+      createColumn(dialect, {
+        id: "fk",
+        logicalName: "부모참조",
+        logicalType: "NUMBER",
+        nullable: false
+      })
+    ]
+  });
+  doc.model.relationships.push({
+    id: "rel1",
+    sourceTableId: "parent",
+    targetTableId: "child",
+    sourceColumnId: "pk",
+    targetColumnId: "fk"
+  });
+  doc.model.indexes.push({
+    id: "ix1",
+    tableId: "child",
+    name: "IX_CHILD_PARENT",
+    columns: ["부모참조"],
+    unique: false
+  });
+  return doc;
+}
+
+describe("generateDdl / generateIndexDdl", () => {
+  it.each(["postgres", "mysql", "oracle", "mssql"] as const)("dialect %s emits CREATE TABLE and FK", (dialect) => {
+    const sql = generateDdl(minimalDoc(dialect));
+    expect(sql).toContain("CREATE TABLE");
+    expect(sql.toUpperCase()).toContain("FOREIGN KEY");
+  });
+
+  it("emits CREATE INDEX", () => {
+    const ix = generateIndexDdl(minimalDoc("postgres"));
+    expect(ix.toUpperCase()).toContain("CREATE ");
+    expect(ix.toUpperCase()).toContain("INDEX");
+  });
+
+  it("includes PK, NOT NULL, and DEFAULT in table DDL", () => {
+    const doc = createEmptyDesign("postgres");
+    doc.model.tables.push({
+      id: "t1",
+      logicalName: "사용자",
+      physicalName: "TB_USER",
+      columns: [
+        createColumn("postgres", {
+          id: "id",
+          logicalName: "아이디",
+          physicalName: "USER_ID",
+          logicalType: "NUMBER",
+          isPrimaryKey: true
+        }),
+        createColumn("postgres", {
+          id: "name",
+          logicalName: "이름",
+          physicalName: "USER_NAME",
+          logicalType: "TEXT",
+          nullable: false,
+          defaultValue: "UNKNOWN"
+        })
+      ]
+    });
+    const sql = generateDdl(doc);
+    expect(sql).toContain("PRIMARY KEY");
+    expect(sql).toContain("NOT NULL");
+    expect(sql).toContain("DEFAULT 'UNKNOWN'");
+  });
+});

package/src/__tests__/designDocument.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import {
+  createColumn,
+  createEmptyDesign,
+  isRelationshipLineRenderable,
+  parseDesign,
+  roundTripDesign,
+  serializeDesign,
+  validateDesignDocument
+} from "../index";
+
+describe("DesignDocument", () => {
+  it("round-trips", () => {
+    const doc = createEmptyDesign("mysql");
+    doc.model.tables.push({
+      id: "t1",
+      logicalName: "엔티티",
+      physicalName: "TB_T1",
+      columns: []
+    });
+    const again = roundTripDesign(doc);
+    expect(again.model.dialect).toBe("mysql");
+    expect(again.model.tables).toHaveLength(1);
+  });
+
+  it("rejects invalid dialect", () => {
+    const raw = JSON.parse(serializeDesign(createEmptyDesign()));
+    raw.model.dialect = "sqlite";
+    expect(() => validateDesignDocument(raw)).toThrow(/dialect/);
+  });
+
+  it("parseDesign validates", () => {
+    const json = serializeDesign(createEmptyDesign("oracle"));
+    expect(parseDesign(json).model.dialect).toBe("oracle");
+  });
+
+  it("createEmptyDesign defaults to mssql", () => {
+    expect(createEmptyDesign().model.dialect).toBe("mssql");
+  });
+
+  it("isRelationshipLineRenderable respects FK column flag and global toggle", () => {
+    const doc = createEmptyDesign("postgres");
+    doc.model.tables.push(
+      {
+        id: "a",
+        logicalName: "A",
+        physicalName: "TA",
+        columns: [createColumn("postgres", { id: "apk", logicalName: "id", logicalType: "NUMBER", nullable: false, isPrimaryKey: true })]
+      },
+      {
+        id: "b",
+        logicalName: "B",
+        physicalName: "TB",
+        columns: [
+          createColumn("postgres", {
+            id: "bfk",
+            logicalName: "aid",
+            logicalType: "NUMBER",
+            isForeignKey: true,
+            showFkRelationLine: false
+          })
+        ]
+      }
+    );
+    const rel = {
+      id: "r1",
+      sourceTableId: "a",
+      targetTableId: "b",
+      sourceColumnId: "apk",
+      targetColumnId: "bfk"
+    };
+    doc.model.relationships.push(rel);
+    expect(isRelationshipLineRenderable(rel, doc.model, false)).toBe(false);
+    expect(isRelationshipLineRenderable(rel, doc.model, true)).toBe(false);
+    doc.model.tables[1].columns[0] = { ...doc.model.tables[1].columns[0], showFkRelationLine: true };
+    expect(isRelationshipLineRenderable(rel, doc.model, true)).toBe(true);
+  });
+});

package/src/__tests__/logical-physical.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { applyLogicalTypeChange, createColumn, defaultPhysicalType } from "../index";
+
+describe("logical / physical types", () => {
+  it("createColumn defaults physical name to logical name and sets default physical type", () => {
+    const col = createColumn("postgres", {
+      id: "c1",
+      logicalName: "이름",
+      logicalType: "TEXT"
+    });
+    expect(col.physicalName).toBe("이름");
+    expect(col.physicalType).toBe(defaultPhysicalType("postgres", "TEXT"));
+  });
+
+  it("createColumn uses explicit physical name when provided", () => {
+    const col = createColumn("postgres", {
+      id: "c1",
+      logicalName: "이름",
+      physicalName: "Name",
+      logicalType: "TEXT"
+    });
+    expect(col.physicalName).toBe("Name");
+  });
+
+  it("applyLogicalTypeChange resets physical to default", () => {
+    let col = createColumn("mssql", {
+      id: "c1",
+      logicalName: "수량",
+      physicalName: "Qty",
+      logicalType: "NUMBER"
+    });
+    col = { ...col, physicalType: "BIGINT" };
+    col = applyLogicalTypeChange(col, "FLOAT", "mssql");
+    expect(col.logicalType).toBe("FLOAT");
+    expect(col.physicalType).toBe(defaultPhysicalType("mssql", "FLOAT"));
+  });
+});

package/src/alignment.ts

@@ -0,0 +1,71 @@
+export type AlignCommand =
+  | "left"
+  | "h-center"
+  | "right"
+  | "top"
+  | "v-center"
+  | "bottom"
+  | "h-gap"
+  | "v-gap";
+
+/**
+ * 멀티 선택된 노드 위치를 bounding box 기준으로 정렬/분배한다.
+ * positions는 id -> 좌표 맵이며, 반환값은 동일 키에 갱신된 좌표만 포함한다.
+ */
+export function alignNodePositions(
+  selectedIds: string[],
+  positions: Record<string, { x: number; y: number }>,
+  command: AlignCommand
+): Record<string, { x: number; y: number }> {
+  const entries = selectedIds
+    .map((id) => {
+      const pos = positions[id];
+      return pos ? { id, pos: { ...pos } } : null;
+    })
+    .filter((e): e is { id: string; pos: { x: number; y: number } } => Boolean(e));
+
+  if (entries.length < 2) {
+    return {};
+  }
+
+  const xs = entries.map((e) => e.pos.x);
+  const ys = entries.map((e) => e.pos.y);
+  const minX = Math.min(...xs);
+  const maxX = Math.max(...xs);
+  const minY = Math.min(...ys);
+  const maxY = Math.max(...ys);
+  const centerX = (minX + maxX) / 2;
+  const centerY = (minY + maxY) / 2;
+
+  const sortByX = [...entries].sort((a, b) => a.pos.x - b.pos.x);
+  const sortByY = [...entries].sort((a, b) => a.pos.y - b.pos.y);
+
+  const out: Record<string, { x: number; y: number }> = {};
+
+  for (const e of entries) {
+    const next = { ...e.pos };
+    if (command === "left") next.x = minX;
+    if (command === "h-center") next.x = centerX;
+    if (command === "right") next.x = maxX;
+    if (command === "top") next.y = minY;
+    if (command === "v-center") next.y = centerY;
+    if (command === "bottom") next.y = maxY;
+    out[e.id] = next;
+  }
+
+  if (command === "h-gap") {
+    const gap = entries.length > 1 ? (maxX - minX) / (entries.length - 1) : 0;
+    sortByX.forEach((e, index) => {
+      out[e.id] = { ...e.pos, x: minX + gap * index };
+    });
+  }
+
+  if (command === "v-gap") {
+    const gap = entries.length > 1 ? (maxY - minY) / (entries.length - 1) : 0;
+    sortByY.forEach((e, index) => {
+      out[e.id] = { ...e.pos, y: minY + gap * index };
+    });
+  }
+
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,506 @@
+export type RdbmsDialect = "mssql" | "oracle" | "mysql" | "postgres";
+
+export { alignNodePositions, type AlignCommand } from "./alignment";
+
+export type LogicalDataType = "TEXT" | "DATE" | "DATETIME" | "NUMBER" | "FLOAT";
+
+export interface ColumnModel {
+  id: string;
+  logicalName: string;
+  physicalName: string;
+  logicalType: LogicalDataType;
+  physicalType: string;
+  defaultValue?: string;
+  nullable: boolean;
+  isPrimaryKey?: boolean;
+  isForeignKey?: boolean;
+  referencesPrimaryColumnId?: string;
+  /** FK 컬럼에서만 사용. false이면 캔버스에서 해당 FK 관계선을 숨긴다(전역 선 표시가 켜져 있을 때만 적용). */
+  showFkRelationLine?: boolean;
+  /** 테이블 노드에서 해당 컬럼 행 배경색 */
+  color?: string;
+}
+
+export interface TableModel {
+  id: string;
+  logicalName: string;
+  physicalName: string;
+  color?: string;
+  columns: ColumnModel[];
+}
+
+export interface RelationshipModel {
+  id: string;
+  /** 참조 원본(PK) 테이블 */
+  sourceTableId: string;
+  /** 참조 대상(FK) 테이블 */
+  targetTableId: string;
+  /** source(PK) 컬럼 id */
+  sourceColumnId?: string;
+  /** target(FK) 컬럼 id */
+  targetColumnId?: string;
+  /** 연결 시 생성된 FK 컬럼인지 여부(삭제 시 컬럼 정리용) */
+  autoCreatedTargetColumn?: boolean;
+  /** FK가 최초로 연결된 PK 컬럼 id(컬럼명 변경과 무관) */
+  originPkColumnId?: string;
+}
+
+/**
+ * 캔버스에 관계선을 그릴지 여부(전역 표시 + FK 컬럼의 라인 표시 옵션).
+ */
+export function isRelationshipLineRenderable(
+  rel: RelationshipModel,
+  model: DesignModel,
+  globalLinesVisible: boolean
+): boolean {
+  if (!globalLinesVisible) return false;
+  if (!rel.targetColumnId) return true;
+  const targetTable = model.tables.find((t) => t.id === rel.targetTableId);
+  const col = targetTable?.columns.find((c) => c.id === rel.targetColumnId);
+  if (!col) return true;
+  if (!col.isForeignKey) return true;
+  return col.showFkRelationLine !== false;
+}
+
+export interface IndexModel {
+  id: string;
+  tableId: string;
+  name: string;
+  columns: string[];
+  unique: boolean;
+}
+
+export interface DiagramLayout {
+  nodePositions: Record<string, { x: number; y: number }>;
+}
+
+export interface DesignModel {
+  dialect: RdbmsDialect;
+  tables: TableModel[];
+  relationships: RelationshipModel[];
+  indexes: IndexModel[];
+}
+
+export interface DesignDocument {
+  schemaVersion: number;
+  model: DesignModel;
+  layout: DiagramLayout;
+  settings?: Record<string, unknown>;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+const DIALECT_DEFAULT_TYPE_MAP: Record<RdbmsDialect, Record<LogicalDataType, string>> = {
+  mssql: {
+    TEXT: "NVARCHAR(255)",
+    DATE: "DATE",
+    DATETIME: "DATETIME2",
+    NUMBER: "INT",
+    FLOAT: "FLOAT"
+  },
+  oracle: {
+    TEXT: "VARCHAR2(255)",
+    DATE: "DATE",
+    DATETIME: "TIMESTAMP",
+    NUMBER: "NUMBER(10)",
+    FLOAT: "BINARY_FLOAT"
+  },
+  mysql: {
+    TEXT: "VARCHAR(255)",
+    DATE: "DATE",
+    DATETIME: "DATETIME",
+    NUMBER: "INT",
+    FLOAT: "FLOAT"
+  },
+  postgres: {
+    TEXT: "VARCHAR(255)",
+    DATE: "DATE",
+    DATETIME: "TIMESTAMP",
+    NUMBER: "INTEGER",
+    FLOAT: "REAL"
+  }
+};
+
+export function defaultPhysicalType(dialect: RdbmsDialect, logicalType: LogicalDataType): string {
+  return DIALECT_DEFAULT_TYPE_MAP[dialect][logicalType];
+}
+
+export function applyLogicalTypeChange(
+  column: ColumnModel,
+  nextLogicalType: LogicalDataType,
+  dialect: RdbmsDialect
+): ColumnModel {
+  return {
+    ...column,
+    logicalType: nextLogicalType,
+    physicalType: defaultPhysicalType(dialect, nextLogicalType)
+  };
+}
+
+export function createColumn(
+  dialect: RdbmsDialect,
+  params: {
+    id: string;
+    logicalName: string;
+    /** 생략 시 논리 이름과 동일한 물리 이름으로 생성된다. */
+    physicalName?: string;
+    logicalType: LogicalDataType;
+    defaultValue?: string;
+    nullable?: boolean;
+    isPrimaryKey?: boolean;
+    isForeignKey?: boolean;
+    referencesPrimaryColumnId?: string;
+    showFkRelationLine?: boolean;
+    color?: string;
+  }
+): ColumnModel {
+  const physicalName = params.physicalName ?? params.logicalName;
+  const isPrimaryKey = params.isPrimaryKey ?? false;
+  const isForeignKey = params.isForeignKey ?? false;
+  const col: ColumnModel = {
+    id: params.id,
+    logicalName: params.logicalName,
+    physicalName,
+    logicalType: params.logicalType,
+    physicalType: defaultPhysicalType(dialect, params.logicalType),
+    defaultValue: params.defaultValue,
+    nullable: isPrimaryKey ? false : (params.nullable ?? true),
+    isPrimaryKey,
+    isForeignKey,
+    referencesPrimaryColumnId: params.referencesPrimaryColumnId
+  };
+  if (params.color !== undefined) col.color = params.color;
+  if (isForeignKey && params.showFkRelationLine === false) col.showFkRelationLine = false;
+  return col;
+}
+
+export function createEmptyDesign(dialect: RdbmsDialect = "mssql"): DesignDocument {
+  return {
+    schemaVersion: 1,
+    model: {
+      dialect,
+      tables: [],
+      relationships: [],
+      indexes: []
+    },
+    layout: {
+      nodePositions: {}
+    }
+  };
+}
+
+export function serializeDesign(doc: DesignDocument): string {
+  return JSON.stringify(doc, null, 2);
+}
+
+export function parseDesign(json: string): DesignDocument {
+  const parsed = JSON.parse(json) as unknown;
+  return validateDesignDocument(parsed);
+}
+
+export function validateDesignDocument(input: unknown): DesignDocument {
+  if (!isObject(input)) {
+    throw new Error("Invalid design document: root must be object");
+  }
+
+  if (input.schemaVersion !== 1) {
+    throw new Error("Unsupported schemaVersion");
+  }
+
+  if (!isObject(input.model) || !Array.isArray(input.model.tables) || !Array.isArray(input.model.relationships) || !Array.isArray(input.model.indexes)) {
+    throw new Error("Invalid design document: model is malformed");
+  }
+
+  const dialects: RdbmsDialect[] = ["mssql", "oracle", "mysql", "postgres"];
+  const modelDialect = (input.model as unknown as { dialect?: unknown }).dialect;
+  if (typeof modelDialect !== "string" || !dialects.includes(modelDialect as RdbmsDialect)) {
+    throw new Error("Invalid design document: model.dialect is invalid");
+  }
+
+  if (!isObject(input.layout) || !isObject(input.layout.nodePositions)) {
+    throw new Error("Invalid design document: layout is malformed");
+  }
+
+  return input as unknown as DesignDocument;
+}
+
+export function roundTripDesign(doc: DesignDocument): DesignDocument {
+  return parseDesign(serializeDesign(doc));
+}
+
+function quoteIdentifier(dialect: RdbmsDialect, identifier: string): string {
+  if (dialect === "mssql") return `[${identifier}]`;
+  if (dialect === "mysql") return `\`${identifier}\``;
+  return `"${identifier}"`;
+}
+
+function quoteSqlString(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function toDefaultExpression(dialect: RdbmsDialect, col: ColumnModel): string | null {
+  const raw = col.defaultValue?.trim();
+  if (!raw) return null;
+  const upper = raw.toUpperCase();
+  const isFunctionLike = /[()]/.test(raw) || upper === "NULL" || upper === "CURRENT_TIMESTAMP" || upper === "CURRENT_DATE";
+  if (isFunctionLike) return raw;
+  if (col.logicalType === "NUMBER" || col.logicalType === "FLOAT") return raw;
+  if (col.logicalType === "DATE" || col.logicalType === "DATETIME") {
+    if (dialect === "mssql" && upper === "NOW") return "GETDATE()";
+    if (upper === "NOW") return "CURRENT_TIMESTAMP";
+    return quoteSqlString(raw);
+  }
+  if ((raw.startsWith("'") && raw.endsWith("'")) || (raw.startsWith('"') && raw.endsWith('"'))) {
+    return raw;
+  }
+  return quoteSqlString(raw);
+}
+
+function joinColumnDefs(table: TableModel, dialect: RdbmsDialect): string[] {
+  const defs = table.columns.map((col) => {
+    const nullable = col.nullable ? "NULL" : "NOT NULL";
+    const defaultExpr = toDefaultExpression(dialect, col);
+    const defaultSql = defaultExpr ? ` DEFAULT ${defaultExpr}` : "";
+    return `  ${quoteIdentifier(dialect, col.physicalName)} ${col.physicalType}${defaultSql} ${nullable}`;
+  });
+  const pkColumns = table.columns.filter((col) => col.isPrimaryKey).map((col) => quoteIdentifier(dialect, col.physicalName));
+  if (pkColumns.length > 0) {
+    defs.push(`  PRIMARY KEY (${pkColumns.join(", ")})`);
+  }
+  return defs;
+}
+
+function createTableSql(table: TableModel, dialect: RdbmsDialect): string {
+  const columns = joinColumnDefs(table, dialect);
+  return `CREATE TABLE ${quoteIdentifier(dialect, table.physicalName)} (\n${columns.join(",\n")}\n);`;
+}
+
+function createRelationshipSql(
+  rel: RelationshipModel,
+  model: DesignModel,
+  dialect: RdbmsDialect,
+  index: number
+): string | null {
+  const sourceTable = model.tables.find((table) => table.id === rel.sourceTableId);
+  const targetTable = model.tables.find((table) => table.id === rel.targetTableId);
+  if (!sourceTable || !targetTable || !rel.sourceColumnId || !rel.targetColumnId) {
+    return null;
+  }
+
+  const sourceColumn = sourceTable.columns.find((col) => col.id === rel.sourceColumnId);
+  const targetColumn = targetTable.columns.find((col) => col.id === rel.targetColumnId);
+  if (!sourceColumn || !targetColumn) {
+    return null;
+  }
+
+  const fkName = `FK_${targetTable.physicalName}_${sourceTable.physicalName}_${index + 1}`;
+  return [
+    `ALTER TABLE ${quoteIdentifier(dialect, targetTable.physicalName)}`,
+    `  ADD CONSTRAINT ${quoteIdentifier(dialect, fkName)}`,
+    `  FOREIGN KEY (${quoteIdentifier(dialect, targetColumn.physicalName)})`,
+    `  REFERENCES ${quoteIdentifier(dialect, sourceTable.physicalName)} (${quoteIdentifier(dialect, sourceColumn.physicalName)});`
+  ].join("\n");
+}
+
+function createIndexSql(indexModel: IndexModel, model: DesignModel, dialect: RdbmsDialect): string | null {
+  const table = model.tables.find((item) => item.id === indexModel.tableId);
+  if (!table || indexModel.columns.length === 0) {
+    return null;
+  }
+  const unique = indexModel.unique ? "UNIQUE " : "";
+  const columns = indexModel.columns.map((col) => quoteIdentifier(dialect, col)).join(", ");
+  return `CREATE ${unique}INDEX ${quoteIdentifier(dialect, indexModel.name)} ON ${quoteIdentifier(dialect, table.physicalName)} (${columns});`;
+}
+
+function buildDdlSql(doc: DesignDocument): string {
+  const { model } = doc;
+  const tableSql = model.tables.map((table) => createTableSql(table, model.dialect));
+  const relSql = model.relationships
+    .map((rel, index) => createRelationshipSql(rel, model, model.dialect, index))
+    .filter((item): item is string => Boolean(item));
+  return [...tableSql, ...relSql].join("\n\n");
+}
+
+function buildIndexDdlSql(doc: DesignDocument): string {
+  const { model } = doc;
+  const statements = model.indexes
+    .map((index) => createIndexSql(index, model, model.dialect))
+    .filter((item): item is string => Boolean(item));
+  return statements.join("\n\n");
+}
+
+/** DDL/인덱스 분석 공통 심각도 */
+export type DdlDiagnosticSeverity = "error" | "warning";
+
+/** 구조화된 DDL 관련 진단(에러·경고) */
+export interface DdlDiagnostic {
+  severity: DdlDiagnosticSeverity;
+  code: string;
+  message: string;
+  /** 예: relationship:rel1, index:ix1, table:t1 */
+  context?: string;
+}
+
+/**
+ * 통일된 한 줄 텍스트 포맷.
+ * 예: `[WARN][DDL_REL_MISSING_COLUMNS] ... | relationship:rel1`
+ */
+export function formatDdlDiagnostic(d: DdlDiagnostic): string {
+  const level = d.severity === "error" ? "ERROR" : "WARN";
+  const tail = d.context ? ` | ${d.context}` : "";
+  return `[${level}][${d.code}] ${d.message}${tail}`;
+}
+
+export function formatDdlDiagnostics(diagnostics: DdlDiagnostic[]): string {
+  return diagnostics.map(formatDdlDiagnostic).join("\n");
+}
+
+/**
+ * 모델 전체에 대한 DDL·인덱스 관련 진단(테이블/관계/인덱스).
+ * 검증 예외(Invalid design document)와는 별도로, 생성 가능 여부와 경고를 나열한다.
+ */
+export function analyzeDdlDocument(doc: DesignDocument): DdlDiagnostic[] {
+  const out: DdlDiagnostic[] = [];
+  const { model } = doc;
+  const tableById = new Map(model.tables.map((t) => [t.id, t]));
+  const physicalTableNames = new Map<string, string[]>();
+
+  for (const table of model.tables) {
+    const list = physicalTableNames.get(table.physicalName) ?? [];
+    list.push(table.id);
+    physicalTableNames.set(table.physicalName, list);
+    if (table.columns.length === 0) {
+      out.push({
+        severity: "warning",
+        code: "DDL_EMPTY_TABLE",
+        message: "컬럼이 없는 테이블은 CREATE TABLE 구문이 비어 있거나 무의미할 수 있다.",
+        context: `table:${table.id}`
+      });
+    }
+  }
+
+  for (const [name, ids] of physicalTableNames) {
+    if (ids.length > 1) {
+      out.push({
+        severity: "warning",
+        code: "DDL_DUPLICATE_TABLE_NAME",
+        message: `동일한 물리 테이블명 "${name}"이 ${ids.length}개 테이블에 사용되었다.`,
+        context: `tables:${ids.join(",")}`
+      });
+    }
+  }
+
+  for (const rel of model.relationships) {
+    const ctx = `relationship:${rel.id}`;
+    const sourceTable = tableById.get(rel.sourceTableId);
+    const targetTable = tableById.get(rel.targetTableId);
+    if (!sourceTable || !targetTable) {
+      out.push({
+        severity: "error",
+        code: "DDL_REL_UNKNOWN_TABLE",
+        message: "관계의 소스 또는 타겟 테이블을 찾을 수 없어 FK DDL을 생성할 수 없다.",
+        context: ctx
+      });
+      continue;
+    }
+    if (!rel.sourceColumnId || !rel.targetColumnId) {
+      out.push({
+        severity: "warning",
+        code: "DDL_REL_MISSING_COLUMNS",
+        message: "소스/타겟 컬럼이 지정되지 않아 FK DDL을 생략한다.",
+        context: ctx
+      });
+      continue;
+    }
+    const sourceColumn = sourceTable.columns.find((c) => c.id === rel.sourceColumnId);
+    const targetColumn = targetTable.columns.find((c) => c.id === rel.targetColumnId);
+    if (!sourceColumn || !targetColumn) {
+      out.push({
+        severity: "warning",
+        code: "DDL_REL_UNKNOWN_COLUMN",
+        message: "관계에 지정된 컬럼 id를 테이블에서 찾을 수 없어 FK DDL을 생략한다.",
+        context: ctx
+      });
+    }
+  }
+
+  for (const indexModel of model.indexes) {
+    const ctx = `index:${indexModel.id}`;
+    const table = tableById.get(indexModel.tableId);
+    if (!table) {
+      out.push({
+        severity: "warning",
+        code: "IDX_UNKNOWN_TABLE",
+        message: "인덱스가 가리키는 테이블을 찾을 수 없어 인덱스 DDL을 생략한다.",
+        context: ctx
+      });
+      continue;
+    }
+    if (indexModel.columns.length === 0) {
+      out.push({
+        severity: "warning",
+        code: "IDX_EMPTY_COLUMNS",
+        message: "인덱스 컬럼 목록이 비어 있어 인덱스 DDL을 생략한다.",
+        context: ctx
+      });
+      continue;
+    }
+    for (const colPhys of indexModel.columns) {
+      if (!table.columns.some((c) => c.physicalName === colPhys)) {
+        out.push({
+          severity: "warning",
+          code: "IDX_UNKNOWN_COLUMN",
+          message: `인덱스가 참조하는 물리 컬럼명 "${colPhys}"을(를) 테이블 "${table.physicalName}"에서 찾을 수 없다.`,
+          context: ctx
+        });
+      }
+    }
+  }
+
+  return out;
+}
+
+export function generateDdlWithDiagnostics(doc: DesignDocument): { sql: string; diagnostics: DdlDiagnostic[] } {
+  return { sql: buildDdlSql(doc), diagnostics: analyzeDdlDocument(doc) };
+}
+
+export function generateIndexDdlWithDiagnostics(doc: DesignDocument): { sql: string; diagnostics: DdlDiagnostic[] } {
+  return { sql: buildIndexDdlSql(doc), diagnostics: analyzeDdlDocument(doc) };
+}
+
+export function generateDdl(doc: DesignDocument): string {
+  return buildDdlSql(doc);
+}
+
+export function generateIndexDdl(doc: DesignDocument): string {
+  return buildIndexDdlSql(doc);
+}
+
+/** 성능·부하 테스트용: 지정 개수의 빈 테이블과 격자 레이아웃을 생성한다. */
+export function createLargeDesign(tableCount: number, dialect: RdbmsDialect = "postgres"): DesignDocument {
+  const doc = createEmptyDesign(dialect);
+  const cols = 20;
+  for (let i = 0; i < tableCount; i++) {
+    const id = `t-${i}`;
+    doc.model.tables.push({
+      id,
+      logicalName: `엔티티${i}`,
+      physicalName: `TB_T${i}`,
+      columns: [
+        createColumn(dialect, {
+          id: `${id}-pk`,
+          logicalName: "식별자",
+          logicalType: "NUMBER",
+          nullable: false
+        })
+      ]
+    });
+    doc.layout.nodePositions[id] = {
+      x: (i % cols) * 220,
+      y: Math.floor(i / cols) * 120
+    };
+  }
+  return doc;
+}