pgpm 5.19.1 → 5.21.0

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,36 @@
+/** 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>;
+/** Resolved `--emit-sql` / `--emit-bundle` projection targets for a command. */
+export interface EmitProjectionTargets {
+    /** Linear SQL target (absolute path, or `-` for stdout). */
+    emitSql?: string;
+    /** Bundle archive target (absolute path). */
+    emitBundle?: string;
+}
+/**
+ * Parse the shared `--emit-sql` / `--emit-bundle` projection flags off a parsed
+ * argv, resolving file targets against `cwd` (the `-` stdout sentinel for SQL is
+ * preserved). Keeps every command's projection flags identical.
+ */
+export declare const parseEmitProjectionTargets: (argv: Record<string, unknown>, cwd: string) => EmitProjectionTargets;
+/** Whether any projection target was requested. */
+export declare const hasEmitProjection: (targets: EmitProjectionTargets) => boolean;
+/**
+ * Run the requested SQL/bundle projections against a written module directory.
+ * `onSuccess` (when provided) is invoked with a human-readable line per emitted
+ * artifact; it is skipped for stdout SQL so the stream stays valid SQL.
+ */
+export declare const projectModule: (moduleDir: string, targets: EmitProjectionTargets, onSuccess?: (message: string) => void) => Promise<void>;

package/utils/module-projections.js

@@ -0,0 +1,123 @@
+"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.projectModule = exports.hasEmitProjection = exports.parseEmitProjectionTargets = 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;
+/**
+ * Parse the shared `--emit-sql` / `--emit-bundle` projection flags off a parsed
+ * argv, resolving file targets against `cwd` (the `-` stdout sentinel for SQL is
+ * preserved). Keeps every command's projection flags identical.
+ */
+const parseEmitProjectionTargets = (argv, cwd) => {
+    const sqlRaw = argv['emit-sql'] ?? argv.emitSql;
+    const emitSql = typeof sqlRaw === 'string' && sqlRaw
+        ? sqlRaw === exports.STDOUT_TARGET
+            ? exports.STDOUT_TARGET
+            : path.resolve(cwd, sqlRaw)
+        : undefined;
+    const bundleRaw = argv['emit-bundle'] ?? argv.emitBundle;
+    const emitBundle = typeof bundleRaw === 'string' && bundleRaw ? path.resolve(cwd, bundleRaw) : undefined;
+    return { emitSql, emitBundle };
+};
+exports.parseEmitProjectionTargets = parseEmitProjectionTargets;
+/** Whether any projection target was requested. */
+const hasEmitProjection = (targets) => Boolean(targets.emitSql || targets.emitBundle);
+exports.hasEmitProjection = hasEmitProjection;
+/**
+ * Run the requested SQL/bundle projections against a written module directory.
+ * `onSuccess` (when provided) is invoked with a human-readable line per emitted
+ * artifact; it is skipped for stdout SQL so the stream stays valid SQL.
+ */
+const projectModule = async (moduleDir, targets, onSuccess) => {
+    if (targets.emitSql) {
+        await (0, exports.emitModuleSql)(moduleDir, targets.emitSql);
+        if (targets.emitSql !== exports.STDOUT_TARGET) {
+            onSuccess?.(`wrote linear SQL to ${targets.emitSql}`);
+        }
+    }
+    if (targets.emitBundle) {
+        await (0, exports.emitModuleBundle)(moduleDir, targets.emitBundle);
+        onSuccess?.(`wrote bundle to ${targets.emitBundle}`);
+    }
+};
+exports.projectModule = projectModule;

package/utils/scratch-db.d.ts

@@ -0,0 +1,16 @@
+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 logger_1 = require("@pgpmjs/logger");
+const transform_1 = require("@pgpmjs/transform");
+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;