pgpm 5.19.1 → 5.20.0

package/esm/utils/module-projections.js

@@ -0,0 +1,47 @@
+/**
+ * Projections of an emitted pgpm module directory.
+ *
+ * A module directory is the canonical artifact the dials pipeline produces
+ * (`writeModule` from `@pgpmjs/transform`). "Linear SQL" and "bundle" are not
+ * separate emitters — they are pure projections of that one module, produced
+ * by the same battle-tested machinery `pgpm package` uses:
+ *
+ *   - {@link emitModuleSql}    -> consolidated single-file SQL (`packageModule`)
+ *   - {@link emitModuleBundle} -> content-addressed bundle (`buildExecutableBundle`)
+ *
+ * They live in the CLI (not `@pgpmjs/transform`) because they reuse packaging
+ * and bundle code from `@pgpmjs/core`, and `core` already depends on
+ * `transform`.
+ */
+import { buildExecutableBundle, packageModule, writeBundleArchiveFile } from '@pgpmjs/core';
+import * as fs from 'fs';
+import * as path from 'path';
+/** Sentinel meaning "write to stdout" for a file-valued emit target. */
+export const STDOUT_TARGET = '-';
+/**
+ * Consolidate an emitted module directory into a single linear SQL script.
+ * Statements are resolved in plan order and deparsed once (comments and
+ * per-change file boundaries collapse away). When `target` is `-` the SQL is
+ * written to stdout; otherwise it is written to the given file path.
+ */
+export const emitModuleSql = async (moduleDir, target) => {
+    const { sql } = await packageModule(moduleDir, { extension: false, usePlan: true, pretty: true });
+    if (target === STDOUT_TARGET) {
+        process.stdout.write(sql.endsWith('\n') ? sql : sql + '\n');
+        return;
+    }
+    const resolved = path.resolve(target);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, sql.endsWith('\n') ? sql : sql + '\n');
+};
+/**
+ * Project an emitted module directory into a content-addressed bundle archive
+ * (`.bundle.tar.gz`) at `target` — the same executable bundle `pgpm package`
+ * stores beside the packaged SQL, but written to an arbitrary path.
+ */
+export const emitModuleBundle = async (moduleDir, target) => {
+    const bundle = await buildExecutableBundle(moduleDir, { createdWith: '@pgpmjs/cli' });
+    const resolved = path.resolve(target);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    writeBundleArchiveFile(bundle, resolved);
+};

package/esm/utils/scratch-db.js

@@ -0,0 +1,61 @@
+/**
+ * Scratch-database catalog oracle shared by the dials commands that prove
+ * structural equivalence (`pgpm transform --check`, `pgpm diff --verify`).
+ *
+ * Both commands do the same dance: create throwaway databases, deploy a
+ * schema into each, snapshot the catalogs, and diff them — always dropping the
+ * scratch databases afterwards even on failure. This centralizes the lifecycle
+ * (`withScratchDatabases`) and the snapshot/compare step (`catalogDifferences`)
+ * so each command only supplies what is genuinely command-specific: how it
+ * deploys a side.
+ *
+ * It lives in the CLI (not `@pgpmjs/transform`) because deploying touches
+ * `PgpmMigrate` from `@pgpmjs/core`, and `core` already depends on `transform`
+ * — hosting the oracle in `transform` would close that cycle.
+ */
+import { diffCatalogSnapshots, snapshotCatalog } from '@pgpmjs/transform';
+import { Logger } from '@pgpmjs/logger';
+import { getPgPool } from 'pg-cache';
+const log = new Logger('scratch-db');
+const createScratchDb = async (config, dbName) => {
+    const adminPool = getPgPool({ ...config, database: 'postgres' });
+    await adminPool.query(`DROP DATABASE IF EXISTS "${dbName}"`);
+    await adminPool.query(`CREATE DATABASE "${dbName}"`);
+};
+const dropScratchDb = async (config, dbName) => {
+    const adminPool = getPgPool({ ...config, database: 'postgres' });
+    await adminPool.query(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
+};
+/**
+ * Create the named scratch databases, run `fn` with a per-database `PgConfig`
+ * for each (in the same order as `names`), and drop them all afterwards —
+ * even if `fn` throws. Drop failures are logged, never thrown, so they can't
+ * mask the original error.
+ */
+export const withScratchDatabases = async (config, names, fn) => {
+    try {
+        for (const name of names)
+            await createScratchDb(config, name);
+        return await fn(names.map(name => ({ ...config, database: name })));
+    }
+    finally {
+        try {
+            for (const name of names)
+                await dropScratchDb(config, name);
+        }
+        catch (err) {
+            log.warn(`failed to drop scratch databases: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+};
+/**
+ * Snapshot the catalogs of two databases and return their differences. An
+ * optional `normalize` transform is applied to both snapshots first (e.g.
+ * `withoutColumnOrder` when a drop+add migration cannot reproduce a fresh
+ * deploy's physical column ordinals). Empty result means equivalent.
+ */
+export const catalogDifferences = async (configA, configB, normalize = snap => snap) => {
+    const snapA = await snapshotCatalog(getPgPool(configA));
+    const snapB = await snapshotCatalog(getPgPool(configB));
+    return diffCatalogSnapshots(normalize(snapA), normalize(snapB));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgpm",
-  "version": "5.19.1",
+  "version": "5.20.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL Package Manager - Database migration and package management CLI",
   "main": "index.js",
@@ -46,22 +46,24 @@
   },
   "dependencies": {
     "@inquirerer/utils": "^3.3.9",
-    "@pgpmjs/core": "^7.21.2",
-    "@pgpmjs/env": "^2.40.2",
-    "@pgpmjs/export": "^1.14.2",
-    "@pgpmjs/logger": "^2.23.2",
-    "@pgpmjs/slice": "^0.13.7",
-    "@pgpmjs/transform": "^0.18.0",
-    "@pgpmjs/types": "^2.49.2",
-    "@pgsql/quotes": "^18.1.0",
+    "@pgpmjs/core": "^7.21.3",
+    "@pgpmjs/diff": "^0.1.1",
+    "@pgpmjs/env": "^2.40.3",
+    "@pgpmjs/export": "^1.15.0",
+    "@pgpmjs/import": "^0.1.1",
+    "@pgpmjs/logger": "^2.23.3",
+    "@pgpmjs/slice": "^0.13.8",
+    "@pgpmjs/transform": "^0.19.0",
+    "@pgpmjs/types": "^2.49.3",
+    "@pgsql/quotes": "^18.2.0",
     "appstash": "^0.7.0",
     "find-and-require-package-json": "^0.9.1",
     "genomic": "^5.6.2",
     "inquirerer": "^4.9.1",
     "js-yaml": "^4.1.0",
-    "pg-cache": "^3.24.2",
+    "pg-cache": "^3.24.3",
     "pg-env": "^1.27.2",
-    "pgsql-deparser": "^18.2.0",
+    "pgsql-deparser": "^18.3.1",
     "semver": "^7.8.1",
     "shelljs": "^0.10.0",
     "yanse": "^0.2.1"
@@ -78,5 +80,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "6d3e25dc5c9f93421dba49ddedf93239f87213a8"
+  "gitHead": "c20b6be96b39bf71c0e2df0f4b51e05deacd006b"
 }

package/utils/display.d.ts

@@ -1 +1 @@
-export declare const usageText = "\n  Usage: pgpm <command> [options]\n\n  Core Database Operations:\n    add                Add database changes to plans and create SQL files\n    deploy             Deploy database changes and migrations\n    verify             Verify database state and migrations\n    revert             Revert database changes and migrations\n\n  Project Management:\n    init               Initialize workspace or module\n    extension          Manage module dependencies\n    plan               Generate module deployment plans\n    regen              Generate revert/verify scripts from deploy scripts\n    package            Package module for distribution\n    materialize        Transpile an apply proxy into a plain, committed module\n    sync-versions      Sync .control/Makefile/sql metadata to package.json versions\n    export             Export database migrations from existing databases\n    update             Update pgpm to the latest version\n    cache              Manage cached templates (clean)\n    upgrade            Upgrade installed pgpm modules to latest versions (alias: up)\n\n  Database Administration:\n    dump               Dump a database to a sql file\n    kill               Terminate database connections and optionally drop databases\n    install            Install database modules\n    tag                Add tags to changes for versioning\n    clear              Clear database state\n    remove             Remove database changes\n    analyze            Analyze database structure\n    rename             Rename database changes\n    admin-users        Manage admin users\n    tune               Tune PostgreSQL for throwaway environments (CI/test)\n\n  Testing:\n    test-packages      Run integration tests on all workspace packages\n\n  Migration Tools:\n    migrate            Migration management subcommands\n      init             Initialize migration tracking\n      status           Show migration status\n      list             List all changes\n      deps             Show change dependencies\n  \n  Development Tools:\n    docker             Manage Docker containers (start/stop/ls, --minio)\n    doctor             Check local dependencies (node, docker, psql) with install guidance\n    env                Manage environment variables (--supabase, --minio)\n    test-packages      Run integration tests on workspace packages\n  \n  Global Options:\n    -h, --help         Display this help information\n    -v, --version      Display version information\n    --cwd <directory>  Working directory (default: current directory)\n    --engine <name>    Migration backend: pg (default, Postgres server) or\n                       pglite (in-process WASM Postgres, no server). Also set by\n                       the \"engine\" key of pgpm.json or PGPM_ENGINE.\n    --driver <pkg>     Driver plugin package backing the engine (escape hatch)\n    --pglite[=dataDir] Sugar for --engine pglite, persisted to <dataDir> if given\n\n  Individual Command Help:\n    pgpm <command> --help    Display detailed help for specific command\n    pgpm <command> -h        Display detailed help for specific command\n\n  Examples:\n    pgpm deploy --help       Show deploy command options\n    pgpm init workspace      Initialize new workspace\n    pgpm install @pgpm/base32  Install a database module\n  ";
+export declare const usageText = "\n  Usage: pgpm <command> [options]\n\n  Core Database Operations:\n    add                Add database changes to plans and create SQL files\n    deploy             Deploy database changes and migrations\n    verify             Verify database state and migrations\n    revert             Revert database changes and migrations\n\n  Project Management:\n    init               Initialize workspace or module\n    extension          Manage module dependencies\n    plan               Generate module deployment plans\n    regen              Generate revert/verify scripts from deploy scripts\n    transform          Re-dial a module through the dials pipeline (granularity/naming/partition)\n    import             pgpm-itize an arbitrary SQL dump into a deployable module\n    diff               Identity-keyed semantic diff between two schema sources (+ migration generation)\n    package            Package module for distribution\n    materialize        Transpile an apply proxy into a plain, committed module\n    sync-versions      Sync .control/Makefile/sql metadata to package.json versions\n    export             Export database migrations from existing databases\n    update             Update pgpm to the latest version\n    cache              Manage cached templates (clean)\n    upgrade            Upgrade installed pgpm modules to latest versions (alias: up)\n\n  Database Administration:\n    dump               Dump a database to a sql file\n    kill               Terminate database connections and optionally drop databases\n    install            Install database modules\n    tag                Add tags to changes for versioning\n    clear              Clear database state\n    remove             Remove database changes\n    analyze            Analyze database structure\n    rename             Rename database changes\n    admin-users        Manage admin users\n    tune               Tune PostgreSQL for throwaway environments (CI/test)\n\n  Testing:\n    test-packages      Run integration tests on all workspace packages\n\n  Migration Tools:\n    migrate            Migration management subcommands\n      init             Initialize migration tracking\n      status           Show migration status\n      list             List all changes\n      deps             Show change dependencies\n  \n  Development Tools:\n    docker             Manage Docker containers (start/stop/ls, --minio)\n    doctor             Check local dependencies (node, docker, psql) with install guidance\n    env                Manage environment variables (--supabase, --minio)\n    test-packages      Run integration tests on workspace packages\n  \n  Global Options:\n    -h, --help         Display this help information\n    -v, --version      Display version information\n    --cwd <directory>  Working directory (default: current directory)\n    --engine <name>    Migration backend: pg (default, Postgres server) or\n                       pglite (in-process WASM Postgres, no server). Also set by\n                       the \"engine\" key of pgpm.json or PGPM_ENGINE.\n    --driver <pkg>     Driver plugin package backing the engine (escape hatch)\n    --pglite[=dataDir] Sugar for --engine pglite, persisted to <dataDir> if given\n\n  Individual Command Help:\n    pgpm <command> --help    Display detailed help for specific command\n    pgpm <command> -h        Display detailed help for specific command\n\n  Examples:\n    pgpm deploy --help       Show deploy command options\n    pgpm init workspace      Initialize new workspace\n    pgpm install @pgpm/base32  Install a database module\n  ";

package/utils/display.js

@@ -15,6 +15,9 @@ exports.usageText = `
     extension          Manage module dependencies
     plan               Generate module deployment plans
     regen              Generate revert/verify scripts from deploy scripts
+    transform          Re-dial a module through the dials pipeline (granularity/naming/partition)
+    import             pgpm-itize an arbitrary SQL dump into a deployable module
+    diff               Identity-keyed semantic diff between two schema sources (+ migration generation)
     package            Package module for distribution
     materialize        Transpile an apply proxy into a plain, committed module
     sync-versions      Sync .control/Makefile/sql metadata to package.json versions

package/utils/driver.js

@@ -4,9 +4,9 @@ exports.PGLITE_DRIVER_PLUGIN = void 0;
 exports.resolveDriverConfig = resolveDriverConfig;
 exports.driverOverrideFromArgv = driverOverrideFromArgv;
 exports.activateDriver = activateDriver;
-const types_1 = require("@pgpmjs/types");
 const node_module_1 = require("node:module");
 const node_path_1 = require("node:path");
+const types_1 = require("@pgpmjs/types");
 /** Package name of the built-in PGlite driver plugin (the `--pglite` alias). */
 exports.PGLITE_DRIVER_PLUGIN = '@pgpmjs/pglite-adapter';
 /**

package/utils/emit-package.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared module emission for the dials commands (`pgpm transform`,
+ * `pgpm import`, `pgpm diff`). The implementation lives in `@pgpmjs/transform`
+ * (`module-emit`) so every command renders through one writer; this module is
+ * a thin re-export that keeps the CLI's local names (`writePackage`,
+ * `EmitPackage`) stable.
+ */
+export type { PgpmModuleModel as EmitPackage } from '@pgpmjs/transform';
+export { checkOverwrite, writeControlFile, writeModule as writePackage } from '@pgpmjs/transform';

package/utils/emit-package.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writePackage = exports.writeControlFile = exports.checkOverwrite = void 0;
+var transform_1 = require("@pgpmjs/transform");
+Object.defineProperty(exports, "checkOverwrite", { enumerable: true, get: function () { return transform_1.checkOverwrite; } });
+Object.defineProperty(exports, "writeControlFile", { enumerable: true, get: function () { return transform_1.writeControlFile; } });
+Object.defineProperty(exports, "writePackage", { enumerable: true, get: function () { return transform_1.writeModule; } });

package/utils/engine.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deactivateEngine = exports.activateEngine = exports.getActiveEngine = exports.resolveEngine = exports.engineDefinitions = exports.SERVER_CAPABILITIES = void 0;
+const node_path_1 = require("node:path");
 const env_1 = require("@pgpmjs/env");
 const types_1 = require("@pgpmjs/types");
-const node_path_1 = require("node:path");
 const driver_1 = require("./driver");
 /** Everything a real Postgres server can do — the built-in `pg` engine. */
 exports.SERVER_CAPABILITIES = {

package/utils/module-projections.d.ts

@@ -0,0 +1,15 @@
+/** Sentinel meaning "write to stdout" for a file-valued emit target. */
+export declare const STDOUT_TARGET = "-";
+/**
+ * Consolidate an emitted module directory into a single linear SQL script.
+ * Statements are resolved in plan order and deparsed once (comments and
+ * per-change file boundaries collapse away). When `target` is `-` the SQL is
+ * written to stdout; otherwise it is written to the given file path.
+ */
+export declare const emitModuleSql: (moduleDir: string, target: string) => Promise<void>;
+/**
+ * Project an emitted module directory into a content-addressed bundle archive
+ * (`.bundle.tar.gz`) at `target` — the same executable bundle `pgpm package`
+ * stores beside the packaged SQL, but written to an arbitrary path.
+ */
+export declare const emitModuleBundle: (moduleDir: string, target: string) => Promise<void>;

package/utils/module-projections.js

@@ -0,0 +1,85 @@
+"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 });
+exports.emitModuleBundle = exports.emitModuleSql = exports.STDOUT_TARGET = void 0;
+/**
+ * Projections of an emitted pgpm module directory.
+ *
+ * A module directory is the canonical artifact the dials pipeline produces
+ * (`writeModule` from `@pgpmjs/transform`). "Linear SQL" and "bundle" are not
+ * separate emitters — they are pure projections of that one module, produced
+ * by the same battle-tested machinery `pgpm package` uses:
+ *
+ *   - {@link emitModuleSql}    -> consolidated single-file SQL (`packageModule`)
+ *   - {@link emitModuleBundle} -> content-addressed bundle (`buildExecutableBundle`)
+ *
+ * They live in the CLI (not `@pgpmjs/transform`) because they reuse packaging
+ * and bundle code from `@pgpmjs/core`, and `core` already depends on
+ * `transform`.
+ */
+const core_1 = require("@pgpmjs/core");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Sentinel meaning "write to stdout" for a file-valued emit target. */
+exports.STDOUT_TARGET = '-';
+/**
+ * Consolidate an emitted module directory into a single linear SQL script.
+ * Statements are resolved in plan order and deparsed once (comments and
+ * per-change file boundaries collapse away). When `target` is `-` the SQL is
+ * written to stdout; otherwise it is written to the given file path.
+ */
+const emitModuleSql = async (moduleDir, target) => {
+    const { sql } = await (0, core_1.packageModule)(moduleDir, { extension: false, usePlan: true, pretty: true });
+    if (target === exports.STDOUT_TARGET) {
+        process.stdout.write(sql.endsWith('\n') ? sql : sql + '\n');
+        return;
+    }
+    const resolved = path.resolve(target);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, sql.endsWith('\n') ? sql : sql + '\n');
+};
+exports.emitModuleSql = emitModuleSql;
+/**
+ * Project an emitted module directory into a content-addressed bundle archive
+ * (`.bundle.tar.gz`) at `target` — the same executable bundle `pgpm package`
+ * stores beside the packaged SQL, but written to an arbitrary path.
+ */
+const emitModuleBundle = async (moduleDir, target) => {
+    const bundle = await (0, core_1.buildExecutableBundle)(moduleDir, { createdWith: '@pgpmjs/cli' });
+    const resolved = path.resolve(target);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    (0, core_1.writeBundleArchiveFile)(bundle, resolved);
+};
+exports.emitModuleBundle = emitModuleBundle;

package/utils/scratch-db.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Scratch-database catalog oracle shared by the dials commands that prove
+ * structural equivalence (`pgpm transform --check`, `pgpm diff --verify`).
+ *
+ * Both commands do the same dance: create throwaway databases, deploy a
+ * schema into each, snapshot the catalogs, and diff them — always dropping the
+ * scratch databases afterwards even on failure. This centralizes the lifecycle
+ * (`withScratchDatabases`) and the snapshot/compare step (`catalogDifferences`)
+ * so each command only supplies what is genuinely command-specific: how it
+ * deploys a side.
+ *
+ * It lives in the CLI (not `@pgpmjs/transform`) because deploying touches
+ * `PgpmMigrate` from `@pgpmjs/core`, and `core` already depends on `transform`
+ * — hosting the oracle in `transform` would close that cycle.
+ */
+import { CatalogSnapshot } from '@pgpmjs/transform';
+import type { PgConfig } from 'pg-env';
+/**
+ * Create the named scratch databases, run `fn` with a per-database `PgConfig`
+ * for each (in the same order as `names`), and drop them all afterwards —
+ * even if `fn` throws. Drop failures are logged, never thrown, so they can't
+ * mask the original error.
+ */
+export declare const withScratchDatabases: <T>(config: PgConfig, names: string[], fn: (configs: PgConfig[]) => Promise<T>) => Promise<T>;
+/**
+ * Snapshot the catalogs of two databases and return their differences. An
+ * optional `normalize` transform is applied to both snapshots first (e.g.
+ * `withoutColumnOrder` when a drop+add migration cannot reproduce a fresh
+ * deploy's physical column ordinals). Empty result means equivalent.
+ */
+export declare const catalogDifferences: (configA: PgConfig, configB: PgConfig, normalize?: (snap: CatalogSnapshot) => CatalogSnapshot) => Promise<string[]>;

package/utils/scratch-db.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catalogDifferences = exports.withScratchDatabases = void 0;
+/**
+ * Scratch-database catalog oracle shared by the dials commands that prove
+ * structural equivalence (`pgpm transform --check`, `pgpm diff --verify`).
+ *
+ * Both commands do the same dance: create throwaway databases, deploy a
+ * schema into each, snapshot the catalogs, and diff them — always dropping the
+ * scratch databases afterwards even on failure. This centralizes the lifecycle
+ * (`withScratchDatabases`) and the snapshot/compare step (`catalogDifferences`)
+ * so each command only supplies what is genuinely command-specific: how it
+ * deploys a side.
+ *
+ * It lives in the CLI (not `@pgpmjs/transform`) because deploying touches
+ * `PgpmMigrate` from `@pgpmjs/core`, and `core` already depends on `transform`
+ * — hosting the oracle in `transform` would close that cycle.
+ */
+const transform_1 = require("@pgpmjs/transform");
+const logger_1 = require("@pgpmjs/logger");
+const pg_cache_1 = require("pg-cache");
+const log = new logger_1.Logger('scratch-db');
+const createScratchDb = async (config, dbName) => {
+    const adminPool = (0, pg_cache_1.getPgPool)({ ...config, database: 'postgres' });
+    await adminPool.query(`DROP DATABASE IF EXISTS "${dbName}"`);
+    await adminPool.query(`CREATE DATABASE "${dbName}"`);
+};
+const dropScratchDb = async (config, dbName) => {
+    const adminPool = (0, pg_cache_1.getPgPool)({ ...config, database: 'postgres' });
+    await adminPool.query(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
+};
+/**
+ * Create the named scratch databases, run `fn` with a per-database `PgConfig`
+ * for each (in the same order as `names`), and drop them all afterwards —
+ * even if `fn` throws. Drop failures are logged, never thrown, so they can't
+ * mask the original error.
+ */
+const withScratchDatabases = async (config, names, fn) => {
+    try {
+        for (const name of names)
+            await createScratchDb(config, name);
+        return await fn(names.map(name => ({ ...config, database: name })));
+    }
+    finally {
+        try {
+            for (const name of names)
+                await dropScratchDb(config, name);
+        }
+        catch (err) {
+            log.warn(`failed to drop scratch databases: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+};
+exports.withScratchDatabases = withScratchDatabases;
+/**
+ * Snapshot the catalogs of two databases and return their differences. An
+ * optional `normalize` transform is applied to both snapshots first (e.g.
+ * `withoutColumnOrder` when a drop+add migration cannot reproduce a fresh
+ * deploy's physical column ordinals). Empty result means equivalent.
+ */
+const catalogDifferences = async (configA, configB, normalize = snap => snap) => {
+    const snapA = await (0, transform_1.snapshotCatalog)((0, pg_cache_1.getPgPool)(configA));
+    const snapB = await (0, transform_1.snapshotCatalog)((0, pg_cache_1.getPgPool)(configB));
+    return (0, transform_1.diffCatalogSnapshots)(normalize(snapA), normalize(snapB));
+};
+exports.catalogDifferences = catalogDifferences;