mega-framework 0.1.6 → 0.1.7

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

@@ -0,0 +1,496 @@
+// @ts-check
+/**
+ * MariaDB dialect (ADR-207) — `dialects/README.md` contract 구현. 실 MariaDB 11.8 검증 기준.
+ *
+ * postgres 와의 핵심 차이:
+ *   - 식별자 = 백틱, 한도 64.
+ *   - enum = **native ENUM 타입**(`enumStrategy: 'enum-type'`) — 값 변경은 CHECK 교체가 아니라
+ *     `MODIFY COLUMN`(differ 가 alterType 으로 산출). 값 제거는 위배 데이터가 있으면 적용 실패.
+ *   - `RENAME CONSTRAINT` **미지원**(11.8 실측 — 구문 에러) → `supportsRenameConstraint: false`,
+ *     FK 이름 동기화는 differ 의 DROP+ADD 대체 패턴.
+ *   - NOT NULL 토글·코멘트 변경은 `MODIFY COLUMN`(전체 정의 필수 — 생략 속성이 리셋되므로
+ *     op 의 def 로 항상 전체 절을 재구성).
+ *   - DDL 은 **암묵 COMMIT** — 러너의 트랜잭션 래핑이 DDL 을 롤백하지 못한다(ADR-190 의
+ *     마이그레이션 락 경고와 동일 맥락). 다단 변경 마이그레이션의 중간 실패는 부분 적용으로
+ *     남는다 — 생성 파일 헤더·러너 경고가 이를 명시한다.
+ *   - 인덱스: `DROP INDEX <name> ON <table>`(ON 필수), 표현식/부분(WHERE) 인덱스 미지원(명시 거부 —
+ *     virtual column + raw 마이그레이션 안내), 온라인 추가는 `ALTER TABLE … ADD INDEX …,
+ *     ALGORITHM=INPLACE, LOCK=NONE`(--concurrent).
+ *   - PRIMARY KEY 이름은 항상 'PRIMARY' — `pkName/inlinePkName` 이 그 현실을 반영(ADD/DROP 도
+ *     이름 없는 `ADD PRIMARY KEY`/`DROP PRIMARY KEY`).
+ *   - timestamptz → DATETIME — timezone-aware 타입이 없어 UTC 저장 규약을 권장(ADR-207).
+ *
+ * @module core/migration/dialects/maria
+ */
+import { MegaConfigError } from '../../../errors/config-error.js'
+
+// ── dialect 표준 인터페이스 속성 ─────────────────────────────────────────────
+/** MariaDB 식별자 한도 — **64자**(chars, utf8 멀티바이트 식별자도 자수 기준). contract 멤버명은
+ * 역사적으로 *MaxBytes 지만 maria 검증은 자수로 한다(비ASCII 과잉 거부 방지 — ADR-208 L-3). */
+export const identifierMaxBytes = 64
+/** 온라인 인덱스 추가 — `ALGORITHM=INPLACE, LOCK=NONE` (--concurrent 옵트인). */
+export const supportsConcurrentIndex = true
+/** enum 표현 전략 — native ENUM 타입(값 변경 = MODIFY COLUMN). */
+export const enumStrategy = 'enum-type'
+/** RENAME COLUMN 자체는 지원(10.5+)하나 DDL 암묵 COMMIT 이라 트랜잭션 내 원자성은 없다. */
+export const supportsRenameInTx = false
+/** DDL 암묵 COMMIT — DROP COLUMN 을 트랜잭션으로 롤백할 수 없다(ADR-190 기존 인지). */
+export const canDropColumnInTx = false
+/** ALTER 가 대부분의 변경을 표현 — 테이블 재생성 불요. */
+export const dependsOnRebuild = false
+/** `ALTER TABLE … RENAME CONSTRAINT` 미지원 — MariaDB 11.8 실측(구문 에러). DROP+ADD 로 대체. */
+export const supportsRenameConstraint = false
+/** ALTER 로 FK 추가/삭제 가능(`ADD CONSTRAINT … FOREIGN KEY` / `DROP CONSTRAINT` — 11.8 실측). */
+export const supportsAlterAddFk = true
+/** InnoDB 는 FK 가 걸린 컬럼의 DROP 을 거부(1553 — FK 인덱스 요구, 11.8 실측) — dropFk 선행 필수. */
+export const requiresDropFkBeforeDropColumn = true
+/** SQL DDL 렌더 dialect — 생성 파일이 `db.query(sql)` 계약을 쓴다(mongo 와 분기, ADR-209). */
+export const usesSqlDdl = true
+
+/**
+ * SQL 식별자 인용 — 백틱. 한도 초과는 fail-fast(절단 충돌 방지 — postgres 와 동일 정책).
+ * @param {string} name @returns {string}
+ * @throws {MegaConfigError} `migration.identifier_too_long`
+ */
+export function quoteIdent(name) {
+  if ([...name].length > identifierMaxBytes) {
+    throw new MegaConfigError(
+      'migration.identifier_too_long',
+      `식별자 '${name}' 가 MariaDB 한도(${identifierMaxBytes}자)를 초과합니다 — 이름을 줄이거나 {name} 으로 짧은 제약 이름을 명시하세요.`,
+      { details: { identifier: name, chars: [...name].length, max: identifierMaxBytes } },
+    )
+  }
+  return `\`${name.replaceAll('`', '``')}\``
+}
+
+/**
+ * 값 literal 인용 — MariaDB 는 기본 sql_mode 에서 백슬래시가 escape 문자라 `\` 도 이스케이프한다
+ * (postgres 의 standard_conforming_strings 와 다른 지점).
+ * @param {unknown} value @returns {string}
+ */
+export function quoteLiteral(value) {
+  if (value === null) return 'NULL'
+  if (typeof value === 'number') {
+    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('\\', '\\\\').replaceAll("'", "''")}'`
+}
+
+/**
+ * 컬럼 타입 → MariaDB SQL 타입.
+ * @param {Record<string, any>} def @returns {string}
+ */
+export function typeSql(def) {
+  switch (def.type) {
+    case 'serial':
+      return 'INT AUTO_INCREMENT'
+    case 'bigSerial':
+      return 'BIGINT AUTO_INCREMENT'
+    case 'integer':
+      return 'INT'
+    case 'bigInteger':
+      return 'BIGINT'
+    case 'smallInteger':
+      return 'SMALLINT'
+    case 'real':
+      return 'FLOAT'
+    case 'doublePrecision':
+      return 'DOUBLE'
+    case 'decimal':
+      return `DECIMAL(${def.precision}, ${def.scale})`
+    case 'varchar':
+      return `VARCHAR(${def.length})`
+    case 'text':
+      return 'TEXT'
+    case 'char':
+      return `CHAR(${def.length})`
+    case 'boolean':
+      return 'TINYINT(1)'
+    case 'timestamp':
+    case 'timestamptz': // timezone-aware 타입 없음 — UTC 저장 규약 권장(ADR-207)
+      return 'DATETIME'
+    case 'date':
+      return 'DATE'
+    case 'time':
+      return 'TIME'
+    case 'uuid':
+      return 'CHAR(36)'
+    case 'json':
+    case 'jsonb': // MariaDB 는 JSON/JSONB 미구분(JSON = LONGTEXT alias + 검증)
+      return 'JSON'
+    case 'enum':
+      return `ENUM(${def.values.map((/** @type {string} */ v) => quoteLiteral(v)).join(', ')})`
+    case 'bytea':
+      return 'BLOB'
+    default:
+      throw new MegaConfigError('migration.schema_invalid', `maria dialect: 알 수 없는 타입 '${def.type}'.`, { details: { type: def.type } })
+  }
+}
+
+// ── 명명 표준 — postgres 와 동일 규칙(diff 안정성), PK 만 서버 현실('PRIMARY') 반영 ──────────
+/** @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}').`, { details: { table } })
+  }
+  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}`
+}
+/** MariaDB 의 PRIMARY KEY 이름은 항상 'PRIMARY' — 명시 이름을 줘도 서버가 무시한다. @returns {string} */
+export function pkName() {
+  return 'PRIMARY'
+}
+/** @returns {string} */
+export function inlinePkName() {
+  return 'PRIMARY'
+}
+
+/**
+ * enum 의 CHECK 식 — contract 필수 멤버. maria 는 enum-type 전략이라 diff 경로에서는 쓰이지
+ * 않지만, 명시 .check() 렌더와 동형 표면을 유지한다.
+ * @param {string} col @param {string[]} values @returns {string}
+ */
+export function enumCheckExpr(col, values) {
+  return `${quoteIdent(col)} IN (${values.map((v) => quoteLiteral(v)).join(', ')})`
+}
+
+/**
+ * 컬럼 정의 절(타입 + NOT NULL + DEFAULT + COMMENT [+ PRIMARY KEY]) — CREATE TABLE/ADD/MODIFY 공용.
+ * MariaDB 의 MODIFY COLUMN 은 전체 정의를 요구(생략 속성 리셋)하므로 이 절이 정의의 단일 정본이다.
+ * 코멘트는 postgres 와 달리 컬럼 정의에 인라인.
+ * @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 ${quoteLiteral(def.default)}`
+  if (def.comment !== undefined) sql += ` COMMENT ${quoteLiteral(def.comment)}`
+  if (inlinePrimary && def.primary === true) sql += ' PRIMARY KEY'
+  return sql
+}
+
+/**
+ * 한 컬럼의 부속 제약(UNIQUE/CHECK) ADD CONSTRAINT 문 — enum 은 타입이라 CHECK 없음.
+ * @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 IF NOT EXISTS (${quoteIdent(col)})`)
+  }
+  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/DROP 문 — DROP 은 `DROP CONSTRAINT`(11.8 실측 지원). */
+function fkAddStatement(/** @type {string} */ table, /** @type {string} */ col, /** @type {Record<string, any>} */ ref) {
+  const name = ref.name ?? fkName(table, col, ref.table)
+  let sql = `ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(name)} FOREIGN KEY IF NOT EXISTS (${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
+}
+function fkDropStatement(/** @type {string} */ table, /** @type {string} */ col, /** @type {Record<string, any>} */ ref) {
+  return `ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT IF EXISTS ${quoteIdent(ref.name ?? fkName(table, col, ref.table))}`
+}
+
+/**
+ * 인덱스 생성 문 — 표현식/부분(WHERE) 인덱스는 MariaDB 미지원이라 명시 거부(silent 누락 금지).
+ * concurrent=true 면 온라인 DDL(`ALTER … ADD INDEX …, ALGORITHM=INPLACE, LOCK=NONE`).
+ * @param {string} table @param {Record<string, any>} ix @param {{ concurrent?: boolean }} [opts]
+ * @returns {string}
+ */
+function indexCreateStatement(table, ix, { concurrent = false } = {}) {
+  if (ix.expression !== undefined) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `MariaDB 는 표현식 인덱스를 지원하지 않습니다 (table '${table}') — virtual column + 인덱스를 raw 마이그레이션으로 작성하세요.`,
+      { details: { table, expression: ix.expression } },
+    )
+  }
+  if (ix.where !== undefined) {
+    throw new MegaConfigError(
+      'migration.dialect_feature_unsupported',
+      `MariaDB 는 부분(WHERE) 인덱스를 지원하지 않습니다 (table '${table}') — 조건을 빼거나 raw 마이그레이션으로 대체하세요.`,
+      { details: { table, where: ix.where } },
+    )
+  }
+  const name = resolveIndexName(table, ix)
+  const cols = ix.columns.map(quoteIdent).join(', ')
+  const usingPart = ix.using !== undefined ? ` USING ${String(ix.using).toUpperCase()}` : ''
+  if (concurrent) {
+    return `ALTER TABLE ${quoteIdent(table)} ADD ${ix.unique === true ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS ${quoteIdent(name)}${usingPart} (${cols}), ALGORITHM=INPLACE, LOCK=NONE`
+  }
+  return `CREATE ${ix.unique === true ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS ${quoteIdent(name)}${usingPart} ON ${quoteIdent(table)} (${cols})`
+}
+
+/**
+ * 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(`  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))
+  }
+  return out
+}
+
+/**
+ * 같은 타입의 길이/정밀도/enum 값 **축소** — 위배 데이터가 있으면 적용 실패·잘림 위험(경고 주석).
+ * enum 값 제거는 enum-type 전략에서 alterType 으로 오므로 여기서 함께 잡는다.
+ * @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
+  if (from.type === 'enum' && Array.isArray(from.values) && Array.isArray(to.values)) {
+    if (from.values.some((/** @type {string} */ v) => !to.values.includes(v))) return true
+  }
+  return false
+}
+
+/**
+ * 변경 연산(op) 1개 → `{ up: string[], down: string[] }`. op 종류·필드는 differ 가 정본.
+ * @param {Record<string, any>} op
+ * @returns {{ up: string[], down: string[] }}
+ */
+export function renderOp(op) {
+  const table = op.table
+  const modify = (/** @type {string} */ col, /** @type {Record<string, any>} */ def, /** @type {string[]} */ notes = []) => {
+    let sql = `ALTER TABLE ${quoteIdent(table)} MODIFY COLUMN ${columnClause(col, def, { inlinePrimary: false })}`
+    for (const n of notes) sql = `${n}\n${sql}`
+    return sql
+  }
+  switch (op.kind) {
+    case 'createTable':
+      return { up: createTableStatements(op.record), down: [`DROP TABLE IF EXISTS ${quoteIdent(table)}`] }
+    case 'dropTable': {
+      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 IF NOT EXISTS ${columnClause(op.column, op.def, { inlinePrimary: false })}`
+      if (op.def.notNull === true && op.def.default === undefined) {
+        add = `-- 경고: 기존 행이 있으면 NOT NULL 컬럼 추가가 실패하거나 암묵 기본값으로 채워질 수 있습니다 — DEFAULT 지정 권장.\n${add}`
+      }
+      up.push(add)
+      up.push(...columnConstraintStatements(table, op.column, op.def))
+      return {
+        up,
+        down: [`-- 경고: 컬럼 데이터가 영구 삭제됩니다.\nALTER TABLE ${quoteIdent(table)} DROP COLUMN IF EXISTS ${quoteIdent(op.column)}`],
+      }
+    }
+    case 'dropColumn': {
+      /** @type {string[]} */
+      const down = [
+        `-- 경고: 구조만 복원됩니다 — 삭제된 컬럼 데이터는 down 으로 복원되지 않습니다.\nALTER TABLE ${quoteIdent(table)} ADD COLUMN IF NOT EXISTS ${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))
+      return {
+        up: [`-- 경고: 컬럼 데이터가 영구 삭제됩니다.\nALTER TABLE ${quoteIdent(table)} DROP COLUMN IF EXISTS ${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': {
+      // MODIFY COLUMN 은 전체 정의 교체 — enum 값 변경(enum-type 전략)도 이 경로다.
+      /** @type {string[]} */
+      const upNotes = []
+      /** @type {string[]} */
+      const downNotes = []
+      if (isNarrowing(op.from, op.to)) {
+        upNotes.push('-- 경고: 길이/정밀도/enum 값 축소 — 위배 데이터가 있으면 적용이 실패하거나 잘림이 발생합니다. 적용 전 데이터 분포를 확인하세요.')
+      }
+      if (isNarrowing(op.to, op.from)) {
+        downNotes.push('-- 경고: 길이/정밀도/enum 값 축소 — 위배 데이터가 있으면 적용이 실패하거나 잘림이 발생합니다.')
+      }
+      return {
+        up: [modify(op.column, op.to, upNotes)],
+        down: [modify(op.column, op.from, downNotes)],
+      }
+    }
+    case 'setNotNull':
+      return { up: [modify(op.column, op.def)], down: [modify(op.column, { ...op.def, notNull: undefined })] }
+    case 'dropNotNull':
+      return { up: [modify(op.column, op.def)], down: [modify(op.column, { ...op.def, notNull: true })] }
+    case 'setDefault':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ALTER COLUMN ${quoteIdent(op.column)} SET DEFAULT ${quoteLiteral(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 ${quoteLiteral(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 ${quoteLiteral(op.prev)}`],
+      }
+    case 'addUnique':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(op.name)} UNIQUE IF NOT EXISTS (${quoteIdent(op.column)})`],
+        down: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT IF EXISTS ${quoteIdent(op.name)}`],
+      }
+    case 'dropUnique':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} DROP CONSTRAINT IF EXISTS ${quoteIdent(op.name)}`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ADD CONSTRAINT ${quoteIdent(op.name)} UNIQUE IF NOT EXISTS (${quoteIdent(op.column)})`],
+      }
+    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 IF EXISTS ${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 IF EXISTS ${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)] }
+    case 'addPk':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} ADD PRIMARY KEY (${op.columns.map(quoteIdent).join(', ')})`],
+        down: [`ALTER TABLE ${quoteIdent(table)} DROP PRIMARY KEY`],
+      }
+    case 'dropPk':
+      return {
+        up: [`ALTER TABLE ${quoteIdent(table)} DROP PRIMARY KEY`],
+        down: [`ALTER TABLE ${quoteIdent(table)} ADD PRIMARY KEY (${op.columns.map(quoteIdent).join(', ')})`],
+      }
+    // PK 교체 — **한 문장**(DROP PRIMARY KEY, ADD PRIMARY KEY)으로 묶는다(11.8 실측): InnoDB 는
+    // FK 인덱스를 겸하는 PK 의 단독 DROP 을 거부(errno 150)하므로 분리 2문은 적용 불가. 단문 결합은
+    // 새 PK 가 FK 컬럼을 선두로 유지하는 한 통과한다(아니면 InnoDB 가 명시 에러 — raw 로 인덱스 선행).
+    case 'changePk': {
+      const one = (/** @type {any} */ to) =>
+        `ALTER TABLE ${quoteIdent(table)} DROP PRIMARY KEY, ADD PRIMARY KEY (${to.columns.map(quoteIdent).join(', ')})`
+      return { up: [one(op.to)], down: [one(op.from)] }
+    }
+    case 'addIndex':
+      return {
+        up: [indexCreateStatement(table, op.index, { concurrent: op.concurrent === true })],
+        down: [`DROP INDEX IF EXISTS ${quoteIdent(resolveIndexName(table, op.index))} ON ${quoteIdent(table)}`],
+      }
+    case 'dropIndex':
+      return {
+        up: [`DROP INDEX IF EXISTS ${quoteIdent(resolveIndexName(table, op.index))} ON ${quoteIdent(table)}`],
+        down: [indexCreateStatement(table, op.index)],
+      }
+    case 'setComment':
+      // 코멘트는 컬럼 정의의 일부 — MODIFY 로 전체 정의를 재기술한다(op.def/prevDef 가 정본).
+      return {
+        up: [modify(op.column, op.def)],
+        down: [modify(op.column, op.prevDef)],
+      }
+    case 'renameFk':
+      // supportsRenameConstraint=false 라 differ 가 발행하지 않는다 — 도달 시 contract 위반.
+      throw new MegaConfigError('migration.schema_invalid', `maria dialect: renameFk 는 미지원입니다(RENAME CONSTRAINT 부재 — DROP+ADD 로 산출돼야 함).`, {
+        details: { op },
+      })
+    default:
+      throw new MegaConfigError('migration.schema_invalid', `maria dialect: 알 수 없는 변경 연산 '${op.kind}'.`, { details: { kind: op.kind } })
+  }
+}
+
+/**
+ * 연산 목록 → `{ up, down }` (down 은 역순). DDL 암묵 COMMIT 특성상 다단 변경의 중간 실패는
+ * 부분 적용으로 남는다 — 러너 락(ADR-190)·생성 파일 헤더가 그 한계를 명시한다.
+ * @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) — CRUD(model-crud)용 DML 보조. maria 는 RETURNING 미지원. ──
+export const paramStyle = 'positional'
+/** maria 는 위치식 `?`(인덱스 무시). @returns {string} */
+export function placeholder() {
+  return '?'
+}
+export const supportsReturning = false
+export const supportsBulkReturning = false
+/** SELECT native(rows 배열) → record[]. @param {any} res @returns {any[]} */
+export function parseReadResult(res) {
+  return Array.isArray(res) ? res : []
+}
+/** write native(`{ affectedRows, insertId }`) → 정규화. @param {any} res */
+export function parseWriteResult(res) {
+  return { count: typeof res?.affectedRows === 'number' ? res.affectedRows : 0, insertId: res?.insertId }
+}
+/** upsert 절 — `ON DUPLICATE KEY UPDATE col = VALUES(col)`. maria 는 conflict target 미사용(자동 unique 매칭). @param {{ updateCols: string[] }} o */
+export function upsertClause({ updateCols }) {
+  const set = updateCols.map((c) => `${quoteIdent(c)} = VALUES(${quoteIdent(c)})`).join(', ')
+  return `ON DUPLICATE KEY UPDATE ${set}`
+}