@restforgejs/platform 4.3.5 → 5.0.0

package/generators/cli/payload/migrate.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Contract: payload migrate
+ *
+ * Konversi file payload backend (RDF / RESTForge consumer) menjadi file payload
+ * frontend (UDF / designer). Port dari `rfd migrate` di packages/designer/.
+ *
+ * Perbedaan dengan `rfd migrate`:
+ *  - `apiBaseUrl` di-construct dari SERVER_ADDRESS + SERVER_PORT (db-connection.env)
+ *    + --project sehingga sesuai dengan runtime server actual
+ *  - Port di-baca dari db-connection.env (SERVER_PORT), bukan hard-coded 3000
+ *  - Primary key (constraints.primaryKey=true) di-skip dari fields[] apapun
+ *    tipenya (uuid/string/integer), karena PK adalah identifier teknis dan
+ *    tidak perlu di-render di UI form
+ */
+
+const runner = require('../../lib/migrate/migrate-runner');
+
+module.exports = {
+    resource: 'payload',
+    verb: 'migrate',
+    description: 'Convert backend payload (RDF) file into frontend payload (UDF) for the designer',
+    category: 'generation',
+    flags: {
+        name: {
+            type: 'string',
+            required: true,
+            description: 'Backend payload file name (e.g. visitors.json). Relative to cwd or cwd/payload/.'
+        },
+        output: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Output directory (the file will be written with the same name as --name inside it). If ending with `.json`, treated as an explicit file path. Default: frontend/payload/'
+        },
+        config: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Database config file (.env). Used to read SERVER_ADDRESS and SERVER_PORT. Falls back to `.restforge/defaults.json`.'
+        },
+        project: {
+            type: 'string',
+            required: true,
+            description: 'Project name (kebab-case code) used as the path segment in apiBaseUrl: http://{host}:{port}/api/{project}'
+        },
+        'app-name': {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Application name (default: "My Application")'
+        },
+        'app-code': {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Application code in kebab-case (default: follows --project)'
+        },
+        plugin: {
+            type: 'string',
+            required: false,
+            default: null,
+            description: 'Designer plugin ID (default: "vanilla-js-basic")'
+        },
+        port: {
+            type: 'number',
+            required: false,
+            default: null,
+            description: 'Frontend application port written to appConfig.port (default: 8000). Independent from the backend port used in apiBaseUrl.'
+        },
+        overwrite: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Overwrite the output file if it already exists'
+        }
+    },
+    examples: [
+        'npx restforge payload migrate --name=visitors.json --output=..\\sandbox\\frontend\\payload --config=db.env --project=myapp',
+        'npx restforge payload migrate --name=visitors.json --project=myapp --overwrite'
+    ],
+    async handler(args) {
+        await runner.run({
+            name: args.name,
+            output: args.output || null,
+            config: args.config || null,
+            project: args.project,
+            appName: args['app-name'] || null,
+            appCode: args['app-code'] || null,
+            plugin: args.plugin || null,
+            port: typeof args.port === 'number' ? args.port : null,
+            overwrite: args.overwrite === true
+        });
+    }
+};

package/generators/lib/dbschema-kit/apply-engine.js

@@ -5,34 +5,40 @@
  * statement incremental. Komplemen `ddl-generator.js` yang menghasilkan full
  * CREATE TABLE.
  *
- * Operasi yang di-handle (MVP):
- *   - ADD COLUMN          (additive, default)
- *   - DROP COLUMN         (destruktif, butuh allowDrop)
- *   - MODIFY COLUMN       (length / nullable, butuh allowModify)
- *   - CREATE INDEX        (additive)
- *   - DROP INDEX          (destruktif, butuh allowDrop)
- *   - ADD CONSTRAINT UNIQUE (additive)
- *   - DROP CONSTRAINT UNIQUE (destruktif, butuh allowDrop)
+ * Operasi yang di-handle:
+ *   - ADD COLUMN              (additive, default)
+ *   - DROP COLUMN             (destruktif, butuh allowDrop)
+ *   - MODIFY COLUMN           (length / nullable, butuh allowModify)
+ *   - CREATE INDEX            (additive)
+ *   - DROP INDEX              (destruktif, butuh allowDrop)
+ *   - ADD CONSTRAINT UNIQUE   (additive)
+ *   - DROP CONSTRAINT UNIQUE  (destruktif, butuh allowDrop)
+ *   - ADD FOREIGN KEY         (additive, default — kecuali sqlite)
+ *   - DROP FOREIGN KEY        (destruktif, butuh allowDrop — kecuali sqlite)
+ *   - REPLACE FOREIGN KEY action (destruktif: DROP+ADD, butuh allowModify — kecuali sqlite)
  *
  * Operasi yang TIDAK di-handle (deferred):
  *   - ALTER COLUMN type change (butuh data conversion strategy per dialect)
  *   - PK changes (butuh rebuild table)
- *   - FK changes (butuh cross-model validation + dialect syntax kompleks)
  *   - DEFAULT value changes (defer ke fase berikutnya)
  *   - CHECK constraint changes
+ *   - FK changes pada sqlite (butuh rebuild table)
  *
- * SQLite tidak mendukung ALTER COLUMN / DROP COLUMN tanpa rebuild table.
- * Untuk dialect ini, MODIFY dan DROP COLUMN otomatis di-skip dengan reason
- * 'sqlite limitation' walaupun flag opt-in aktif.
+ * SQLite tidak mendukung ALTER COLUMN / DROP COLUMN / ALTER ADD CONSTRAINT FK
+ * tanpa rebuild table. Untuk dialect ini, MODIFY/DROP COLUMN dan semua perubahan
+ * FK otomatis di-skip dengan reason 'sqlite limitation' walaupun flag opt-in
+ * aktif.
  *
  * Output dipesan dengan urutan aman untuk dependency:
- *   1. ADD COLUMN          (no dependencies)
- *   2. CREATE INDEX        (depend on column existence)
- *   3. ADD CONSTRAINT UNIQUE (depend on column existence)
- *   4. ALTER/MODIFY COLUMN (modify after additive done)
- *   5. DROP CONSTRAINT     (before drop column to avoid dependency error)
- *   6. DROP INDEX          (before drop column)
- *   7. DROP COLUMN         (last)
+ *   1. ADD COLUMN                 (no dependencies)
+ *   2. CREATE INDEX               (depend on column existence)
+ *   3. ADD CONSTRAINT UNIQUE      (depend on column existence)
+ *   4. ADD CONSTRAINT FOREIGN KEY (depend on column existence di kedua sisi)
+ *   5. ALTER/MODIFY COLUMN        (modify after additive done)
+ *   6. DROP CONSTRAINT FK         (release FK sebelum drop unique/index/column)
+ *   7. DROP CONSTRAINT UNIQUE     (before drop column to avoid dependency error)
+ *   8. DROP INDEX                 (before drop column)
+ *   9. DROP COLUMN                (last)
  *
  * @module lib/dbschema-kit/apply-engine
  */
@@ -45,7 +51,9 @@ const {
     emitCreateIndex,
     emitDropIndex,
     emitAddUnique,
-    emitDropUnique
+    emitDropUnique,
+    emitAddForeignKey,
+    emitDropForeignKey
 } = require('./emitters/alter-table');
 
 const VALID_DIALECTS = ['postgres', 'mysql', 'oracle', 'sqlite'];
@@ -142,7 +150,10 @@ function buildBuckets() {
         addColumns: [],
         createIndexes: [],
         addUniques: [],
+        addForeignKeys: [],
         modifyColumns: [],
+        dropForeignKeys: [],
+        replaceForeignKeysAdd: [],
         dropConstraints: [],
         dropIndexes: [],
         dropColumns: []
@@ -154,7 +165,10 @@ function flattenBuckets(buckets) {
         ...buckets.addColumns,
         ...buckets.createIndexes,
         ...buckets.addUniques,
+        ...buckets.addForeignKeys,
         ...buckets.modifyColumns,
+        ...buckets.dropForeignKeys,
+        ...buckets.replaceForeignKeysAdd,
         ...buckets.dropConstraints,
         ...buckets.dropIndexes,
         ...buckets.dropColumns
@@ -412,51 +426,201 @@ function processUniques(delta, tableIR, dialect, options, buckets, skipped, summ
     }
 }
 
-function noteDeferredSections(delta, skipped) {
-    // PK changes — deferred dari MVP karena butuh rebuild table.
-    if (delta.primaryKey && delta.primaryKey.match === false) {
-        const sdf = Array.isArray(delta.primaryKey.sdf) ? delta.primaryKey.sdf : [];
-        const db = Array.isArray(delta.primaryKey.db) ? delta.primaryKey.db : [];
-        skipped.push({
-            table: delta.tableName,
-            kind: 'primary-key',
-            target: `pk(${sdf.join(',') || '∅'} vs ${db.join(',') || '∅'})`,
-            reason: 'deferred',
-            description: `Primary key changes for ${delta.tableName} deferred from MVP (requires table rebuild)`
-        });
-    }
+// ─────────────────────────────────────────────────────────────
+// FK delta processing
+// ─────────────────────────────────────────────────────────────
 
-    if (delta.foreignKeys) {
-        const fkOnlySdf = Array.isArray(delta.foreignKeys.onlyInSdf) ? delta.foreignKeys.onlyInSdf : [];
-        const fkOnlyDb = Array.isArray(delta.foreignKeys.onlyInDb) ? delta.foreignKeys.onlyInDb : [];
-        const fkMismatch = Array.isArray(delta.foreignKeys.mismatched) ? delta.foreignKeys.mismatched : [];
+// FK delta entries dari diff-engine memuat triplet (localKey, target, references)
+// plus optional `name` (relName dari relations map) dan `dbName` (untuk mismatched).
+// Apply path hanya menjalankan validator opsional, jadi kita fallback ke localKey
+// untuk derive constraint name bila relName tidak tersedia.
+function pickRelName(fk) {
+    if (fk && typeof fk.name === 'string' && fk.name !== '') return fk.name;
+    if (fk && typeof fk.localKey === 'string' && fk.localKey !== '') return fk.localKey;
+    return null;
+}
+
+function fkSkipTarget(fk) {
+    const local = fk && fk.localKey ? fk.localKey : '?';
+    const target = fk && fk.target ? fk.target : '?';
+    const ref = fk && fk.references ? fk.references : '?';
+    return `${local} -> ${target}.${ref}`;
+}
+
+function processForeignKeys(delta, tableIR, dialect, options, buckets, skipped, summary) {
+    if (!delta.foreignKeys) return;
+
+    const fkOnlySdf = Array.isArray(delta.foreignKeys.onlyInSdf) ? delta.foreignKeys.onlyInSdf : [];
+    const fkOnlyDb = Array.isArray(delta.foreignKeys.onlyInDb) ? delta.foreignKeys.onlyInDb : [];
+    const fkMismatch = Array.isArray(delta.foreignKeys.mismatched) ? delta.foreignKeys.mismatched : [];
+
+    // SQLite: semua perubahan FK butuh table rebuild — defer dengan reason akurat
+    if (dialect.name === 'sqlite') {
         for (const fk of fkOnlySdf) {
             skipped.push({
                 table: delta.tableName,
                 kind: 'foreign-key',
-                target: `${fk.localKey} -> ${fk.target}.${fk.references}`,
-                reason: 'deferred',
-                description: `Foreign key changes deferred from MVP (additive ${delta.tableName}.${fk.localKey})`
+                target: fkSkipTarget(fk),
+                reason: 'sqlite limitation',
+                description: `SQLite does not support ALTER TABLE ADD CONSTRAINT FOREIGN KEY (${delta.tableName}.${fk.localKey})`
             });
         }
         for (const fk of fkOnlyDb) {
             skipped.push({
                 table: delta.tableName,
                 kind: 'foreign-key',
-                target: `${fk.localKey} -> ${fk.target}.${fk.references}`,
-                reason: 'deferred',
-                description: `Foreign key changes deferred from MVP (drop ${delta.tableName}.${fk.localKey})`
+                target: fkSkipTarget(fk),
+                reason: 'sqlite limitation',
+                description: `SQLite does not support ALTER TABLE DROP CONSTRAINT FOREIGN KEY (${delta.tableName}.${fk.localKey})`
             });
         }
         for (const fk of fkMismatch) {
             skipped.push({
                 table: delta.tableName,
                 kind: 'foreign-key',
-                target: `${fk.localKey} -> ${fk.target}.${fk.references}`,
-                reason: 'deferred',
-                description: `Foreign key action change deferred from MVP (${delta.tableName}.${fk.localKey})`
+                target: fkSkipTarget(fk),
+                reason: 'sqlite limitation',
+                description: `SQLite does not support ALTER TABLE for FK action change (${delta.tableName}.${fk.localKey})`
+            });
+        }
+        return;
+    }
+
+    // FK additive (onlyInSdf) — non-destruktif, emit langsung tanpa flag opt-in
+    for (const fk of fkOnlySdf) {
+        const relName = pickRelName(fk);
+        if (!relName) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'emit-error',
+                description: `Foreign key for ${delta.tableName} missing both name and localKey`
             });
+            continue;
         }
+        try {
+            buckets.addForeignKeys.push(emitAddForeignKey(tableIR, relName, fk, dialect));
+            summary.totalAdditions++;
+        } catch (err) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'emit-error',
+                description: err && err.message ? err.message : String(err)
+            });
+        }
+    }
+
+    // FK drop (onlyInDb) — destruktif, butuh --allow-drop
+    for (const fk of fkOnlyDb) {
+        const relName = pickRelName(fk);
+        if (!relName) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'emit-error',
+                description: `Foreign key for ${delta.tableName} missing both name and localKey`
+            });
+            continue;
+        }
+        if (!options.allowDrop) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'requires --allow-drop',
+                description: `Drop foreign key on ${delta.tableName}.${fk.localKey} requires --allow-drop`
+            });
+            continue;
+        }
+        try {
+            // DROP memakai conname aktual dari introspeksi (fk.dbConstraintName) agar
+            // statement menargetkan constraint yang benar-benar ada di DB. Bila conname
+            // tidak tersedia (driver kustom), emitter fallback ke derivasi nama lama
+            // (generateConstraintName) — perilaku legacy, tanpa entry skipped/warning.
+            buckets.dropForeignKeys.push(
+                emitDropForeignKey(tableIR, relName, dialect, { name: fk.dbConstraintName })
+            );
+            summary.totalDeletions++;
+        } catch (err) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'emit-error',
+                description: err && err.message ? err.message : String(err)
+            });
+        }
+    }
+
+    // FK mismatch (action change) — destruktif (DROP + ADD), butuh --allow-modify
+    for (const fk of fkMismatch) {
+        const relName = pickRelName(fk);
+        if (!relName) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'emit-error',
+                description: `Foreign key for ${delta.tableName} missing both name and localKey`
+            });
+            continue;
+        }
+        if (!options.allowModify) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'requires --allow-modify',
+                description: `Foreign key action change on ${delta.tableName}.${fk.localKey} requires --allow-modify`
+            });
+            continue;
+        }
+        try {
+            const sdfActions = fk.sdf || {};
+            const addRel = {
+                localKey: fk.localKey,
+                target: fk.target,
+                references: fk.references,
+                onDelete: sdfActions.onDelete,
+                onUpdate: sdfActions.onUpdate
+            };
+            // DROP memakai conname aktual dari DB (fk.dbConstraintName, fallback derive
+            // bila absen); ADD memakai nama SDF-derive (relName) konsisten dengan
+            // create-table. ADD masuk replaceForeignKeysAdd bucket supaya terbit SETELAH
+            // semua DROP FK, mencegah konflik bila nama lama dan baru kebetulan sama.
+            buckets.dropForeignKeys.push(
+                emitDropForeignKey(tableIR, relName, dialect, { name: fk.dbConstraintName })
+            );
+            buckets.replaceForeignKeysAdd.push(emitAddForeignKey(tableIR, relName, addRel, dialect));
+            summary.totalModifications++;
+        } catch (err) {
+            skipped.push({
+                table: delta.tableName,
+                kind: 'foreign-key',
+                target: fkSkipTarget(fk),
+                reason: 'emit-error',
+                description: err && err.message ? err.message : String(err)
+            });
+        }
+    }
+}
+
+function noteDeferredSections(delta, skipped) {
+    // PK changes — deferred dari MVP karena butuh rebuild table.
+    if (delta.primaryKey && delta.primaryKey.match === false) {
+        const sdf = Array.isArray(delta.primaryKey.sdf) ? delta.primaryKey.sdf : [];
+        const db = Array.isArray(delta.primaryKey.db) ? delta.primaryKey.db : [];
+        skipped.push({
+            table: delta.tableName,
+            kind: 'primary-key',
+            target: `pk(${sdf.join(',') || '∅'} vs ${db.join(',') || '∅'})`,
+            reason: 'deferred',
+            description: `Primary key changes for ${delta.tableName} deferred from MVP (requires table rebuild)`
+        });
     }
 
     if (delta.checks) {
@@ -548,6 +712,7 @@ function generateAlterStatements(deltas, options) {
         processFieldsMismatched(delta, tableIR, dialect, localOptions, buckets, skipped, sdfModels, summary);
         processIndexes(delta, tableIR, dialect, localOptions, buckets, skipped, summary);
         processUniques(delta, tableIR, dialect, localOptions, buckets, skipped, summary);
+        processForeignKeys(delta, tableIR, dialect, localOptions, buckets, skipped, summary);
         noteDeferredSections(delta, skipped);
 
         const flat = flattenBuckets(buckets);

package/generators/lib/dbschema-kit/diff-engine.js

@@ -410,7 +410,11 @@ function extractForeignKeys(ir) {
             target: stripSchemaPrefix(rel.target),
             references: rel.references || null,
             onDelete: rel.onDelete,
-            onUpdate: rel.onUpdate
+            onUpdate: rel.onUpdate,
+            // Carry the actual DB constraint name (introspect-mapper sets it on the
+            // rel) past this whitelist so DROP/MODIFY can target the real conname.
+            // Undefined for SDF-side FKs, which never emit a DROP.
+            _dbConstraintName: rel._dbConstraintName
         });
     }
     return out;
@@ -456,11 +460,14 @@ function compareFkActions(sdfFk, dbFk) {
 
 function formatFkEntry(fk) {
     return {
+        name: fk.name,
         localKey: fk.localKey,
         target: fk.target,
         references: fk.references,
         onDelete: normalizeFkAction(fk.onDelete),
-        onUpdate: normalizeFkAction(fk.onUpdate)
+        onUpdate: normalizeFkAction(fk.onUpdate),
+        // Actual DB constraint name for onlyInDb (DROP); undefined for onlyInSdf (ADD).
+        dbConstraintName: fk._dbConstraintName
     };
 }
 
@@ -493,6 +500,11 @@ function diffForeignKeys(sdfIR, dbIR) {
         const reasons = compareFkActions(sdfFk, dbFk);
         if (reasons.length > 0) {
             mismatched.push({
+                name: sdfFk.name,
+                dbName: dbFk.name,
+                // Actual DB constraint name (conname) from the DB side, used to DROP
+                // the existing constraint before re-adding with SDF-derived naming.
+                dbConstraintName: dbFk._dbConstraintName,
                 localKey: sdfFk.localKey,
                 target: sdfFk.target,
                 references: sdfFk.references,

package/generators/lib/dbschema-kit/emitters/alter-table.js

@@ -10,7 +10,9 @@
  *   - CREATE INDEX
  *   - DROP INDEX (dialect-aware)
  *   - ADD CONSTRAINT UNIQUE
- *   - DROP CONSTRAINT
+ *   - DROP CONSTRAINT (unique)
+ *   - ADD CONSTRAINT FOREIGN KEY
+ *   - DROP CONSTRAINT FOREIGN KEY (MySQL: DROP FOREIGN KEY)
  *
  * Konvensi penamaan constraint/index reuse `naming.js` (generateConstraintName,
  * deriveCompositeShortName) agar nama yang di-emit identik dengan create-table
@@ -262,6 +264,95 @@ function emitDropUnique(tableIR, columns, dialect, options) {
     return `ALTER TABLE ${tableIdentifier} DROP CONSTRAINT ${dialect.quoteIdentifier(name)}`;
 }
 
+// ─────────────────────────────────────────────────────────────
+// ADD / DROP FOREIGN KEY
+// ─────────────────────────────────────────────────────────────
+
+// Cross-model-validator augments rel with `_targetSchemaName` + `_targetTableName`.
+// Apply path tidak selalu menjalankan validator, jadi fallback dengan split
+// `rel.target` di '.' bila tersedia, lalu treat sebagai schema-less target.
+function resolveTargetIr(rel) {
+    if (rel && rel._targetTableName) {
+        return { schemaName: rel._targetSchemaName || null, tableName: rel._targetTableName };
+    }
+    const target = rel && rel.target;
+    if (typeof target === 'string' && target.includes('.')) {
+        const idx = target.indexOf('.');
+        return { schemaName: target.slice(0, idx), tableName: target.slice(idx + 1) };
+    }
+    return { schemaName: null, tableName: target };
+}
+
+function deriveForeignKeyConstraintName(tableName, relName, dialect, explicitName) {
+    if (typeof explicitName === 'string' && explicitName !== '') {
+        return explicitName;
+    }
+    return generateConstraintName('fk', tableName, relName, dialect.maxIdentifierLength);
+}
+
+function emitAddForeignKey(tableIR, relName, rel, dialect) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitAddForeignKey: tableIR with tableName is required');
+    }
+    if (typeof relName !== 'string' || relName === '') {
+        throw new Error('emitAddForeignKey: relName must be a non-empty string');
+    }
+    if (!rel || typeof rel !== 'object') {
+        throw new Error(`emitAddForeignKey: rel definition required for '${relName}'`);
+    }
+    if (typeof rel.localKey !== 'string' || rel.localKey === '') {
+        throw new Error(`emitAddForeignKey: rel.localKey required for '${relName}'`);
+    }
+    if (typeof rel.references !== 'string' || rel.references === '') {
+        throw new Error(`emitAddForeignKey: rel.references required for '${relName}'`);
+    }
+    if (dialect.name === 'sqlite') {
+        throw new Error(
+            `emitAddForeignKey: sqlite does not support ALTER TABLE ADD CONSTRAINT FOREIGN KEY ` +
+            `(requires table rebuild). Filter FK operations in apply-engine before calling emitter.`
+        );
+    }
+
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+    const constraintName = deriveForeignKeyConstraintName(tableIR.tableName, relName, dialect);
+    const local = dialect.quoteIdentifier(rel.localKey);
+    const target = dialect.formatTableIdentifier(resolveTargetIr(rel));
+    const ref = dialect.quoteIdentifier(rel.references);
+
+    let stmt = `ALTER TABLE ${tableIdentifier} ADD CONSTRAINT ${dialect.quoteIdentifier(constraintName)} `
+             + `FOREIGN KEY (${local}) REFERENCES ${target} (${ref})`;
+    if (rel.onDelete) stmt += ` ON DELETE ${dialect.formatReferentialAction(rel.onDelete)}`;
+    if (rel.onUpdate) stmt += ` ON UPDATE ${dialect.formatReferentialAction(rel.onUpdate)}`;
+    return stmt;
+}
+
+function emitDropForeignKey(tableIR, relName, dialect, options) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitDropForeignKey: tableIR with tableName is required');
+    }
+    if (typeof relName !== 'string' || relName === '') {
+        throw new Error('emitDropForeignKey: relName must be a non-empty string');
+    }
+    if (dialect.name === 'sqlite') {
+        throw new Error(
+            `emitDropForeignKey: sqlite does not support ALTER TABLE DROP CONSTRAINT FOREIGN KEY ` +
+            `(requires table rebuild). Filter FK operations in apply-engine before calling emitter.`
+        );
+    }
+
+    const explicitName = options && typeof options.name === 'string' && options.name.length > 0
+        ? options.name
+        : null;
+    const constraintName = deriveForeignKeyConstraintName(tableIR.tableName, relName, dialect, explicitName);
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+
+    if (dialect.name === 'mysql') {
+        // MySQL: DROP FOREIGN KEY syntax (DROP CONSTRAINT FK hanya supported MySQL 8.0.19+)
+        return `ALTER TABLE ${tableIdentifier} DROP FOREIGN KEY ${dialect.quoteIdentifier(constraintName)}`;
+    }
+    return `ALTER TABLE ${tableIdentifier} DROP CONSTRAINT ${dialect.quoteIdentifier(constraintName)}`;
+}
+
 module.exports = {
     emitAddColumn,
     emitDropColumn,
@@ -270,6 +361,9 @@ module.exports = {
     emitDropIndex,
     emitAddUnique,
     emitDropUnique,
+    emitAddForeignKey,
+    emitDropForeignKey,
     deriveIndexName,
-    deriveUniqueConstraintName
+    deriveUniqueConstraintName,
+    deriveForeignKeyConstraintName
 };

package/generators/lib/dbschema-kit/introspect-mapper.js

@@ -120,6 +120,15 @@ function mapTableMetaToIR(tableMeta, dialect) {
             _sourceField: null
         };
 
+        // Preserve the actual DB constraint name (conname). relName above is derived
+        // from the target table for SDF generation and does not match the constraint
+        // stored in the database, so the apply-engine needs the real conname to emit a
+        // DROP that targets an existing constraint. Internal field (prefix `_`): the
+        // schema-printer whitelist (VALID_REL_FIELDS) keeps it out of SDF output.
+        if (typeof fk.name === 'string' && fk.name !== '') {
+            rel._dbConstraintName = fk.name;
+        }
+
         const onDelete = mapReferentialAction(fk.onDelete);
         if (onDelete) rel.onDelete = onDelete;
         const onUpdate = mapReferentialAction(fk.onUpdate);