frg-data-diff 2.0.0

package/dist/apply/apply-diff.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConflictError = void 0;
+exports.applyTableDiff = applyTableDiff;
+const serialize_value_1 = require("../diff/serialize-value");
+const sql_1 = require("../db/sql");
+const metadata_1 = require("../db/metadata");
+/**
+ * Applies a single table diff to the destination database.
+ * Modifies summary in-place.
+ */
+async function applyTableDiff(client, tableDiff, options, summary) {
+    const { schema, table, primaryKey, inserts, updates, deletes } = tableDiff;
+    // Fetch column type metadata for type-correct guard WHERE clauses.
+    // Skip if dry-run and there's nothing to process.
+    let columnTypes = {};
+    const needsTypes = !options.dryRun &&
+        ((options.applyUpdates && updates.length > 0) ||
+            (options.applyDeletes && deletes.length > 0));
+    if (needsTypes) {
+        columnTypes = await (0, metadata_1.fetchColumnTypeMap)(client, schema, table);
+    }
+    // 1. Inserts
+    if (options.applyInserts && inserts.length > 0) {
+        for (const record of inserts) {
+            await applyInsert(client, schema, table, primaryKey, record, options, summary);
+        }
+    }
+    // 2. Updates
+    if (options.applyUpdates && updates.length > 0) {
+        for (const record of updates) {
+            await applyUpdate(client, schema, table, primaryKey, record, options, summary, columnTypes);
+        }
+    }
+    // 3. Deletes (only if explicitly enabled)
+    if (options.applyDeletes && deletes.length > 0) {
+        for (const record of deletes) {
+            await applyDelete(client, schema, table, primaryKey, record, options, summary, columnTypes);
+        }
+    }
+}
+async function applyInsert(client, schema, table, pkColumns, record, options, summary) {
+    const columns = Object.keys(record.row);
+    const deserializedRow = {};
+    for (const col of columns) {
+        deserializedRow[col] = (0, serialize_value_1.deserializeValue)(record.row[col]);
+    }
+    const pkValues = {};
+    for (const col of pkColumns) {
+        pkValues[col] = deserializedRow[col];
+    }
+    if (options.verbose) {
+        console.log(`  INSERT into ${schema}.${table} pk=${JSON.stringify(pkValues)}`);
+    }
+    if (options.dryRun) {
+        summary.applied.inserts++;
+        return;
+    }
+    if (options.conflictMode === "skip" || options.conflictMode === "overwrite") {
+        // Use a savepoint so a failure doesn't abort the entire transaction
+        const sp = `sp_insert_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        await client.query(`SAVEPOINT ${sp}`);
+        try {
+            if (options.insertMode === "upsert") {
+                await (0, sql_1.upsertRow)(client, schema, table, deserializedRow, columns, pkColumns);
+            }
+            else {
+                await (0, sql_1.insertRow)(client, schema, table, deserializedRow, columns);
+            }
+            await client.query(`RELEASE SAVEPOINT ${sp}`);
+            summary.applied.inserts++;
+        }
+        catch (err) {
+            await client.query(`ROLLBACK TO SAVEPOINT ${sp}`);
+            await client.query(`RELEASE SAVEPOINT ${sp}`);
+            if (options.conflictMode === "skip") {
+                const reason = err instanceof Error ? err.message : String(err);
+                summary.skipped.push({
+                    table: `${schema}.${table}`,
+                    operation: "insert",
+                    pk: pkValues,
+                    reason,
+                });
+            }
+            else {
+                // overwrite: try upsert as fallback
+                await (0, sql_1.upsertRow)(client, schema, table, deserializedRow, columns, pkColumns);
+                summary.applied.inserts++;
+            }
+        }
+    }
+    else {
+        // abort mode: let errors propagate directly
+        try {
+            if (options.insertMode === "upsert") {
+                await (0, sql_1.upsertRow)(client, schema, table, deserializedRow, columns, pkColumns);
+            }
+            else {
+                // strict: will throw if PK already exists
+                await (0, sql_1.insertRow)(client, schema, table, deserializedRow, columns);
+            }
+            summary.applied.inserts++;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new ConflictError(`Insert conflict in ${schema}.${table} pk=${JSON.stringify(pkValues)}: ${reason}`);
+        }
+    }
+}
+async function applyUpdate(client, schema, table, pkColumns, record, options, summary, columnTypes = {}) {
+    const pkValues = {};
+    for (const col of pkColumns) {
+        pkValues[col] = (0, serialize_value_1.deserializeValue)(record.pk[col]);
+    }
+    const setColumns = Object.keys(record.changes);
+    const setValues = {};
+    for (const col of setColumns) {
+        setValues[col] = (0, serialize_value_1.deserializeValue)(record.changes[col].to);
+    }
+    if (options.verbose) {
+        console.log(`  UPDATE ${schema}.${table} pk=${JSON.stringify(pkValues)} columns=[${setColumns.join(", ")}]`);
+    }
+    if (options.dryRun) {
+        summary.applied.updates++;
+        return;
+    }
+    const guardCols = [];
+    const guardVals = {};
+    if (options.conflictMode !== "overwrite") {
+        for (const [col, value] of Object.entries(record.guard)) {
+            if (!pkColumns.includes(col)) {
+                guardCols.push(col);
+                guardVals[col] = (0, serialize_value_1.deserializeValue)(value);
+            }
+        }
+    }
+    const rowsUpdated = await (0, sql_1.updateRow)(client, schema, table, pkColumns, pkValues, setColumns, setValues, guardCols, guardVals, columnTypes);
+    if (rowsUpdated === 0) {
+        // Either PK not found, or guard failed
+        const reason = "Row not found or guard check failed (destination row may have changed)";
+        if (options.conflictMode === "abort") {
+            throw new ConflictError(`Update conflict in ${schema}.${table} pk=${JSON.stringify(pkValues)}: ${reason}`);
+        }
+        else if (options.conflictMode === "skip") {
+            summary.skipped.push({
+                table: `${schema}.${table}`,
+                operation: "update",
+                pk: pkValues,
+                reason,
+            });
+        }
+    }
+    else {
+        summary.applied.updates++;
+    }
+}
+async function applyDelete(client, schema, table, pkColumns, record, options, summary, columnTypes = {}) {
+    const pkValues = {};
+    for (const col of pkColumns) {
+        pkValues[col] = (0, serialize_value_1.deserializeValue)(record.pk[col]);
+    }
+    // Build guard from all guard columns (not just pk)
+    const guardColumns = Object.keys(record.guard).filter((c) => !pkColumns.includes(c));
+    const guardVals = {};
+    for (const col of guardColumns) {
+        guardVals[col] = (0, serialize_value_1.deserializeValue)(record.guard[col]);
+    }
+    if (options.verbose) {
+        console.log(`  DELETE from ${schema}.${table} pk=${JSON.stringify(pkValues)}`);
+    }
+    if (options.dryRun) {
+        summary.applied.deletes++;
+        return;
+    }
+    // Always use guarded delete (abort/skip modes check guards)
+    const rowsDeleted = await (0, sql_1.deleteRow)(client, schema, table, pkColumns, pkValues, guardColumns, guardVals, columnTypes);
+    if (rowsDeleted === 0) {
+        const reason = "Row not found or guard check failed (destination row may have changed)";
+        if (options.conflictMode === "abort") {
+            throw new ConflictError(`Delete conflict in ${schema}.${table} pk=${JSON.stringify(pkValues)}: ${reason}`);
+        }
+        else if (options.conflictMode === "skip") {
+            summary.skipped.push({
+                table: `${schema}.${table}`,
+                operation: "delete",
+                pk: pkValues,
+                reason,
+            });
+        }
+    }
+    else {
+        summary.applied.deletes++;
+    }
+}
+/**
+ * Thrown when a conflict is detected in abort mode.
+ */
+class ConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConflictError";
+    }
+}
+exports.ConflictError = ConflictError;
+//# sourceMappingURL=apply-diff.js.map

package/dist/apply/conflict.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Conflict handling documentation and utilities.
+ *
+ * Conflict modes:
+ *
+ * abort   - (default) Abort the transaction on the first conflict.
+ *            The destination database is left unchanged (if transaction=true).
+ *
+ * skip    - Skip the conflicting row and continue applying other rows.
+ *           Skipped rows are recorded in the summary.
+ *
+ * overwrite - Ignore the "from" guard for updates and force the "to" value.
+ *             For inserts, behaves like upsert.
+ *             Note: overwrite does NOT disable guarded deletes.
+ *             Deletes still check the guard even in overwrite mode
+ *             to prevent accidental data loss.
+ */
+export type ConflictMode = "abort" | "skip" | "overwrite";
+export declare function describeConflictMode(mode: ConflictMode): string;
+//# sourceMappingURL=conflict.d.ts.map

package/dist/apply/conflict.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeConflictMode = describeConflictMode;
+function describeConflictMode(mode) {
+    switch (mode) {
+        case "abort":
+            return "abort: Roll back transaction on first conflict (default, safest)";
+        case "skip":
+            return "skip: Skip conflicting rows and continue";
+        case "overwrite":
+            return "overwrite: Force apply changes, ignoring from-value guards for updates";
+    }
+}
+//# sourceMappingURL=conflict.js.map

package/dist/apply/plan.d.ts

@@ -0,0 +1,13 @@
+import { Pool } from "pg";
+import { type DiffJson } from "../diff/diff-schema";
+import { type ApplyTableOptions } from "./apply-diff";
+import { type ApplySummary } from "../shared/summary";
+export interface RunApplyOptions extends ApplyTableOptions {
+    transaction: boolean;
+}
+/**
+ * Applies a full diff to the destination database.
+ * Handles transactions, conflict modes, and dry-run behavior.
+ */
+export declare function runApply(destPool: Pool, diff: DiffJson, options: RunApplyOptions): Promise<ApplySummary>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/apply/plan.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runApply = runApply;
+const apply_diff_1 = require("./apply-diff");
+const summary_1 = require("../shared/summary");
+/**
+ * Applies a full diff to the destination database.
+ * Handles transactions, conflict modes, and dry-run behavior.
+ */
+async function runApply(destPool, diff, options) {
+    const summary = (0, summary_1.createEmptySummary)();
+    const client = await destPool.connect();
+    try {
+        if (options.transaction && !options.dryRun) {
+            await client.query("BEGIN");
+        }
+        try {
+            for (const tableDiff of diff.tables) {
+                await (0, apply_diff_1.applyTableDiff)(client, tableDiff, options, summary);
+            }
+            if (options.transaction && !options.dryRun) {
+                await client.query("COMMIT");
+            }
+        }
+        catch (err) {
+            if (options.transaction && !options.dryRun) {
+                await client.query("ROLLBACK");
+            }
+            throw err;
+        }
+    }
+    finally {
+        client.release();
+    }
+    return summary;
+}
+//# sourceMappingURL=plan.js.map

package/dist/cli/apply.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * frg-data-diff apply
+ *
+ * Reads a JSON diff file and safely applies it to a destination PostgreSQL database.
+ */
+export {};
+//# sourceMappingURL=apply.d.ts.map

package/dist/cli/apply.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * frg-data-diff apply
+ *
+ * Reads a JSON diff file and safely applies it to a destination PostgreSQL database.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const load_config_1 = require("../config/load-config");
+const resolve_options_1 = require("../config/resolve-options");
+const connection_1 = require("../db/connection");
+const diff_schema_1 = require("../diff/diff-schema");
+const plan_1 = require("../apply/plan");
+const summary_1 = require("../shared/summary");
+const prompts_1 = require("../shared/prompts");
+const env_values_1 = require("../shared/env-values");
+const program = new commander_1.Command();
+program
+    .name("frg-data-diff apply")
+    .description("Reads a JSON diff file and safely applies it to a destination PostgreSQL database.")
+    .option("--dest-pg-host <host>", "Destination database host")
+    .option("--dest-pg-port <port>", "Destination database port", (v) => parseInt(v, 10))
+    .option("--dest-pg-database <db>", "Destination database name")
+    .option("--dest-pg-user <user>", "Destination database user")
+    .option("--dest-pg-password-env <value>", "Destination DB password or $ENV_VAR reference")
+    .option("--dest-pg-ssl", "Use SSL for destination database connection")
+    .option("--no-dest-pg-ssl", "Do not use SSL for destination database connection")
+    .option("--input <file>", "Input diff file path", "frg-data-diff.json")
+    .option("--dry-run", "Simulate the apply without making any changes (default)")
+    .option("--execute", "Apply changes to the destination database (required to mutate)")
+    .option("--apply-inserts", "Apply inserts (default: true)")
+    .option("--no-apply-inserts", "Do not apply inserts")
+    .option("--apply-updates", "Apply updates (default: true)")
+    .option("--no-apply-updates", "Do not apply updates")
+    .option("--apply-deletes", "Apply deletes (default: false, requires explicit opt-in)")
+    .option("--no-apply-deletes", "Do not apply deletes (default)")
+    .option("--conflict-mode <mode>", "Conflict mode: abort, skip, or overwrite", "abort")
+    .option("--insert-mode <mode>", "Insert mode: strict or upsert", "strict")
+    .option("--transaction", "Wrap all changes in a single transaction (default: true)")
+    .option("--no-transaction", "Do not wrap changes in a transaction")
+    .option("--verbose", "Enable verbose logging")
+    .option("--config <file>", "Path to config file", load_config_1.DEFAULT_CONFIG_FILENAME)
+    .option("--yes", "Skip interactive confirmation (for CI/CD)");
+program.parse(process.argv);
+const opts = program.opts();
+async function main() {
+    // Validate conflicting flags
+    if (opts["dryRun"] && opts["execute"]) {
+        console.error("Error: --dry-run and --execute cannot both be specified.");
+        process.exit(1);
+    }
+    const configFilePath = path.resolve(opts["config"] || load_config_1.DEFAULT_CONFIG_FILENAME);
+    const configExists = fs.existsSync(configFilePath);
+    let applyConfig;
+    if (configExists) {
+        const config = (0, load_config_1.loadConfig)(configFilePath);
+        applyConfig = config.apply;
+    }
+    // Determine dryRun: --execute overrides config/default dryRun
+    const dryRunFromCli = resolveDryRunFromCli(opts["execute"], opts["dryRun"]);
+    // Build resolved options from CLI args + config
+    const cliArgs = {
+        destPgHost: opts["destPgHost"],
+        destPgPort: opts["destPgPort"],
+        destPgDatabase: opts["destPgDatabase"],
+        destPgUser: opts["destPgUser"],
+        destPgPassword: opts["destPgPasswordEnv"],
+        destPgSsl: normalizeOptionalBoolean(opts["destPgSsl"]),
+        input: opts["input"],
+        dryRun: dryRunFromCli,
+        applyInserts: normalizeOptionalBoolean(opts["applyInserts"]),
+        applyUpdates: normalizeOptionalBoolean(opts["applyUpdates"]),
+        applyDeletes: normalizeOptionalBoolean(opts["applyDeletes"]),
+        conflictMode: opts["conflictMode"],
+        insertMode: opts["insertMode"],
+        transaction: normalizeOptionalBoolean(opts["transaction"]),
+        verbose: opts["verbose"] ? true : undefined,
+    };
+    // Remove undefined values
+    const cleanCliArgs = Object.fromEntries(Object.entries(cliArgs).filter(([, v]) => v !== undefined));
+    const resolved = (0, resolve_options_1.resolveApplyOptions)(applyConfig, cleanCliArgs);
+    const runtimeResolved = (0, resolve_options_1.resolveRuntimeApplyOptions)(resolved);
+    // Validate required values
+    if (!resolved.destPgHost ||
+        !resolved.destPgDatabase ||
+        !resolved.destPgUser ||
+        !resolved.destPgPassword) {
+        console.error("Error: Missing required destination database connection options.");
+        console.error("Provide --dest-pg-host, --dest-pg-database, --dest-pg-user, --dest-pg-password-env");
+        console.error("or configure them in .frg-data-diff.config.json");
+        process.exit(1);
+    }
+    if (!runtimeResolved.input) {
+        console.error("Error: Missing required --input diff file path.");
+        process.exit(1);
+    }
+    const inputPath = path.resolve(runtimeResolved.input);
+    if (!fs.existsSync(inputPath)) {
+        console.error(`Error: Diff file not found: ${inputPath}`);
+        process.exit(1);
+    }
+    // Validate conflict mode
+    const destConnection = (0, connection_1.resolveConnectionParams)({
+        host: resolved.destPgHost,
+        port: resolved.destPgPort,
+        database: resolved.destPgDatabase,
+        user: resolved.destPgUser,
+        password: resolved.destPgPassword,
+        ssl: runtimeResolved.destPgSsl,
+    }, {
+        host: "destination host",
+        port: "destination port",
+        database: "destination database",
+        user: "destination user",
+        password: "destination password",
+    });
+    // Print resolved plan
+    printResolvedApplyPlan(resolved, runtimeResolved, inputPath, destConnection);
+    // Ask for confirmation if no --yes flag
+    if (!opts["yes"]) {
+        const proceed = await (0, prompts_1.confirmProceed)();
+        if (!proceed) {
+            console.log("Aborted.");
+            process.exit(0);
+        }
+    }
+    // Load and validate the diff file
+    let rawDiff;
+    try {
+        const content = fs.readFileSync(inputPath, "utf-8");
+        rawDiff = JSON.parse(content);
+    }
+    catch (err) {
+        console.error(`Error reading diff file: ${inputPath}`);
+        if (err instanceof Error)
+            console.error(err.message);
+        process.exit(1);
+    }
+    let diff;
+    try {
+        diff = (0, diff_schema_1.validateDiffJson)(rawDiff);
+    }
+    catch (err) {
+        console.error("Diff file validation failed:");
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    if (runtimeResolved.dryRun) {
+        console.log("\n[DRY RUN] No changes will be made to the destination database.");
+    }
+    else {
+        console.log("\nApplying changes to destination database...");
+    }
+    const destPool = (0, connection_1.createPool)(destConnection);
+    try {
+        const summary = await (0, plan_1.runApply)(destPool, diff, {
+            dryRun: runtimeResolved.dryRun,
+            applyInserts: runtimeResolved.applyInserts,
+            applyUpdates: runtimeResolved.applyUpdates,
+            applyDeletes: runtimeResolved.applyDeletes,
+            conflictMode: runtimeResolved.conflictMode,
+            insertMode: runtimeResolved.insertMode,
+            transaction: runtimeResolved.transaction,
+            verbose: resolved.verbose,
+        });
+        (0, summary_1.printSummary)(summary, runtimeResolved.dryRun);
+        // Output machine-readable summary
+        console.log("\nMachine-readable summary:");
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    finally {
+        await destPool.end();
+    }
+}
+function printResolvedApplyPlan(resolved, runtimeResolved, inputPath, destConnection) {
+    const resolvedDest = destConnection ??
+        (0, connection_1.resolveConnectionParams)({
+            host: resolved.destPgHost,
+            port: resolved.destPgPort,
+            database: resolved.destPgDatabase,
+            user: resolved.destPgUser,
+            password: resolved.destPgPassword,
+            ssl: runtimeResolved.destPgSsl,
+        }, {
+            host: "destination host",
+            port: "destination port",
+            database: "destination database",
+            user: "destination user",
+            password: "destination password",
+        });
+    console.log("\ntool:");
+    console.log("  frg-data-diff apply");
+    console.log("\ndest:");
+    console.log(`  host: ${(0, env_values_1.formatVisibleValue)(resolved.destPgHost, resolvedDest.host)}`);
+    console.log(`  port: ${typeof resolved.destPgPort === "string" ? `${resolved.destPgPort} -> ${resolvedDest.port}` : resolvedDest.port}`);
+    console.log(`  database: ${(0, env_values_1.formatVisibleValue)(resolved.destPgDatabase, resolvedDest.database)}`);
+    console.log(`  user: ${(0, env_values_1.formatVisibleValue)(resolved.destPgUser, resolvedDest.user)}`);
+    console.log(`  password: ${(0, env_values_1.formatSecretValue)(String(resolved.destPgPassword))}`);
+    console.log(`  ssl: ${runtimeResolved.destPgSsl}`);
+    console.log(`\ninput: ${inputPath}`);
+    console.log(`dry-run: ${runtimeResolved.dryRun}`);
+    console.log(`apply inserts: ${runtimeResolved.applyInserts}`);
+    console.log(`apply updates: ${runtimeResolved.applyUpdates}`);
+    console.log(`apply deletes: ${runtimeResolved.applyDeletes}`);
+    console.log(`conflict mode: ${runtimeResolved.conflictMode}`);
+    console.log(`insert mode: ${runtimeResolved.insertMode}`);
+    console.log(`transaction: ${runtimeResolved.transaction}`);
+    if (runtimeResolved.applyDeletes) {
+        console.log("\nWarning: applyDeletes is enabled. Rows may be deleted from the destination database.");
+    }
+}
+main().catch((err) => {
+    console.error("Fatal error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});
+function normalizeOptionalBoolean(value) {
+    if (value === true) {
+        return true;
+    }
+    if (value === false) {
+        return false;
+    }
+    return undefined;
+}
+function resolveDryRunFromCli(execute, dryRun) {
+    if (execute === true) {
+        return false;
+    }
+    if (dryRun === true) {
+        return true;
+    }
+    return undefined;
+}
+//# sourceMappingURL=apply.js.map

package/dist/cli/generator.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * frg-data-diff generate
+ *
+ * Compares a source PostgreSQL database against a destination PostgreSQL database
+ * and writes a JSON diff file.
+ */
+export {};
+//# sourceMappingURL=generator.d.ts.map