mega-framework 0.1.6 → 0.1.8

package/src/core/migration/dialects/postgres.js

@@ -0,0 +1,563 @@
+// @ts-check
+/**
+ * PostgreSQL dialect (ADR-204) — differ 가 산출한 변경 연산(op)을 SQL 문자열(up/down 쌍)로 렌더한다.
+ *
+ * # 명명 표준 (diff 안정성의 핵심 — 이름이 흔들리면 변경이 drop+add 로 오판된다)
+ *   - 인덱스: `idx_<table>_<col1>_<col2>` (UNIQUE 인덱스: `uniq_<table>_<cols>`)
+ *   - UNIQUE 제약: `uniq_<table>_<col>`
+ *   - FK: `fk_<table>_<col>_<reftable>`
+ *   - CHECK: `chk_<table>_<col>` (사용자 지정 name 우선)
+ *   - PRIMARY KEY(복합): `pk_<table>`
+ *
+ * # 렌더 원칙
+ *   - 식별자는 필요할 때만 따옴표(`"camelCase"` 등) — 소문자 snake 는 bare 로 가독성 유지.
+ *   - enum 은 `TEXT` + `CHECK (col IN (...))` — native enum 타입 미사용(값 변경이 제약 교체로 단순).
+ *   - FK 는 CREATE TABLE 인라인이 아니라 **별도 ADD CONSTRAINT** — 같은 마이그레이션 안에서
+ *     상호 참조하는 새 테이블들의 생성 순서 문제를 제거한다(differ 가 createTable 뒤에 addFk 를 배치).
+ *   - 파괴적 변경(DROP TABLE/COLUMN)·위험 캐스트(ALTER TYPE)는 SQL 안에 경고/TODO 주석을 박는다
+ *     (silent 손실 금지 — 사용자가 적용 전 검토).
+ *
+ * @module core/migration/dialects/postgres
+ */
+import { MegaConfigError } from '../../../errors/config-error.js'
+
+// ── dialect 표준 인터페이스 속성 (ADR-205 — dialects/README.md 가 contract 정본) ─────────────
+/** 식별자 최대 길이(byte) — postgres NAMEDATALEN-1. 초과는 절단·충돌 위험이라 fail-fast(정책 2). */
+export const identifierMaxBytes = 63
+/** CREATE INDEX CONCURRENTLY 지원(트랜잭션 밖 실행 필요 — generate --concurrent 옵트인). */
+export const supportsConcurrentIndex = true
+/** enum 표현 전략 — 'check' = TEXT + CHECK(col IN (...)). (maria 는 'enum-type' 예정.) */
+export const enumStrategy = 'check'
+/** RENAME COLUMN 의 트랜잭션 내 실행 지원. */
+export const supportsRenameInTx = true
+/** DROP COLUMN 의 트랜잭션 내 롤백 가능(maria 는 DDL 암묵 commit 으로 false 예정). */
+export const canDropColumnInTx = true
+/** 일부 ALTER 가 테이블 재생성을 요구하는지(sqlite true 예정). */
+export const dependsOnRebuild = false
+/** ALTER TABLE ... RENAME CONSTRAINT 지원(postgres 9.2+). 미지원 dialect 는 DROP+ADD 로 대체. */
+export const supportsRenameConstraint = true
+/** ALTER 로 FK 추가/삭제 가능 — false(sqlite)면 FK 는 CREATE TABLE 인라인 + 변경은 rebuild. */
+export const supportsAlterAddFk = true
+/** FK 걸린 컬럼 DROP 전 dropFk 선행 필요 여부 — postgres 는 의존 객체 cascade 라 불필요. */
+export const requiresDropFkBeforeDropColumn = false
+/** SQL DDL 렌더 dialect — 생성 파일이 `db.query(sql)` 계약을 쓴다(mongo 와 분기, ADR-209). */
+export const usesSqlDdl = true
+
+/** bare 로 둘 수 있는 식별자 — 그 외(camelCase·예약어 충돌 가능성)는 따옴표. */
+const BARE_IDENT_RE = /^[a-z_][a-z0-9_]*$/
+
+/**
+ * SQL 식별자 인용 — 필요할 때만 `"..."`. **모든 식별자가 지나는 단일 깔때기**라 여기서
+ * 63byte 초과를 fail-fast 한다 — postgres 는 NOTICE 와 함께 조용히 절단해 이름 충돌·
+ * `migrate:status` 표기 불일치를 만들기 때문(자동 축약 없이 거부, 정책 2).
+ *
+ * @param {string} name @returns {string}
+ * @throws {MegaConfigError} `migration.identifier_too_long` - 63byte 초과(합성 이름 포함).
+ */
+export function quoteIdent(name) {
+  if (Buffer.byteLength(name, 'utf8') > identifierMaxBytes) {
+    throw new MegaConfigError(
+      'migration.identifier_too_long',
+      `식별자 '${name}' 가 postgres 한도(${identifierMaxBytes}byte)를 초과합니다 — 절단 시 이름 충돌 위험이 있어 거부합니다. ` +
+        '테이블/컬럼 이름을 줄이거나, 합성 이름(idx_/fk_ 등)이 문제라면 .unique({name})/.references(...,{name})/t.index(...,{name}) 으로 짧은 이름을 명시하세요.',
+      { details: { identifier: name, bytes: Buffer.byteLength(name, 'utf8'), max: identifierMaxBytes } },
+    )
+  }
+  if (BARE_IDENT_RE.test(name)) return name
+  return `"${name.replaceAll('"', '""')}"`
+}
+
+/**
+ * DEFAULT/CHECK 용 literal 렌더 — 문자열은 단일따옴표 escape, `{ raw }` 는 검증된 식 그대로.
+ * @param {unknown} value @returns {string}
+ */
+export function renderLiteral(value) {
+  if (value === null) return 'NULL'
+  if (typeof value === 'number') {
+    // NaN/Infinity 는 SQL literal 이 아니다 — invalid SQL 을 만들기 전에 거부.
+    if (!Number.isFinite(value)) {
+      throw new MegaConfigError('migration.schema_invalid', `default 값이 유한한 수가 아닙니다: ${value}`, { details: { value: String(value) } })
+    }
+    return String(value)
+  }
+  if (typeof value === 'boolean') return value ? 'TRUE' : 'FALSE'
+  if (typeof value === 'object' && value !== null && typeof (/** @type {any} */ (value).raw) === 'string') {
+    return /** @type {any} */ (value).raw
+  }
+  return `'${String(value).replaceAll("'", "''")}'`
+}
+
+/** dialect 표준 인터페이스 별칭 — 값 인용(SQL injection 방지 깔때기). @type {typeof renderLiteral} */
+export const quoteLiteral = renderLiteral
+
+/**
+ * 컬럼 타입 → postgres SQL 타입.
+ * @param {Record<string, any>} def @param {{ forAlter?: boolean }} [opts] - forAlter: ALTER TYPE 대상
+ *   (SERIAL 은 타입이 아니라 시퀀스 단축문법이라 INTEGER/BIGINT 로 강등).
+ * @returns {string}
+ */
+export function typeSql(def, { forAlter = false } = {}) {
+  switch (def.type) {
+    case 'serial':
+      return forAlter ? 'INTEGER' : 'SERIAL'
+    case 'bigSerial':
+      return forAlter ? 'BIGINT' : 'BIGSERIAL'
+    case 'integer':
+      return 'INTEGER'
+    case 'bigInteger':
+      return 'BIGINT'
+    case 'smallInteger':
+      return 'SMALLINT'
+    case 'real':
+      return 'REAL'
+    case 'doublePrecision':
+      return 'DOUBLE PRECISION'
+    case 'decimal':
+      return `NUMERIC(${def.precision}, ${def.scale})`
+    case 'varchar':
+      return `VARCHAR(${def.length})`
+    case 'text':
+      return 'TEXT'
+    case 'char':
+      return `CHAR(${def.length})`
+    case 'boolean':
+      return 'BOOLEAN'
+    case 'timestamp':
+      return 'TIMESTAMP'
+    case 'timestamptz':
+      return 'TIMESTAMPTZ'
+    case 'date':
+      return 'DATE'
+    case 'time':
+      return 'TIME'
+    case 'uuid':
+      return 'UUID'
+    case 'json':
+      return 'JSON'
+    case 'jsonb':
+      return 'JSONB'
+    case 'enum':
+      return 'TEXT'
+    case 'bytea':
+      return 'BYTEA'
+    default:
+      throw new MegaConfigError('migration.schema_invalid', `postgres dialect: 알 수 없는 타입 '${def.type}'.`, { details: { type: def.type } })
+  }
+}
+
+// ── 명명 표준 ────────────────────────────────────────────────────────────────
+/** @param {string} table @param {string[]} cols @param {boolean} [unique] @returns {string} */
+export function indexName(table, cols, unique = false) {
+  return `${unique ? 'uniq' : 'idx'}_${table}_${cols.join('_')}`
+}
+/** @param {string} table @param {Record<string, any>} ix @returns {string} 인덱스 정의의 유효 이름. */
+export function resolveIndexName(table, ix) {
+  if (ix.name !== undefined) return ix.name
+  if (ix.expression !== undefined) {
+    throw new MegaConfigError('migration.schema_invalid', `표현식 인덱스는 name 이 필수입니다 (table '${table}', expression '${ix.expression}').`, {
+      details: { table, expression: ix.expression },
+    })
+  }
+  return indexName(table, ix.columns, ix.unique === true)
+}
+/** @param {string} table @param {string} col @returns {string} */
+export function uniqueName(table, col) {
+  return `uniq_${table}_${col}`
+}
+/** @param {string} table @param {string} col @param {string} refTable @returns {string} */
+export function fkName(table, col, refTable) {
+  return `fk_${table}_${col}_${refTable}`
+}
+/** @param {string} table @param {string} col @returns {string} */
+export function checkName(table, col) {
+  return `chk_${table}_${col}`
+}
+/** @param {string} table @returns {string} */
+export function pkName(table) {
+  return `pk_${table}`
+}
+/** CREATE TABLE 인라인 단일 PK 의 서버 자동 명명. @param {string} table @returns {string} */
+export function inlinePkName(table) {
+  return `${table}_pkey`
+}
+
+/**
+ * enum 컬럼의 CHECK 식 — **유일한 enum CHECK 렌더 지점**(differ 는 values 만 전달, ADR-205 H-1).
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col, values) {
+  return `${quoteIdent(col)} IN (${values.map((v) => renderLiteral(v)).join(', ')})`
+}
+
+/**
+ * 컬럼 정의 조각(타입 + NOT NULL + DEFAULT [+ PRIMARY KEY]) — CREATE TABLE/ADD COLUMN 공용.
+ * unique/check/fk 는 별도 제약 연산으로 렌더한다(명명 표준 유지·드롭 가능).
+ * @param {string} name @param {Record<string, any>} def @param {{ inlinePrimary?: boolean }} [opts]
+ * @returns {string}
+ */
+function columnClause(name, def, { inlinePrimary = true } = {}) {
+  let sql = `${quoteIdent(name)} ${typeSql(def)}`
+  if (def.notNull === true) sql += ' NOT NULL'
+  if (def.default !== undefined) sql += ` DEFAULT ${renderLiteral(def.default)}`
+  if (inlinePrimary && def.primary === true) sql += ' PRIMARY KEY'
+  return sql
+}
+
+/**
+ * 한 컬럼의 부속 제약(UNIQUE/CHECK/enum CHECK) ADD CONSTRAINT 문 목록 — FK 는 differ 가 별도 op 로.
+ * @param {string} table @param {string} col @param {Record<string, any>} def
+ * @returns {string[]}
+ */
+function columnConstraintStatements(table, col, def) {
+  /** @type {string[]} */
+  const out = []
+  if (def.unique !== undefined) {
+    const name = def.unique === true ? uniqueName(table, col) : def.unique.name
+    out.push(`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(name)} UNIQUE (${quoteIdent(col)})`)
+  }
+  if (def.type === 'enum') {
+    const name = def.enumName ?? checkName(table, col)
+    out.push(`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(name)} CHECK (${enumCheckExpr(col, def.values)})`)
+  }
+  if (def.check !== undefined) {
+    const name = def.check.name ?? checkName(table, col)
+    out.push(`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(name)} CHECK (${def.check.expr})`)
+  }
+  return out
+}
+
+/** FK ADD CONSTRAINT 문. @param {string} table @param {string} col @param {Record<string, any>} ref @returns {string} */
+function fkAddStatement(table, col, ref) {
+  const name = ref.name ?? fkName(table, col, ref.table)
+  let sql = `ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(name)} FOREIGN KEY (${quoteIdent(col)}) REFERENCES ${quoteIdent(ref.table)} (${quoteIdent(ref.column)})`
+  if (ref.onDelete !== undefined) sql += ` ON DELETE ${ref.onDelete.toUpperCase()}`
+  if (ref.onUpdate !== undefined) sql += ` ON UPDATE ${ref.onUpdate.toUpperCase()}`
+  return sql
+}
+
+/** FK DROP CONSTRAINT 문. @param {string} table @param {string} col @param {Record<string, any>} ref @returns {string} */
+function fkDropStatement(table, col, ref) {
+  return `ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(ref.name ?? fkName(table, col, ref.table))}`
+}
+
+/**
+ * CREATE INDEX 문. concurrent=true 면 `CONCURRENTLY`(쓰기 비블로킹 — 단 트랜잭션 밖 실행 필요,
+ * generate --concurrent 가 no-tx 마이그레이션으로 묶는다).
+ * @param {string} table @param {Record<string, any>} ix @param {{ concurrent?: boolean }} [opts]
+ * @returns {string}
+ */
+function indexCreateStatement(table, ix, { concurrent = false } = {}) {
+  const name = resolveIndexName(table, ix)
+  const target = ix.expression !== undefined ? `(${ix.expression})` : `(${ix.columns.map(quoteIdent).join(', ')})`
+  let sql = `CREATE ${ix.unique === true ? 'UNIQUE ' : ''}INDEX ${concurrent ? 'CONCURRENTLY ' : ''}${quoteIdent(name)} ON ${quoteIdent(table)}`
+  if (ix.using !== undefined) sql += ` USING ${ix.using}`
+  sql += ` ${target}`
+  if (ix.where !== undefined) sql += ` WHERE ${ix.where}`
+  return sql
+}
+
+/** COMMENT ON COLUMN 문. @param {string} table @param {string} col @param {string | null} text @returns {string} */
+function commentStatement(table, col, text) {
+  return `COMMENT ON COLUMN ${quoteIdent(table)}.${quoteIdent(col)} IS ${text === null ? 'NULL' : renderLiteral(text)}`
+}
+
+/**
+ * CREATE TABLE 문(+부속 제약/코멘트) — FK·인덱스 제외(별도 op).
+ * @param {Record<string, any>} record
+ * @returns {string[]}
+ */
+function createTableStatements(record) {
+  const table = record.table
+  /** @type {string[]} */
+  const lines = []
+  for (const [name, def] of Object.entries(record.columns)) {
+    lines.push('  ' + columnClause(name, def))
+  }
+  if (record.primaryKey !== undefined) {
+    lines.push(`  CONSTRAINT ${quoteIdent(pkName(table))} PRIMARY KEY (${record.primaryKey.map(quoteIdent).join(', ')})`)
+  }
+  /** @type {string[]} */
+  const out = [`CREATE TABLE ${quoteIdent(table)} (\n${lines.join(',\n')}\n)`]
+  for (const [name, def] of Object.entries(record.columns)) {
+    out.push(...columnConstraintStatements(table, name, def))
+    if (def.comment !== undefined) out.push(commentStatement(table, name, def.comment))
+  }
+  return out
+}
+
+/**
+ * ALTER TYPE 시 implicit cast 가 보장되지 않아 USING 식 검토가 필요한지. 안전 목록(정수 확장·
+ * varchar↔text·decimal 정밀도·timestamp↔timestamptz·길이 변경) 밖이면 true.
+ * @param {Record<string, any>} from @param {Record<string, any>} to @returns {boolean}
+ */
+export function isRiskyCast(from, to) {
+  const f = from.type
+  const t = to.type
+  if (f === t) return false // 같은 타입의 파라미터 변경(길이·정밀도)
+  const intFamily = ['smallInteger', 'integer', 'bigInteger', 'serial', 'bigSerial']
+  if (intFamily.includes(f) && intFamily.includes(t)) return false
+  const textFamily = ['varchar', 'text', 'char', 'enum']
+  if (textFamily.includes(f) && textFamily.includes(t)) return false
+  if ((f === 'timestamp' && t === 'timestamptz') || (f === 'timestamptz' && t === 'timestamp')) return false
+  if ((f === 'real' || f === 'doublePrecision' || f === 'decimal') && (t === 'real' || t === 'doublePrecision' || t === 'decimal')) return false
+  return true
+}
+
+/**
+ * 같은 타입의 길이/정밀도 **축소** 인지 — varchar(200→50)·decimal(12,2→8,2) 등. implicit cast 는
+ * 존재해 isRiskyCast 로는 안 잡히지만, 기존 데이터가 한도를 넘으면 적용이 실패하거나(varchar)
+ * 반올림·잘림이 생긴다 — 경고 주석 대상.
+ * @param {Record<string, any>} from @param {Record<string, any>} to @returns {boolean}
+ */
+export function isNarrowing(from, to) {
+  if (from.type !== to.type) return false
+  if (typeof from.length === 'number' && typeof to.length === 'number' && to.length < from.length) return true
+  if (typeof from.precision === 'number' && typeof to.precision === 'number' && to.precision < from.precision) return true
+  if (typeof from.scale === 'number' && typeof to.scale === 'number' && to.scale < from.scale) return true
+  return false
+}
+
+/**
+ * ALTER TYPE 문(위험 캐스트면 TODO, 같은-타입 축소면 경고 주석 동반).
+ * @param {string} table @param {string} col @param {Record<string, any>} from @param {Record<string, any>} to
+ * @returns {string}
+ */
+function alterTypeStatement(table, col, from, to) {
+  const target = typeSql(to, { forAlter: true })
+  let sql = `ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(col)} TYPE ${target}`
+  if (isRiskyCast(from, to)) {
+    sql = `-- TODO: implicit cast 가 없으면 적용이 실패합니다 — USING ${quoteIdent(col)}::${target} 등 캐스트 식을 검토·추가하세요.\n${sql}`
+  }
+  if (isNarrowing(from, to)) {
+    sql = `-- 경고: 길이/정밀도 축소 — 한도를 넘는 기존 데이터가 있으면 적용이 실패하거나 잘림/반올림이 발생합니다. 적용 전 데이터 분포를 확인하세요.\n${sql}`
+  }
+  return sql
+}
+
+/**
+ * 변경 연산(op) 1개 → `{ up: string[], down: string[] }`.
+ * op 종류·필드는 {@link module:core/migration/differ} 가 정본.
+ *
+ * @param {Record<string, any>} op
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOp(op) {
+  const table = op.table
+  switch (op.kind) {
+    case 'createTable':
+      return {
+        up: createTableStatements(op.record),
+        down: [`DROP TABLE IF EXISTS ${quoteIdent(table)}`],
+      }
+    case 'dropTable': {
+      // down = 구조 복원 — 테이블·제약·코멘트(createTableStatements) + 인덱스(DROP TABLE 이 암묵
+      // 제거하므로 여기서 재생). 보유 FK 는 differ 가 별도 dropFk op 를 선행 발행하므로(의존 순서
+      // 보장) 그 op 의 down 이 복원한다 — 여기서 또 추가하면 down 에서 중복 ADD CONSTRAINT 가 된다.
+      const down = createTableStatements(op.record)
+      for (const ix of op.record.indexes ?? []) down.push(indexCreateStatement(table, ix))
+      return {
+        up: [
+          `-- 경고: 테이블과 모든 데이터가 영구 삭제됩니다 — down 으로 구조(제약·인덱스 포함)는 복원되지만 데이터는 복원되지 않습니다.\nDROP TABLE IF EXISTS ${quoteIdent(table)}`,
+        ],
+        down,
+      }
+    }
+    case 'addColumn': {
+      /** @type {string[]} */
+      const up = []
+      let add = `ALTER TABLE ${quoteIdent(table)} ADD COLUMN ${columnClause(op.column, op.def, { inlinePrimary: false })}`
+      if (op.def.notNull === true && op.def.default === undefined) {
+        add = `-- 경고: 기존 행이 있으면 NOT NULL 컬럼 추가가 실패합니다 — DEFAULT 를 지정하거나 backfill 후 NOT NULL 을 거세요.\n${add}`
+      }
+      up.push(add)
+      up.push(...columnConstraintStatements(table, op.column, op.def))
+      if (op.def.comment !== undefined) up.push(commentStatement(table, op.column, op.def.comment))
+      return {
+        up,
+        down: [`-- 경고: 컬럼 데이터가 영구 삭제됩니다.\nALTER TABLE ${quoteIdent(table)} DROP COLUMN ${quoteIdent(op.column)}`],
+      }
+    }
+    case 'dropColumn': {
+      // 컬럼 DROP 은 부속 제약(unique/check/fk)도 함께 제거된다(postgres 의존 객체 정리).
+      /** @type {string[]} */
+      const down = [
+        `-- 경고: 구조만 복원됩니다 — 삭제된 컬럼 데이터는 down 으로 복원되지 않습니다.\nALTER TABLE ${quoteIdent(table)} ADD COLUMN ${columnClause(op.column, op.def, { inlinePrimary: false })}`,
+      ]
+      down.push(...columnConstraintStatements(table, op.column, op.def))
+      if (op.def.references !== undefined) down.push(fkAddStatement(table, op.column, op.def.references))
+      if (op.def.comment !== undefined) down.push(commentStatement(table, op.column, op.def.comment))
+      return {
+        up: [`-- 경고: 컬럼 데이터가 영구 삭제됩니다.\nALTER TABLE ${quoteIdent(table)} DROP COLUMN ${quoteIdent(op.column)}`],
+        down,
+      }
+    }
+    case 'renameColumn':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} RENAME COLUMN ${quoteIdent(op.from)} TO ${quoteIdent(op.to)}`],
+        down: [`ALTER TABLE ${quoteIdent(table)} RENAME COLUMN ${quoteIdent(op.to)} TO ${quoteIdent(op.from)}`],
+      }
+    case 'alterType':
+      return {
+        up: [alterTypeStatement(table, op.column, op.from, op.to)],
+        down: [alterTypeStatement(table, op.column, op.to, op.from)],
+      }
+    case 'setNotNull':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} SET NOT NULL`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} DROP NOT NULL`],
+      }
+    case 'dropNotNull':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} DROP NOT NULL`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} SET NOT NULL`],
+      }
+    case 'setDefault':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} SET DEFAULT ${renderLiteral(op.value)}`],
+        down: [
+          op.prev === undefined
+            ? `ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} DROP DEFAULT`
+            : `ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} SET DEFAULT ${renderLiteral(op.prev)}`,
+        ],
+      }
+    case 'dropDefault':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} DROP DEFAULT`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} SET DEFAULT ${renderLiteral(op.prev)}`],
+      }
+    case 'addUnique':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(op.name)} UNIQUE (${quoteIdent(op.column)})`],
+        down: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(op.name)}`],
+      }
+    case 'dropUnique':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(op.name)}`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(op.name)} UNIQUE (${quoteIdent(op.column)})`],
+      }
+    // CHECK 식: enum 은 op.values 로 받아 **dialect 가 렌더**한다(식별자 인용 일원화 — differ 의
+    // 비인용 식이 camelCase 컬럼에서 적용 실패하던 결함 교정). 명시 check 는 expr 그대로.
+    case 'addCheck': {
+      const expr = op.values !== undefined ? enumCheckExpr(op.column, op.values) : op.expr
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(op.name)} CHECK (${expr})`],
+        down: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(op.name)}`],
+      }
+    }
+    case 'dropCheck': {
+      const expr = op.values !== undefined ? enumCheckExpr(op.column, op.values) : op.expr
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(op.name)}`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(op.name)} CHECK (${expr})`],
+      }
+    }
+    case 'addFk':
+      return {
+        up: [fkAddStatement(table, op.column, op.ref)],
+        down: [fkDropStatement(table, op.column, op.ref)],
+      }
+    case 'dropFk':
+      return {
+        up: [fkDropStatement(table, op.column, op.ref)],
+        down: [fkAddStatement(table, op.column, op.ref)],
+      }
+    // 컬럼 rename 시 FK 기본 이름(fk_<table>_<col>_<ref>) 동기화 — 실 DB 제약 이름과 명명 표준의
+    // 드리프트 방지(이후 FK 변경 마이그레이션이 옛 이름을 못 찾는 결함 교정).
+    case 'renameFk':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} RENAME CONSTRAINT ${quoteIdent(op.from)} TO ${quoteIdent(op.to)}`],
+        down: [`ALTER TABLE ${quoteIdent(table)} RENAME CONSTRAINT ${quoteIdent(op.to)} TO ${quoteIdent(op.from)}`],
+      }
+    // PK 제약 이름: 복합/후행 추가 = pk_<table>(우리 명명), CREATE TABLE 인라인 단일 PK = postgres
+    // 자동 명명 '<table>_pkey' — differ 가 출처를 알고 op.name 으로 확정해 넘긴다.
+    case 'addPk': {
+      const name = op.name ?? pkName(table)
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(name)} PRIMARY KEY (${op.columns.map(quoteIdent).join(', ')})`],
+        down: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(name)}`],
+      }
+    }
+    case 'dropPk': {
+      const name = op.name ?? pkName(table)
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(name)}`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(name)} PRIMARY KEY (${op.columns.map(quoteIdent).join(', ')})`],
+      }
+    }
+    // PK 교체 — postgres 는 DROP/ADD CONSTRAINT 2문이 그대로 안전(트랜잭셔널 DDL).
+    case 'changePk': {
+      const stmts = (/** @type {any} */ from, /** @type {any} */ to) => [
+        `ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT ${quoteIdent(from.name)}`,
+        `ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(to.name)} PRIMARY KEY (${to.columns.map(quoteIdent).join(', ')})`,
+      ]
+      return { up: stmts(op.from, op.to), down: stmts(op.to, op.from) }
+    }
+    case 'addIndex':
+      return {
+        up: [indexCreateStatement(table, op.index, { concurrent: op.concurrent === true })],
+        down: [`DROP INDEX IF EXISTS ${quoteIdent(resolveIndexName(table, op.index))}`],
+      }
+    case 'dropIndex':
+      return {
+        up: [`DROP INDEX IF EXISTS ${quoteIdent(resolveIndexName(table, op.index))}`],
+        down: [indexCreateStatement(table, op.index)],
+      }
+    case 'setComment':
+      return {
+        up: [commentStatement(table, op.column, op.comment)],
+        down: [commentStatement(table, op.column, op.prev ?? null)],
+      }
+    default:
+      throw new MegaConfigError('migration.schema_invalid', `postgres dialect: 알 수 없는 변경 연산 '${op.kind}'.`, { details: { kind: op.kind } })
+  }
+}
+
+/**
+ * 연산 목록 → `{ up: string[], down: string[] }`. down 은 **역순**(가장 마지막 변경부터 되돌림).
+ * @param {Array<Record<string, any>>} ops
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOps(ops) {
+  /** @type {string[]} */
+  const up = []
+  /** @type {string[][]} */
+  const downs = []
+  for (const op of ops) {
+    const r = renderOp(op)
+    up.push(...r.up)
+    downs.push(r.down)
+  }
+  return { up, down: downs.reverse().flat() }
+}
+
+// ── DML facet (ADR-212) — DDL 마이그레이션 계약과 별개로 CRUD(model-crud)가 쓰는 DML 보조. ──
+//    같은 모듈에 두어 driver 진실을 1곳에 유지(중복 레지스트리 신설 아님). quoteIdent 재사용.
+
+/** placeholder 스타일 — postgres 는 번호식 `$1`. */
+export const paramStyle = 'numbered'
+
+/** @param {number} i - 1-base placeholder 인덱스. @returns {string} */
+export function placeholder(i) {
+  return `$${i}`
+}
+
+/** RETURNING 지원(insert/upsert 레코드 반환). */
+export const supportsReturning = true
+/** insertMany RETURNING 지원. */
+export const supportsBulkReturning = true
+
+/** SELECT native 결과(pg `{ rows }`) → record[]. @param {any} res @returns {any[]} */
+export function parseReadResult(res) {
+  return Array.isArray(res?.rows) ? res.rows : []
+}
+
+/** write native 결과(pg `{ rowCount, rows }`) → 정규화. @param {any} res @returns {{ count: number, rows?: any[] }} */
+export function parseWriteResult(res) {
+  return { count: typeof res?.rowCount === 'number' ? res.rowCount : 0, rows: res?.rows }
+}
+
+/** upsert 절 — `ON CONFLICT (...) DO UPDATE SET ...`. @param {{ conflictCols: string[], updateCols: string[] }} o @returns {string} */
+export function upsertClause({ conflictCols, updateCols }) {
+  const set = updateCols.map((c) => `${quoteIdent(c)} = EXCLUDED.${quoteIdent(c)}`).join(', ')
+  return `ON CONFLICT (${conflictCols.map(quoteIdent).join(', ')}) DO UPDATE SET ${set}`
+}