pgpm 5.14.0 → 5.15.1

package/commands/deploy.js

@@ -17,6 +17,10 @@ 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
@@ -36,6 +40,8 @@ Examples:
   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
@@ -117,11 +123,17 @@ exports.default = async (argv, prompter, _options) => {
         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) {

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,33 @@ 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 open a connection, so they must not activate a driver —
+ * a workspace-wide `engine` must not make plan/scaffolding commands depend on
+ * the driver plugin being installed. `init` additionally owns its own `--pglite`
+ * meaning (scaffold from the PGlite boilerplates), and runs before the plugin
+ * it scaffolds exists.
+ */
+const ENGINE_EXEMPT_COMMANDS = new Set([
+    'add',
+    'analyze',
+    'cache',
+    'doctor',
+    'env',
+    'extension',
+    'init',
+    'install',
+    'package',
+    'plan',
+    'remove',
+    'rename',
+    'slice',
+    'sync-versions',
+    'tag',
+    'up',
+    'update',
+    'upgrade'
+]);
 const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
     try {
         await fn(...args);
@@ -144,7 +171,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,6 +15,10 @@ 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
@@ -34,6 +38,8 @@ Examples:
   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
@@ -115,11 +121,17 @@ export default async (argv, prompter, _options) => {
         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) {

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,34 @@ 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 open a connection, so they must not activate a driver —
+ * a workspace-wide `engine` must not make plan/scaffolding commands depend on
+ * the driver plugin being installed. `init` additionally owns its own `--pglite`
+ * meaning (scaffold from the PGlite boilerplates), and runs before the plugin
+ * it scaffolds exists.
+ */
+const ENGINE_EXEMPT_COMMANDS = new Set([
+    'add',
+    'analyze',
+    'cache',
+    'doctor',
+    'env',
+    'extension',
+    'init',
+    'install',
+    'package',
+    'plan',
+    'remove',
+    'rename',
+    'slice',
+    'sync-versions',
+    'tag',
+    'up',
+    'update',
+    'upgrade'
+]);
 const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
     try {
         await fn(...args);
@@ -137,7 +164,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/driver.js

@@ -1,6 +1,6 @@
 import { PGPM_DRIVER_EXPORT, } from '@pgpmjs/types';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
+import { resolve } from 'node:path';
 /** Package name of the built-in PGlite driver plugin (the `--pglite` alias). */
 export const PGLITE_DRIVER_PLUGIN = '@pgpmjs/pglite-adapter';
 /**
@@ -56,8 +56,9 @@ export async function activateDriver(configured, override, cwd) {
     if (!cfg)
         return undefined;
     // A require bound to the consumer's project directory. `createRequire` is the
-    // one primitive available and identical in both CJS and ESM runtimes.
-    const requireFrom = createRequire(join(cwd, 'package.json'));
+    // one primitive available and identical in both CJS and ESM runtimes; it
+    // requires an absolute path, and `cwd` may come from a relative `--cwd`.
+    const requireFrom = createRequire(resolve(cwd, 'package.json'));
     let mod;
     try {
         const entry = requireFrom.resolve(cfg.plugin);

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,91 @@
+import { getEnvOptions } from '@pgpmjs/env';
+import { BUILTIN_ENGINES, DEFAULT_ENGINE, } from '@pgpmjs/types';
+import { resolve } from 'node:path';
+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 dir = resolve(cwd);
+    const config = getEnvOptions({}, dir);
+    const engine = resolveEngine(argv, config);
+    const session = await activateDriver(engine.driver, undefined, dir);
+    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.14.0",
+  "version": "5.15.1",
   "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.15.0",
-    "@pgpmjs/env": "^2.38.0",
-    "@pgpmjs/export": "^1.12.2",
+    "@pgpmjs/core": "^7.17.0",
+    "@pgpmjs/env": "^2.39.1",
+    "@pgpmjs/export": "^1.12.4",
     "@pgpmjs/logger": "^2.22.0",
-    "@pgpmjs/slice": "^0.10.1",
-    "@pgpmjs/types": "^2.46.0",
+    "@pgpmjs/slice": "^0.11.0",
+    "@pgpmjs/types": "^2.48.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.1",
+    "pg-cache": "^3.23.3",
     "pg-env": "^1.26.0",
     "pgsql-deparser": "^18.1.1",
     "semver": "^7.8.1",
@@ -77,5 +77,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "5ef8341033a8fbd85841b770e996e468dd15333b"
+  "gitHead": "2832d5632d11eb22e1437df773706ac6a99175fe"
 }

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/driver.js

@@ -62,8 +62,9 @@ async function activateDriver(configured, override, cwd) {
     if (!cfg)
         return undefined;
     // A require bound to the consumer's project directory. `createRequire` is the
-    // one primitive available and identical in both CJS and ESM runtimes.
-    const requireFrom = (0, node_module_1.createRequire)((0, node_path_1.join)(cwd, 'package.json'));
+    // one primitive available and identical in both CJS and ESM runtimes; it
+    // requires an absolute path, and `cwd` may come from a relative `--cwd`.
+    const requireFrom = (0, node_module_1.createRequire)((0, node_path_1.resolve)(cwd, 'package.json'));
     let mod;
     try {
         const entry = requireFrom.resolve(cfg.plugin);

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,99 @@
+"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 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 = {
+    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 dir = (0, node_path_1.resolve)(cwd);
+    const config = (0, env_1.getEnvOptions)({}, dir);
+    const engine = (0, exports.resolveEngine)(argv, config);
+    const session = await (0, driver_1.activateDriver)(engine.driver, undefined, dir);
+    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);