pgpm 5.13.0 → 5.15.0

package/commands/deploy.js

@@ -17,11 +17,18 @@ Deploy Command:
 Options:
   --help, -h         Show this help message
   --createdb         Create database if it doesn't exist
+  --engine <name>    Migration backend to deploy to (default: pg).
+                     Built-in engines: pg (Postgres server), pglite (in-process WASM).
+  --driver <pkg>     Driver plugin package to deploy through (escape hatch for --engine)
+  --pglite[=dataDir] Sugar for --engine pglite; persists to <dataDir> when given
   --recursive        Deploy recursively through dependencies
   --package <name>   Target specific package
   --to <target>      Deploy to specific change or tag
   --tx               Use transactions (default: true)
-  --fast             Use fast deployment strategy
+  --fast             Fast strategy: one-shot SQL + bulk migration ledger,
+                     reading each module's verified sql/*.bundle.tar.gz artifact
+                     when present and building it from deploy/ when not
+  --bundled          Alias for --fast
   --logOnly          Log-only mode, skip script execution
   --usePlan          Use deployment plan
   --cache            Enable caching
@@ -32,6 +39,9 @@ Examples:
   pgpm deploy --createdb                   Deploy with database creation
   pgpm deploy --package mypackage --to @v1.0.0  Deploy specific package to tag
   pgpm deploy --fast --no-tx              Fast deployment without transactions
+  pgpm deploy --bundled                    Same as --fast
+  pgpm deploy --engine pglite              Deploy into in-process PGlite (no server)
+  pgpm deploy --pglite=./.pglite           Deploy into a persisted PGlite data directory
 `;
 exports.default = async (argv, prompter, _options) => {
     // Show usage if explicitly requested
@@ -90,6 +100,14 @@ exports.default = async (argv, prompter, _options) => {
             default: false,
             required: false
         },
+        {
+            name: 'bundled',
+            type: 'confirm',
+            message: 'Prefer prebuilt bundle artifacts (alias of fast)?',
+            useDefault: true,
+            default: false,
+            required: false
+        },
         {
             name: 'logOnly',
             type: 'confirm',
@@ -99,17 +117,23 @@ exports.default = async (argv, prompter, _options) => {
             required: false
         }
     ];
-    let { yes, recursive, createdb, cwd, tx, fast, logOnly } = await prompter.prompt(argv, questions);
+    let { yes, recursive, createdb, cwd, tx, fast, bundled, logOnly } = await prompter.prompt(argv, questions);
     if (!yes) {
         log.info('Operation cancelled.');
         return;
     }
     log.debug(`Using current directory: ${cwd}`);
+    const { engine, capabilities } = (0, utils_1.getActiveEngine)();
     if (createdb) {
-        log.info(`Creating database ${database}...`);
-        (0, child_process_1.execSync)(`createdb ${database}`, {
-            env: (0, pg_env_1.getSpawnEnvWithPg)(pgEnv)
-        });
+        if (capabilities.createdb) {
+            log.info(`Creating database ${database}...`);
+            (0, child_process_1.execSync)(`createdb ${database}`, {
+                env: (0, pg_env_1.getSpawnEnvWithPg)(pgEnv)
+            });
+        }
+        else {
+            log.info(`Skipping createdb: the "${engine.name}" engine's instance is the database.`);
+        }
     }
     let packageName;
     if (recursive) {
@@ -120,6 +144,7 @@ exports.default = async (argv, prompter, _options) => {
         deployment: {
             useTx: tx !== false,
             fast: fast !== false,
+            bundled: bundled === true,
             usePlan: argv.usePlan !== false,
             cache: argv.cache !== false,
             logOnly: argv.logOnly !== false,

package/commands/package.js

@@ -14,12 +14,14 @@ Options:
   --pretty                        Pretty-print output (default: true)
   --functionDelimiter <delimiter> Function delimiter (default: $EOFCODE$)
   --outputDiff                    Export AST diff files when round-trip mismatch detected (default: false)
+  --bundle                        Also emit sql/<name>--<version>.bundle.tar.gz (default: true)
   --cwd <directory>               Working directory (default: current directory)
 
 Examples:
   pgpm package                     Package with defaults
   pgpm package --no-plan           Package without plan
   pgpm package --outputDiff        Package and export AST diff files if mismatch detected
+  pgpm package --no-bundle         Package without emitting the bundle artifact
 `;
 exports.default = async (argv, prompter, _options) => {
     // Show usage if explicitly requested
@@ -55,9 +57,16 @@ exports.default = async (argv, prompter, _options) => {
             default: false,
             useDefault: true,
             required: false
+        },
+        {
+            type: 'confirm',
+            name: 'bundle',
+            default: true,
+            useDefault: true,
+            required: false
         }
     ];
-    let { cwd, plan, pretty, functionDelimiter, outputDiff } = await prompter.prompt(argv, questions);
+    let { cwd, plan, pretty, functionDelimiter, outputDiff, bundle } = await prompter.prompt(argv, questions);
     const project = new core_1.PgpmPackage(cwd);
     project.ensureModule();
     const info = project.getModuleInfo();
@@ -69,7 +78,8 @@ exports.default = async (argv, prompter, _options) => {
         packageDir: project.modulePath,
         pretty,
         functionDelimiter,
-        outputDiff
+        outputDiff,
+        bundle: bundle !== false
     });
     return argv;
 };

package/commands/revert.js

@@ -22,6 +22,7 @@ Options:
   --to <target>      Revert to specific change or tag
   --to               Interactive selection of deployed changes
   --tx               Use transactions (default: true)
+  --engine <name>    Migration backend to revert in (default: pg; also pglite)
   --cwd <directory>  Working directory (default: current directory)
 
 Examples:

package/commands/verify.js

@@ -21,6 +21,7 @@ Options:
   --package <name>   Verify specific package
   --to <target>      Verify up to specific change or tag
   --to               Interactive selection of deployed changes
+  --engine <name>    Migration backend to verify against (default: pg; also pglite)
   --cwd <directory>  Working directory (default: current directory)
 
 Examples:

package/commands.js

@@ -37,6 +37,12 @@ const update_1 = __importDefault(require("./commands/update"));
 const upgrade_1 = __importDefault(require("./commands/upgrade"));
 const verify_1 = __importDefault(require("./commands/verify"));
 const utils_2 = require("./utils");
+/**
+ * Commands that never talk to a database and must not activate a driver.
+ * `init` owns its own `--pglite` meaning (scaffold from the PGlite boilerplates),
+ * and it runs before the plugin it would scaffold is even installed.
+ */
+const ENGINE_EXEMPT_COMMANDS = new Set(['init']);
 const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
     try {
         await fn(...args);
@@ -144,7 +150,27 @@ const commands = async (argv, prompter, options) => {
         console.log(utils_2.usageText);
         await (0, inquirerer_1.cliExitWithError)(`Unknown command: ${command}`, { beforeExit: pg_cache_1.teardownPgPools });
     }
-    await commandFn(newArgv, prompter, options);
+    // Activate the selected migration backend (`--engine`/`--driver`/`--pglite` or
+    // pgpm.json) before the command runs: the driver plugin registers its
+    // pool/client factories, so the unmodified engine targets it. The built-in
+    // `pg` engine activates nothing and behaves exactly as before.
+    const engineArgv = newArgv;
+    const { engine, capabilities } = ENGINE_EXEMPT_COMMANDS.has(command)
+        ? (0, utils_2.getActiveEngine)()
+        : await (0, utils_2.activateEngine)(engineArgv, engineArgv.cwd).catch(async (error) => {
+            await (0, inquirerer_1.cliExitWithError)(error.message, { beforeExit: pg_cache_1.teardownPgPools });
+            throw error;
+        });
+    try {
+        const blocked = (0, utils_2.engineCommandBlocker)(command, engine, capabilities);
+        if (blocked) {
+            await (0, inquirerer_1.cliExitWithError)(blocked, { beforeExit: pg_cache_1.teardownPgPools });
+        }
+        await commandFn(newArgv, prompter, options);
+    }
+    finally {
+        await (0, utils_2.deactivateEngine)();
+    }
     prompter.close();
     return argv;
 };

package/esm/commands/deploy.js

@@ -3,7 +3,7 @@ import { getEnvOptions } from '@pgpmjs/env';
 import { Logger } from '@pgpmjs/logger';
 import { execSync } from 'child_process';
 import { getPgEnvOptions, getSpawnEnvWithPg, } from 'pg-env';
-import { getTargetDatabase, resolvePackageAlias } from '../utils';
+import { getActiveEngine, getTargetDatabase, resolvePackageAlias } from '../utils';
 import { selectPackage } from '../utils/module-utils';
 const deployUsageText = `
 Deploy Command:
@@ -15,11 +15,18 @@ Deploy Command:
 Options:
   --help, -h         Show this help message
   --createdb         Create database if it doesn't exist
+  --engine <name>    Migration backend to deploy to (default: pg).
+                     Built-in engines: pg (Postgres server), pglite (in-process WASM).
+  --driver <pkg>     Driver plugin package to deploy through (escape hatch for --engine)
+  --pglite[=dataDir] Sugar for --engine pglite; persists to <dataDir> when given
   --recursive        Deploy recursively through dependencies
   --package <name>   Target specific package
   --to <target>      Deploy to specific change or tag
   --tx               Use transactions (default: true)
-  --fast             Use fast deployment strategy
+  --fast             Fast strategy: one-shot SQL + bulk migration ledger,
+                     reading each module's verified sql/*.bundle.tar.gz artifact
+                     when present and building it from deploy/ when not
+  --bundled          Alias for --fast
   --logOnly          Log-only mode, skip script execution
   --usePlan          Use deployment plan
   --cache            Enable caching
@@ -30,6 +37,9 @@ Examples:
   pgpm deploy --createdb                   Deploy with database creation
   pgpm deploy --package mypackage --to @v1.0.0  Deploy specific package to tag
   pgpm deploy --fast --no-tx              Fast deployment without transactions
+  pgpm deploy --bundled                    Same as --fast
+  pgpm deploy --engine pglite              Deploy into in-process PGlite (no server)
+  pgpm deploy --pglite=./.pglite           Deploy into a persisted PGlite data directory
 `;
 export default async (argv, prompter, _options) => {
     // Show usage if explicitly requested
@@ -88,6 +98,14 @@ export default async (argv, prompter, _options) => {
             default: false,
             required: false
         },
+        {
+            name: 'bundled',
+            type: 'confirm',
+            message: 'Prefer prebuilt bundle artifacts (alias of fast)?',
+            useDefault: true,
+            default: false,
+            required: false
+        },
         {
             name: 'logOnly',
             type: 'confirm',
@@ -97,17 +115,23 @@ export default async (argv, prompter, _options) => {
             required: false
         }
     ];
-    let { yes, recursive, createdb, cwd, tx, fast, logOnly } = await prompter.prompt(argv, questions);
+    let { yes, recursive, createdb, cwd, tx, fast, bundled, logOnly } = await prompter.prompt(argv, questions);
     if (!yes) {
         log.info('Operation cancelled.');
         return;
     }
     log.debug(`Using current directory: ${cwd}`);
+    const { engine, capabilities } = getActiveEngine();
     if (createdb) {
-        log.info(`Creating database ${database}...`);
-        execSync(`createdb ${database}`, {
-            env: getSpawnEnvWithPg(pgEnv)
-        });
+        if (capabilities.createdb) {
+            log.info(`Creating database ${database}...`);
+            execSync(`createdb ${database}`, {
+                env: getSpawnEnvWithPg(pgEnv)
+            });
+        }
+        else {
+            log.info(`Skipping createdb: the "${engine.name}" engine's instance is the database.`);
+        }
     }
     let packageName;
     if (recursive) {
@@ -118,6 +142,7 @@ export default async (argv, prompter, _options) => {
         deployment: {
             useTx: tx !== false,
             fast: fast !== false,
+            bundled: bundled === true,
             usePlan: argv.usePlan !== false,
             cache: argv.cache !== false,
             logOnly: argv.logOnly !== false,

package/esm/commands/package.js

@@ -12,12 +12,14 @@ Options:
   --pretty                        Pretty-print output (default: true)
   --functionDelimiter <delimiter> Function delimiter (default: $EOFCODE$)
   --outputDiff                    Export AST diff files when round-trip mismatch detected (default: false)
+  --bundle                        Also emit sql/<name>--<version>.bundle.tar.gz (default: true)
   --cwd <directory>               Working directory (default: current directory)
 
 Examples:
   pgpm package                     Package with defaults
   pgpm package --no-plan           Package without plan
   pgpm package --outputDiff        Package and export AST diff files if mismatch detected
+  pgpm package --no-bundle         Package without emitting the bundle artifact
 `;
 export default async (argv, prompter, _options) => {
     // Show usage if explicitly requested
@@ -53,9 +55,16 @@ export default async (argv, prompter, _options) => {
             default: false,
             useDefault: true,
             required: false
+        },
+        {
+            type: 'confirm',
+            name: 'bundle',
+            default: true,
+            useDefault: true,
+            required: false
         }
     ];
-    let { cwd, plan, pretty, functionDelimiter, outputDiff } = await prompter.prompt(argv, questions);
+    let { cwd, plan, pretty, functionDelimiter, outputDiff, bundle } = await prompter.prompt(argv, questions);
     const project = new PgpmPackage(cwd);
     project.ensureModule();
     const info = project.getModuleInfo();
@@ -67,7 +76,8 @@ export default async (argv, prompter, _options) => {
         packageDir: project.modulePath,
         pretty,
         functionDelimiter,
-        outputDiff
+        outputDiff,
+        bundle: bundle !== false
     });
     return argv;
 };

package/esm/commands/revert.js

@@ -20,6 +20,7 @@ Options:
   --to <target>      Revert to specific change or tag
   --to               Interactive selection of deployed changes
   --tx               Use transactions (default: true)
+  --engine <name>    Migration backend to revert in (default: pg; also pglite)
   --cwd <directory>  Working directory (default: current directory)
 
 Examples:

package/esm/commands/verify.js

@@ -19,6 +19,7 @@ Options:
   --package <name>   Verify specific package
   --to <target>      Verify up to specific change or tag
   --to               Interactive selection of deployed changes
+  --engine <name>    Migration backend to verify against (default: pg; also pglite)
   --cwd <directory>  Working directory (default: current directory)
 
 Examples:

package/esm/commands.js

@@ -30,7 +30,13 @@ import tune from './commands/tune';
 import updateCmd from './commands/update';
 import upgrade from './commands/upgrade';
 import verify from './commands/verify';
-import { usageText } from './utils';
+import { activateEngine, deactivateEngine, engineCommandBlocker, getActiveEngine, usageText } from './utils';
+/**
+ * Commands that never talk to a database and must not activate a driver.
+ * `init` owns its own `--pglite` meaning (scaffold from the PGlite boilerplates),
+ * and it runs before the plugin it would scaffold is even installed.
+ */
+const ENGINE_EXEMPT_COMMANDS = new Set(['init']);
 const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
     try {
         await fn(...args);
@@ -137,7 +143,27 @@ export const commands = async (argv, prompter, options) => {
         console.log(usageText);
         await cliExitWithError(`Unknown command: ${command}`, { beforeExit: teardownPgPools });
     }
-    await commandFn(newArgv, prompter, options);
+    // Activate the selected migration backend (`--engine`/`--driver`/`--pglite` or
+    // pgpm.json) before the command runs: the driver plugin registers its
+    // pool/client factories, so the unmodified engine targets it. The built-in
+    // `pg` engine activates nothing and behaves exactly as before.
+    const engineArgv = newArgv;
+    const { engine, capabilities } = ENGINE_EXEMPT_COMMANDS.has(command)
+        ? getActiveEngine()
+        : await activateEngine(engineArgv, engineArgv.cwd).catch(async (error) => {
+            await cliExitWithError(error.message, { beforeExit: teardownPgPools });
+            throw error;
+        });
+    try {
+        const blocked = engineCommandBlocker(command, engine, capabilities);
+        if (blocked) {
+            await cliExitWithError(blocked, { beforeExit: teardownPgPools });
+        }
+        await commandFn(newArgv, prompter, options);
+    }
+    finally {
+        await deactivateEngine();
+    }
     prompter.close();
     return argv;
 };

package/esm/utils/display.js

@@ -50,6 +50,11 @@ export const usageText = `
     -h, --help         Display this help information
     -v, --version      Display version information
     --cwd <directory>  Working directory (default: current directory)
+    --engine <name>    Migration backend: pg (default, Postgres server) or
+                       pglite (in-process WASM Postgres, no server). Also set by
+                       the "engine" key of pgpm.json or PGPM_ENGINE.
+    --driver <pkg>     Driver plugin package backing the engine (escape hatch)
+    --pglite[=dataDir] Sugar for --engine pglite, persisted to <dataDir> if given
 
   Individual Command Help:
     pgpm <command> --help    Display detailed help for specific command

package/esm/utils/engine-gating.js

@@ -0,0 +1,28 @@
+/**
+ * Commands that need a capability the backend may not have. Gating is declared
+ * here rather than branching per backend inside each command, so a new driver
+ * plugin only has to describe itself through {@link PgpmDriverCapabilities}.
+ */
+const COMMAND_REQUIREMENTS = {
+    docker: 'serverLifecycle',
+    kill: 'serverLifecycle',
+    tune: 'serverLifecycle',
+    'admin-users': 'multiConnection',
+    dump: 'dump',
+};
+const REQUIREMENT_REASONS = {
+    createdb: 'it cannot create databases (the instance is the database)',
+    dump: 'it has no pg_dump',
+    serverLifecycle: 'it has no server to manage',
+    multiConnection: 'it is a single-session backend',
+};
+/**
+ * The reason a command cannot run on the active engine, or undefined when it can.
+ */
+export const engineCommandBlocker = (command, engine, capabilities) => {
+    const requirement = COMMAND_REQUIREMENTS[command];
+    if (!requirement || capabilities[requirement])
+        return undefined;
+    return (`pgpm ${command} is not supported by the "${engine.name}" engine — ` +
+        `${REQUIREMENT_REASONS[requirement]}.`);
+};

package/esm/utils/engine.js

@@ -0,0 +1,89 @@
+import { getEnvOptions } from '@pgpmjs/env';
+import { BUILTIN_ENGINES, DEFAULT_ENGINE, } from '@pgpmjs/types';
+import { activateDriver, driverOverrideFromArgv, PGLITE_DRIVER_PLUGIN } from './driver';
+/** Everything a real Postgres server can do — the built-in `pg` engine. */
+export const SERVER_CAPABILITIES = {
+    createdb: true,
+    dump: true,
+    serverLifecycle: true,
+    multiConnection: true,
+};
+/**
+ * The engines available by name: the built-ins, overridden/extended by the
+ * `engines` block of `pgpm.json` (sqitch's `[engine "name"]` sections).
+ *
+ * A configured entry is merged over its built-in, so declaring only options
+ * (e.g. `engines.pglite.options.dataDir`) keeps the built-in plugin.
+ */
+export const engineDefinitions = (config) => {
+    const definitions = { ...BUILTIN_ENGINES };
+    for (const [name, configured] of Object.entries(config.engines ?? {})) {
+        definitions[name] = { ...definitions[name], ...configured };
+    }
+    return definitions;
+};
+const definitionToDriver = (definition, options) => definition.plugin
+    ? { plugin: definition.plugin, options: { ...definition.options, ...options } }
+    : undefined;
+const lookupEngine = (name, config, options) => {
+    const definition = engineDefinitions(config)[name];
+    if (!definition) {
+        const known = Object.keys(engineDefinitions(config)).sort().join(', ');
+        throw new Error(`Unknown pgpm engine "${name}". Known engines: ${known}.\n` +
+            'Declare it in the "engines" block of pgpm.json, or name its plugin with --driver <package>.');
+    }
+    return { name, driver: definitionToDriver(definition, options) };
+};
+/**
+ * Resolve which engine a command targets, mirroring sqitch's `core.engine` model:
+ * a short engine name selects the backend, and the built-in default is `pg`.
+ *
+ * Precedence (first match wins):
+ * 1. `--driver <package>` — name a driver plugin directly (escape hatch)
+ * 2. `--pglite[=dataDir]` — sugar for `--engine pglite`
+ * 3. `--engine <name>`
+ * 4. the `driver` block of `pgpm.json` — plugin-level configuration
+ * 5. the `engine` key of `pgpm.json` / `PGPM_ENGINE`
+ * 6. `pg`, the built-in server path
+ */
+export const resolveEngine = (argv, config) => {
+    const override = driverOverrideFromArgv(argv);
+    if (override) {
+        if (override.plugin === PGLITE_DRIVER_PLUGIN && !argv.driver) {
+            // `--pglite` is the pglite engine, so it inherits that engine's configured
+            // options (e.g. a dataDir declared in pgpm.json) instead of bypassing them.
+            return lookupEngine('pglite', config, override.options);
+        }
+        return { name: override.plugin, driver: override };
+    }
+    if (argv.engine)
+        return lookupEngine(argv.engine, config);
+    if (config.driver)
+        return { name: config.driver.plugin, driver: config.driver };
+    return lookupEngine(config.engine ?? DEFAULT_ENGINE, config);
+};
+let active;
+/**
+ * The engine activated for the running command. Commands read this to skip
+ * server-only steps (e.g. `deploy --createdb`) instead of hard-coding backends.
+ * Defaults to the built-in server path when nothing has been activated.
+ */
+export const getActiveEngine = () => active ?? { engine: { name: DEFAULT_ENGINE }, capabilities: SERVER_CAPABILITIES };
+/**
+ * Resolve the engine from argv + `pgpm.json` and activate its driver plugin.
+ * The driver has registered its pool/client factories by the time this resolves,
+ * so the unmodified pgpm engine runs against the selected backend.
+ */
+export const activateEngine = async (argv, cwd = process.cwd()) => {
+    const config = getEnvOptions({}, cwd);
+    const engine = resolveEngine(argv, config);
+    const session = await activateDriver(engine.driver, undefined, cwd);
+    active = { engine, session, capabilities: session?.capabilities ?? SERVER_CAPABILITIES };
+    return active;
+};
+/** Tear down the active driver session and restore the built-in server path. */
+export const deactivateEngine = async () => {
+    const session = active?.session;
+    active = undefined;
+    await session?.teardown();
+};

package/esm/utils/index.js

@@ -3,6 +3,8 @@ export * from './deployed-changes';
 export * from './display';
 export * from './doctor';
 export * from './driver';
+export * from './engine';
+export * from './engine-gating';
 export * from './module-utils';
 export * from './npm-version';
 export * from './package-alias';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgpm",
-  "version": "5.13.0",
+  "version": "5.15.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL Package Manager - Database migration and package management CLI",
   "main": "index.js",
@@ -46,19 +46,19 @@
   },
   "dependencies": {
     "@inquirerer/utils": "^3.3.9",
-    "@pgpmjs/core": "^7.14.0",
-    "@pgpmjs/env": "^2.37.0",
-    "@pgpmjs/export": "^1.12.1",
+    "@pgpmjs/core": "^7.16.0",
+    "@pgpmjs/env": "^2.39.0",
+    "@pgpmjs/export": "^1.12.3",
     "@pgpmjs/logger": "^2.22.0",
-    "@pgpmjs/slice": "^0.10.0",
-    "@pgpmjs/types": "^2.45.0",
+    "@pgpmjs/slice": "^0.10.2",
+    "@pgpmjs/types": "^2.47.0",
     "@pgsql/quotes": "^18.1.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.23.0",
+    "pg-cache": "^3.23.2",
     "pg-env": "^1.26.0",
     "pgsql-deparser": "^18.1.1",
     "semver": "^7.8.1",
@@ -77,5 +77,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "d85911699e8a50a9fdfeb7506195442525c1f238"
+  "gitHead": "0286d994d98717cb9b28842233d2db6d1e37c48e"
 }

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    package            Package module for distribution\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\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    package            Package module for distribution\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

@@ -53,6 +53,11 @@ exports.usageText = `
     -h, --help         Display this help information
     -v, --version      Display version information
     --cwd <directory>  Working directory (default: current directory)
+    --engine <name>    Migration backend: pg (default, Postgres server) or
+                       pglite (in-process WASM Postgres, no server). Also set by
+                       the "engine" key of pgpm.json or PGPM_ENGINE.
+    --driver <pkg>     Driver plugin package backing the engine (escape hatch)
+    --pglite[=dataDir] Sugar for --engine pglite, persisted to <dataDir> if given
 
   Individual Command Help:
     pgpm <command> --help    Display detailed help for specific command

package/utils/engine-gating.d.ts

@@ -0,0 +1,6 @@
+import { PgpmDriverCapabilities } from '@pgpmjs/types';
+import { ResolvedEngine } from './engine';
+/**
+ * The reason a command cannot run on the active engine, or undefined when it can.
+ */
+export declare const engineCommandBlocker: (command: string, engine: ResolvedEngine, capabilities: PgpmDriverCapabilities) => string | undefined;

package/utils/engine-gating.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.engineCommandBlocker = void 0;
+/**
+ * Commands that need a capability the backend may not have. Gating is declared
+ * here rather than branching per backend inside each command, so a new driver
+ * plugin only has to describe itself through {@link PgpmDriverCapabilities}.
+ */
+const COMMAND_REQUIREMENTS = {
+    docker: 'serverLifecycle',
+    kill: 'serverLifecycle',
+    tune: 'serverLifecycle',
+    'admin-users': 'multiConnection',
+    dump: 'dump',
+};
+const REQUIREMENT_REASONS = {
+    createdb: 'it cannot create databases (the instance is the database)',
+    dump: 'it has no pg_dump',
+    serverLifecycle: 'it has no server to manage',
+    multiConnection: 'it is a single-session backend',
+};
+/**
+ * The reason a command cannot run on the active engine, or undefined when it can.
+ */
+const engineCommandBlocker = (command, engine, capabilities) => {
+    const requirement = COMMAND_REQUIREMENTS[command];
+    if (!requirement || capabilities[requirement])
+        return undefined;
+    return (`pgpm ${command} is not supported by the "${engine.name}" engine — ` +
+        `${REQUIREMENT_REASONS[requirement]}.`);
+};
+exports.engineCommandBlocker = engineCommandBlocker;

package/utils/engine.d.ts

@@ -0,0 +1,57 @@
+import { PgpmDriverCapabilities, PgpmDriverConfig, PgpmDriverSession, PgpmEngineConfig, PgpmOptions } from '@pgpmjs/types';
+/** Everything a real Postgres server can do — the built-in `pg` engine. */
+export declare const SERVER_CAPABILITIES: PgpmDriverCapabilities;
+/** The engine/driver selectors every command accepts. */
+export interface EngineArgv {
+    engine?: string;
+    driver?: string;
+    pglite?: boolean | string;
+}
+/** The engine a command runs against, plus the driver plugin backing it. */
+export interface ResolvedEngine {
+    /** Engine name, for messages: a registered name or a plugin package. */
+    name: string;
+    /** Driver plugin to activate; undefined = built-in `pg` (server) path. */
+    driver?: PgpmDriverConfig;
+}
+/**
+ * The engines available by name: the built-ins, overridden/extended by the
+ * `engines` block of `pgpm.json` (sqitch's `[engine "name"]` sections).
+ *
+ * A configured entry is merged over its built-in, so declaring only options
+ * (e.g. `engines.pglite.options.dataDir`) keeps the built-in plugin.
+ */
+export declare const engineDefinitions: (config: PgpmOptions) => Record<string, PgpmEngineConfig>;
+/**
+ * Resolve which engine a command targets, mirroring sqitch's `core.engine` model:
+ * a short engine name selects the backend, and the built-in default is `pg`.
+ *
+ * Precedence (first match wins):
+ * 1. `--driver <package>` — name a driver plugin directly (escape hatch)
+ * 2. `--pglite[=dataDir]` — sugar for `--engine pglite`
+ * 3. `--engine <name>`
+ * 4. the `driver` block of `pgpm.json` — plugin-level configuration
+ * 5. the `engine` key of `pgpm.json` / `PGPM_ENGINE`
+ * 6. `pg`, the built-in server path
+ */
+export declare const resolveEngine: (argv: EngineArgv, config: PgpmOptions) => ResolvedEngine;
+/** The engine activated for the running command. */
+export interface ActiveEngine {
+    engine: ResolvedEngine;
+    session?: PgpmDriverSession;
+    capabilities: PgpmDriverCapabilities;
+}
+/**
+ * The engine activated for the running command. Commands read this to skip
+ * server-only steps (e.g. `deploy --createdb`) instead of hard-coding backends.
+ * Defaults to the built-in server path when nothing has been activated.
+ */
+export declare const getActiveEngine: () => ActiveEngine;
+/**
+ * Resolve the engine from argv + `pgpm.json` and activate its driver plugin.
+ * The driver has registered its pool/client factories by the time this resolves,
+ * so the unmodified pgpm engine runs against the selected backend.
+ */
+export declare const activateEngine: (argv: EngineArgv, cwd?: string) => Promise<ActiveEngine>;
+/** Tear down the active driver session and restore the built-in server path. */
+export declare const deactivateEngine: () => Promise<void>;

package/utils/engine.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deactivateEngine = exports.activateEngine = exports.getActiveEngine = exports.resolveEngine = exports.engineDefinitions = exports.SERVER_CAPABILITIES = void 0;
+const env_1 = require("@pgpmjs/env");
+const types_1 = require("@pgpmjs/types");
+const driver_1 = require("./driver");
+/** Everything a real Postgres server can do — the built-in `pg` engine. */
+exports.SERVER_CAPABILITIES = {
+    createdb: true,
+    dump: true,
+    serverLifecycle: true,
+    multiConnection: true,
+};
+/**
+ * The engines available by name: the built-ins, overridden/extended by the
+ * `engines` block of `pgpm.json` (sqitch's `[engine "name"]` sections).
+ *
+ * A configured entry is merged over its built-in, so declaring only options
+ * (e.g. `engines.pglite.options.dataDir`) keeps the built-in plugin.
+ */
+const engineDefinitions = (config) => {
+    const definitions = { ...types_1.BUILTIN_ENGINES };
+    for (const [name, configured] of Object.entries(config.engines ?? {})) {
+        definitions[name] = { ...definitions[name], ...configured };
+    }
+    return definitions;
+};
+exports.engineDefinitions = engineDefinitions;
+const definitionToDriver = (definition, options) => definition.plugin
+    ? { plugin: definition.plugin, options: { ...definition.options, ...options } }
+    : undefined;
+const lookupEngine = (name, config, options) => {
+    const definition = (0, exports.engineDefinitions)(config)[name];
+    if (!definition) {
+        const known = Object.keys((0, exports.engineDefinitions)(config)).sort().join(', ');
+        throw new Error(`Unknown pgpm engine "${name}". Known engines: ${known}.\n` +
+            'Declare it in the "engines" block of pgpm.json, or name its plugin with --driver <package>.');
+    }
+    return { name, driver: definitionToDriver(definition, options) };
+};
+/**
+ * Resolve which engine a command targets, mirroring sqitch's `core.engine` model:
+ * a short engine name selects the backend, and the built-in default is `pg`.
+ *
+ * Precedence (first match wins):
+ * 1. `--driver <package>` — name a driver plugin directly (escape hatch)
+ * 2. `--pglite[=dataDir]` — sugar for `--engine pglite`
+ * 3. `--engine <name>`
+ * 4. the `driver` block of `pgpm.json` — plugin-level configuration
+ * 5. the `engine` key of `pgpm.json` / `PGPM_ENGINE`
+ * 6. `pg`, the built-in server path
+ */
+const resolveEngine = (argv, config) => {
+    const override = (0, driver_1.driverOverrideFromArgv)(argv);
+    if (override) {
+        if (override.plugin === driver_1.PGLITE_DRIVER_PLUGIN && !argv.driver) {
+            // `--pglite` is the pglite engine, so it inherits that engine's configured
+            // options (e.g. a dataDir declared in pgpm.json) instead of bypassing them.
+            return lookupEngine('pglite', config, override.options);
+        }
+        return { name: override.plugin, driver: override };
+    }
+    if (argv.engine)
+        return lookupEngine(argv.engine, config);
+    if (config.driver)
+        return { name: config.driver.plugin, driver: config.driver };
+    return lookupEngine(config.engine ?? types_1.DEFAULT_ENGINE, config);
+};
+exports.resolveEngine = resolveEngine;
+let active;
+/**
+ * The engine activated for the running command. Commands read this to skip
+ * server-only steps (e.g. `deploy --createdb`) instead of hard-coding backends.
+ * Defaults to the built-in server path when nothing has been activated.
+ */
+const getActiveEngine = () => active ?? { engine: { name: types_1.DEFAULT_ENGINE }, capabilities: exports.SERVER_CAPABILITIES };
+exports.getActiveEngine = getActiveEngine;
+/**
+ * Resolve the engine from argv + `pgpm.json` and activate its driver plugin.
+ * The driver has registered its pool/client factories by the time this resolves,
+ * so the unmodified pgpm engine runs against the selected backend.
+ */
+const activateEngine = async (argv, cwd = process.cwd()) => {
+    const config = (0, env_1.getEnvOptions)({}, cwd);
+    const engine = (0, exports.resolveEngine)(argv, config);
+    const session = await (0, driver_1.activateDriver)(engine.driver, undefined, cwd);
+    active = { engine, session, capabilities: session?.capabilities ?? exports.SERVER_CAPABILITIES };
+    return active;
+};
+exports.activateEngine = activateEngine;
+/** Tear down the active driver session and restore the built-in server path. */
+const deactivateEngine = async () => {
+    const session = active?.session;
+    active = undefined;
+    await session?.teardown();
+};
+exports.deactivateEngine = deactivateEngine;

package/utils/index.d.ts

@@ -3,6 +3,8 @@ export * from './deployed-changes';
 export * from './display';
 export * from './doctor';
 export * from './driver';
+export * from './engine';
+export * from './engine-gating';
 export * from './module-utils';
 export * from './npm-version';
 export * from './package-alias';

package/utils/index.js

@@ -19,6 +19,8 @@ __exportStar(require("./deployed-changes"), exports);
 __exportStar(require("./display"), exports);
 __exportStar(require("./doctor"), exports);
 __exportStar(require("./driver"), exports);
+__exportStar(require("./engine"), exports);
+__exportStar(require("./engine-gating"), exports);
 __exportStar(require("./module-utils"), exports);
 __exportStar(require("./npm-version"), exports);
 __exportStar(require("./package-alias"), exports);