pgpm 5.19.1 → 5.21.0

package/commands/cache.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const inquirerer_1 = require("inquirerer");
 const genomic_1 = require("genomic");
+const inquirerer_1 = require("inquirerer");
 const cacheUsageText = `
 Cache Command:
 

package/commands/diff.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: Partial<ParsedArgs>, prompter: Inquirerer, _options: CLIOptions) => Promise<Partial<ParsedArgs>>;
+export default _default;

package/commands/diff.js

@@ -0,0 +1,359 @@
+"use strict";
+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 core_1 = require("@pgpmjs/core");
+const diff_1 = require("@pgpmjs/diff");
+const logger_1 = require("@pgpmjs/logger");
+const transform_1 = require("@pgpmjs/transform");
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const inquirerer_1 = require("inquirerer");
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const pg_cache_1 = require("pg-cache");
+const pg_env_1 = require("pg-env");
+const module_projections_1 = require("../utils/module-projections");
+const scratch_db_1 = require("../utils/scratch-db");
+const log = new logger_1.Logger('diff');
+const diffUsageText = `
+Diff Command:
+
+  pgpm diff <A> <B> [OPTIONS]
+
+  Identity-keyed semantic diff between two schema sources. Each side is
+  normalized to an object set keyed by identity (kind/schema/name), so the
+  same schema authored at different granularity, naming, or partitioning
+  diffs as empty. Tables are compared column-by-column and
+  constraint-by-constraint, so table changes emit ALTER TABLE, not a rebuild.
+
+Sides:
+  <A> / <B> may each be:
+    - a pgpm module directory (flattened in plan order)
+    - a raw .sql file
+    - a live database: a postgres:// connection string, or db:<name>
+      (uses PG* env for host/port/user; schema is read via pg_dump)
+
+The delta is one model; every --emit-* flag is a projection of it, so they
+compose (a single run can emit a module, a linear SQL file, and a bundle).
+
+Options:
+  --help, -h               Show this help message
+  --emit-migration <dir>   Write the delta as a pgpm module (deploy/revert/
+                           verify per change, spec-derived paths, graph-derived
+                           requires) into <dir>/<pkg>
+  --emit-module <dir>      Alias of --emit-migration
+  --append-module <dir>    Append the delta into an EXISTING pgpm module at
+                           <dir> (new changes only; existing changes, scripts,
+                           and .control are left untouched). Standalone: not
+                           combinable with --emit-*/--verify.
+  --emit-sql <file|->      Also project the delta to a single consolidated SQL
+                           file (deparsed in plan order); - writes to stdout
+  --emit-bundle <file>     Also project the delta to a content-addressed
+                           .bundle.tar.gz archive
+  --pkg <name>             Emitted migration package name (default: diff-migration)
+  --granularity <level>    Granularity for emitted changes: atomic | object |
+                           consolidated (default: object)
+  --change-granularity <level>
+                           Change-level distribution for emitted changes:
+                           alteration | object | single (default: object)
+  --naming <style>         Change path naming style: directory | flat (default: directory)
+  --json                   Machine-readable output
+  --verify                 Oracle mode: deploy A plus the emitted migration into
+                           a scratch database and assert catalog equivalence
+                           with B deployed fresh
+  --cwd <directory>        Working directory (default: current directory)
+
+Exit status: 0 when the sides are identical or the diff succeeds; non-zero on
+error or when --verify finds the migrated catalog differs from B.
+
+Examples:
+  pgpm diff ./v1-module ./v2-module
+  pgpm diff ./v1-module ./schema-v2.sql --json
+  pgpm diff db:app_v1 db:app_v2 --emit-migration ./out --verify
+`;
+const NAMING_STYLES = ['directory', 'flat'];
+/** pg_dump a side's schema: `db:<name>` uses PG* env; DSNs pass through. */
+const dumpDatabase = async (spec) => {
+    const args = ['--schema-only', '--no-owner'];
+    let env = process.env;
+    if (spec.startsWith('db:')) {
+        const config = (0, pg_env_1.getPgEnvOptions)({ database: spec.slice(3) });
+        env = (0, pg_env_1.getSpawnEnvWithPg)(config);
+    }
+    else {
+        args.push('--dbname', spec);
+    }
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('pg_dump', args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', chunk => { out += chunk; });
+        child.stderr.on('data', chunk => { err += chunk; });
+        child.on('error', (e) => {
+            if (e.code === 'ENOENT') {
+                reject(new Error('pg_dump not found; ensure PostgreSQL client tools are installed and in PATH'));
+                return;
+            }
+            reject(e);
+        });
+        child.on('close', code => {
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`pg_dump exited with code ${code}: ${err.trim()}`));
+        });
+    });
+};
+/** Resolve one side spec into diff input changes. */
+const loadSide = async (spec, cwd) => {
+    if (resolveDiffSideKindSafe(spec) === 'database') {
+        const label = spec.startsWith('db:') ? spec.slice(3) : spec;
+        return {
+            kind: 'database',
+            label,
+            changes: (0, diff_1.sqlToDiffChanges)(await dumpDatabase(spec), label),
+            warnings: []
+        };
+    }
+    return (0, diff_1.loadDiffSideFromDisk)(path.resolve(cwd, spec));
+};
+/** `resolveDiffSideKind` without throwing on relative on-disk paths. */
+const resolveDiffSideKindSafe = (spec) => /^postgres(ql)?:\/\//.test(spec) || spec.startsWith('db:') ? 'database' : 'disk';
+/** Apply one diff side into a scratch database (module deploy or raw SQL). */
+const applySide = async (config, side, spec, cwd) => {
+    if (side.kind === 'module') {
+        const client = new core_1.PgpmMigrate(config);
+        const result = await client.deploy({ modulePath: path.resolve(cwd, spec) });
+        if (result.failed) {
+            throw new Error(`deploy failed at change ${result.failed} (module ${spec})`);
+        }
+        return;
+    }
+    const pool = (0, pg_cache_1.getPgPool)(config);
+    const sql = side.changes.map(c => c.deploy).filter(Boolean).join('\n\n');
+    if (sql.trim())
+        await pool.query(sql);
+};
+/**
+ * Oracle mode: deploy A into a scratch database, deploy the emitted migration
+ * module on top (when there is one), and assert catalog equivalence with B
+ * deployed fresh into a second scratch database. Column order is physical — a
+ * drop+add migration cannot reproduce a fresh deploy's ordinals — so
+ * equivalence is checked order-insensitively via `withoutColumnOrder`.
+ */
+const runVerify = async (sideA, sideB, specA, specB, migrationDir, cwd) => {
+    const config = (0, pg_env_1.getPgEnvOptions)();
+    const stamp = Date.now();
+    const names = [`pgpm_diff_verify_a_${stamp}`, `pgpm_diff_verify_b_${stamp}`];
+    return (0, scratch_db_1.withScratchDatabases)(config, names, async ([cfgMigrated, cfgTarget]) => {
+        await applySide(cfgMigrated, sideA, specA, cwd);
+        if (migrationDir) {
+            const result = await new core_1.PgpmMigrate(cfgMigrated).deploy({ modulePath: migrationDir });
+            if (result.failed) {
+                throw new Error(`migration deploy failed at change ${result.failed}`);
+            }
+        }
+        await applySide(cfgTarget, sideB, specB, cwd);
+        return (0, scratch_db_1.catalogDifferences)(cfgMigrated, cfgTarget, transform_1.withoutColumnOrder);
+    });
+};
+const printSummary = (result, labelA, labelB) => {
+    if (result.identical) {
+        console.log(`No differences: ${labelA} and ${labelB} describe the same objects.`);
+        return;
+    }
+    const byDelta = (delta) => result.objects.filter(o => o.delta === delta);
+    const section = (title, objects) => {
+        if (objects.length === 0)
+            return;
+        console.log(`${title} (${objects.length}):`);
+        for (const obj of objects) {
+            const detail = [];
+            if (obj.columnsAdded?.length)
+                detail.push(`+cols: ${obj.columnsAdded.join(', ')}`);
+            if (obj.columnsRemoved?.length)
+                detail.push(`-cols: ${obj.columnsRemoved.join(', ')}`);
+            if (obj.columnsModified?.length)
+                detail.push(`~cols: ${obj.columnsModified.join(', ')}`);
+            console.log(`  ${obj.identity.kind} ${obj.path}${detail.length ? ` (${detail.join('; ')})` : ''}`);
+        }
+    };
+    section('Added', byDelta('added'));
+    section('Removed', byDelta('removed'));
+    section('Changed', byDelta('modified'));
+    console.log(`${result.changes.length} migration change(s) derivable.`);
+};
+exports.default = async (argv, prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(diffUsageText);
+        process.exit(0);
+    }
+    const { first: specA, newArgv } = (0, inquirerer_1.extractFirst)(argv);
+    const { first: specB, newArgv: restArgv } = (0, inquirerer_1.extractFirst)(newArgv);
+    argv = restArgv;
+    if (!specA || !specB) {
+        await (0, inquirerer_1.cliExitWithError)('pgpm diff requires two sides: pgpm diff <A> <B> (module dir, .sql file, db:<name>, or connection string).');
+    }
+    const granularityRaw = argv.granularity ?? 'object';
+    if (!(0, transform_1.isExportGranularity)(granularityRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --granularity "${granularityRaw}". Expected one of: ${transform_1.EXPORT_GRANULARITIES.join(', ')}.`);
+    }
+    const granularity = granularityRaw;
+    const changeGranularityRaw = argv['change-granularity'] ?? argv.changeGranularity ?? 'object';
+    if (!(0, transform_1.isChangeGranularity)(changeGranularityRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --change-granularity "${changeGranularityRaw}". Expected one of: ${transform_1.CHANGE_GRANULARITIES.join(', ')}.`);
+    }
+    const changeGranularity = changeGranularityRaw;
+    const namingRaw = argv.naming ?? 'directory';
+    if (!NAMING_STYLES.includes(namingRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
+    }
+    const naming = namingRaw;
+    const cwd = argv.cwd || process.cwd();
+    const json = Boolean(argv.json);
+    const verify = Boolean(argv.verify);
+    const emitModuleRaw = argv['emit-migration'] ?? argv.emitMigration ?? argv['emit-module'] ?? argv.emitModule;
+    const emitModuleDir = typeof emitModuleRaw === 'string' && emitModuleRaw
+        ? path.resolve(cwd, emitModuleRaw)
+        : undefined;
+    const appendModuleRaw = argv['append-module'] ?? argv.appendModule;
+    const appendModuleDir = typeof appendModuleRaw === 'string' && appendModuleRaw
+        ? path.resolve(cwd, appendModuleRaw)
+        : undefined;
+    const emitSqlRaw = argv['emit-sql'] ?? argv.emitSql;
+    const emitSql = typeof emitSqlRaw === 'string' && emitSqlRaw
+        ? (emitSqlRaw === module_projections_1.STDOUT_TARGET ? module_projections_1.STDOUT_TARGET : path.resolve(cwd, emitSqlRaw))
+        : undefined;
+    const emitBundleRaw = argv['emit-bundle'] ?? argv.emitBundle;
+    const emitBundle = typeof emitBundleRaw === 'string' && emitBundleRaw
+        ? path.resolve(cwd, emitBundleRaw)
+        : undefined;
+    const sqlToStdout = emitSql === module_projections_1.STDOUT_TARGET;
+    const pkgName = argv.pkg || 'diff-migration';
+    if (appendModuleDir && (emitModuleDir || emitSql || emitBundle || verify)) {
+        await (0, inquirerer_1.cliExitWithError)('--append-module is standalone; it cannot be combined with --emit-migration/--emit-module/--emit-sql/--emit-bundle/--verify.');
+    }
+    await (0, transform_1.loadModule)();
+    let sideA;
+    let sideB;
+    try {
+        sideA = await loadSide(specA, cwd);
+        sideB = await loadSide(specB, cwd);
+    }
+    catch (err) {
+        await (0, inquirerer_1.cliExitWithError)(err instanceof Error ? err.message : String(err));
+        return;
+    }
+    const result = (0, transform_1.diffChangeSets)(sideA.changes, sideB.changes, { granularity, changeGranularity, style: naming });
+    const warnings = [
+        ...sideA.warnings.map(w => `${sideA.label}: ${w}`),
+        ...sideB.warnings.map(w => `${sideB.label}: ${w}`),
+        ...result.warnings
+    ];
+    if (json) {
+        console.log(JSON.stringify({
+            identical: result.identical,
+            objects: result.objects,
+            changes: result.changes.map(c => ({
+                name: c.name,
+                dependencies: c.dependencies,
+                deploy: c.deploy,
+                revert: c.revert,
+                verify: c.verify
+            })),
+            warnings
+        }, null, 2));
+    }
+    else {
+        for (const warning of warnings)
+            console.warn(`diff: ${warning}`);
+        // Keep stdout clean when the SQL projection is piped there.
+        if (!sqlToStdout)
+            printSummary(result, sideA.label, sideB.label);
+    }
+    if (appendModuleDir) {
+        const rows = (0, diff_1.deltaChangesToRows)(result.changes);
+        if (rows.length === 0) {
+            log.info('no migration changes to append (sides are identical).');
+        }
+        else {
+            const appended = (0, transform_1.appendModule)(appendModuleDir, rows);
+            for (const w of appended.warnings)
+                console.warn(`diff: ${w}`);
+            log.success(`appended ${appended.added.length} change(s) to ${appended.dir}` +
+                (appended.skipped.length ? ` (${appended.skipped.length} skipped)` : ''));
+        }
+        prompter.close();
+        return argv;
+    }
+    let migrationDir;
+    const needModule = Boolean(emitModuleDir || emitSql || emitBundle) || (verify && !result.identical);
+    if (needModule) {
+        const outBase = emitModuleDir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'pgpm-diff-'));
+        const rows = (0, diff_1.deltaChangesToRows)(result.changes);
+        if (rows.length === 0) {
+            if (!sqlToStdout)
+                log.info('no migration changes to emit (sides are identical).');
+        }
+        else {
+            migrationDir = (0, transform_1.writeModule)(outBase, { name: pkgName, requires: [], rows });
+            if (emitModuleDir && !sqlToStdout)
+                log.success(`wrote ${rows.length} migration change(s) to ${migrationDir}`);
+            if (emitSql) {
+                await (0, module_projections_1.emitModuleSql)(migrationDir, emitSql);
+                if (!sqlToStdout)
+                    log.success(`wrote linear SQL to ${emitSql}`);
+            }
+            if (emitBundle) {
+                await (0, module_projections_1.emitModuleBundle)(migrationDir, emitBundle);
+                if (!sqlToStdout)
+                    log.success(`wrote bundle to ${emitBundle}`);
+            }
+        }
+    }
+    if (verify) {
+        log.info('running --verify: deploying A plus the migration and B into scratch databases...');
+        const diffs = await runVerify(sideA, sideB, specA, specB, migrationDir, cwd);
+        if (diffs.length) {
+            console.error(`--verify failed: catalogs differ (${diffs.length} differences):`);
+            for (const diff of diffs)
+                console.error(`  ${diff}`);
+            await (0, inquirerer_1.cliExitWithError)('Migrated catalog does not match the target.');
+        }
+        log.success('--verify passed: migrated catalog is structurally equivalent to the target.');
+    }
+    prompter.close();
+    return argv;
+};

package/commands/dump.js

@@ -4,12 +4,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const logger_1 = require("@pgpmjs/logger");
-const pg_env_1 = require("pg-env");
-const pg_cache_1 = require("pg-cache");
+const quotes_1 = require("@pgsql/quotes");
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const quotes_1 = require("@pgsql/quotes");
+const pg_cache_1 = require("pg-cache");
+const pg_env_1 = require("pg-env");
 const utils_1 = require("../utils");
 const log = new logger_1.Logger('dump');
 const dumpUsageText = `

package/commands/export.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@pgpmjs/core");
-const export_1 = require("@pgpmjs/export");
 const env_1 = require("@pgpmjs/env");
+const export_1 = require("@pgpmjs/export");
+const transform_1 = require("@pgpmjs/transform");
 const types_1 = require("@pgpmjs/types");
 const path_1 = require("path");
 const pg_cache_1 = require("pg-cache");
@@ -30,12 +31,16 @@ Options:
                           Change paths are derived from the naming spec and
                           requires from the statement graph. When omitted,
                           sql_actions rows are exported unchanged.
+  --partition <file>      Partition config (JSON: rules/defaultPackage/splitRiders)
+                          splitting the exported database module into multiple
+                          pgpm packages with derived cross-package requires.
   --cwd <directory>       Working directory (default: current directory)
 
 Examples:
   pgpm export              Export migrations from selected database (SQL mode)
   pgpm export --exclude-categories security,permissions,auth,memberships
   pgpm export --granularity consolidated
+  pgpm export --granularity object --partition partition.json
   pgpm export --graphql-endpoint 'http://[::1]:3002/graphql' --migrate-endpoint 'http://[::1]:3000/graphql' --migrate-host db_migrate.localhost:3000
 `;
 exports.default = async (argv, prompter, _options) => {
@@ -61,12 +66,24 @@ exports.default = async (argv, prompter, _options) => {
             ? excludeCategoriesRaw
             : undefined;
     const granularityRaw = argv.granularity;
-    if (granularityRaw !== undefined && !(0, export_1.isExportGranularity)(granularityRaw)) {
-        console.error(`Invalid --granularity "${granularityRaw}". Expected one of: ${export_1.EXPORT_GRANULARITIES.join(', ')}.`);
+    if (granularityRaw !== undefined && !(0, transform_1.isExportGranularity)(granularityRaw)) {
+        console.error(`Invalid --granularity "${granularityRaw}". Expected one of: ${transform_1.EXPORT_GRANULARITIES.join(', ')}.`);
         prompter.close();
         return;
     }
     const granularity = granularityRaw;
+    const partitionRaw = argv.partition;
+    let partition;
+    if (typeof partitionRaw === 'string' && partitionRaw) {
+        try {
+            partition = (0, transform_1.parsePartitionConfig)((0, path_1.resolve)(cwd, partitionRaw));
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            prompter.close();
+            return;
+        }
+    }
     if (graphqlEndpoint) {
         // =========================================================================
         // GraphQL export mode
@@ -164,7 +181,8 @@ exports.default = async (argv, prompter, _options) => {
             argv,
             username,
             excludeCategories,
-            granularity
+            granularity,
+            partition
         });
     }
     else {
@@ -285,7 +303,8 @@ exports.default = async (argv, prompter, _options) => {
             argv,
             username,
             excludeCategories,
-            granularity
+            granularity,
+            partition
         });
     }
     prompter.close();

package/commands/import.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: Partial<ParsedArgs>, prompter: Inquirerer, _options: CLIOptions) => Promise<Partial<ParsedArgs>>;
+export default _default;