pgpm 2.9.1 → 2.10.1

package/README.md

@@ -328,6 +328,28 @@ pgpm package --no-plan
 
 ### Utilities
 
+#### `pgpm dump`
+
+Dump a postgres database to a sql file.
+
+```bash
+# dump to default timestamped file
+pgpm dump --database mydb
+
+# interactive mode (prompts for database)
+pgpm dump
+
+# dump to specific file
+pgpm dump --database mydb --out ./backup.sql
+
+# dump from a specific working directory
+pgpm dump --database mydb --cwd ./packages/my-module
+
+# dump with pruning 
+# useful for creating test fixtures or development snapshots
+pgpm dump --database mydb --database-id <uuid>
+```
+
 #### `pgpm export`
 
 Export migrations from existing databases.

package/commands/dump.d.ts

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

package/commands/dump.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = require("@pgpmjs/logger");
+const pg_env_1 = require("pg-env");
+const pg_cache_1 = require("pg-cache");
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const quote_utils_1 = require("pgsql-deparser/utils/quote-utils");
+const utils_1 = require("../utils");
+const log = new logger_1.Logger('dump');
+const dumpUsageText = `
+Dump Command:
+
+  pgpm dump [options]
+
+  Dump a postgres database to a sql file.
+
+Options:
+  --help, -h                 Show this help message
+  --db, --database <name>    Target postgres database name
+  --out <path>               Output file path
+  --database-id <id>         When set, the dump will include a prune step that keeps only this database_id after restore
+  --cwd <directory>          Working directory (default: current directory)
+
+Examples:
+  pgpm dump
+  pgpm dump --database mydb
+  pgpm dump --database mydb --out ./mydb.sql
+  pgpm dump --database mydb --database-id 00000000-0000-0000-0000-000000000000
+`;
+function nowStamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+async function runPgDump(args, env) {
+    await new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('pg_dump', args, {
+            env,
+            stdio: 'inherit',
+            shell: false
+        });
+        child.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                log.error('pg_dump not found; ensure PostgreSQL client tools are installed and in PATH');
+            }
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`pg_dump exited with code ${code ?? 1}`));
+        });
+    });
+}
+async function resolveDatabaseId(dbname, databaseIdRaw) {
+    const pool = (0, pg_cache_1.getPgPool)((0, pg_env_1.getPgEnvOptions)({ database: dbname }));
+    const res = await pool.query(`select id, name from metaschema_public.database order by name`);
+    const byId = res.rows.find((r) => String(r.id) === databaseIdRaw);
+    if (byId)
+        return { id: String(byId.id), name: String(byId.name) };
+    const byName = res.rows.find((r) => String(r.name) === databaseIdRaw);
+    if (byName)
+        return { id: String(byName.id), name: String(byName.name) };
+    return null;
+}
+async function buildPruneSql(dbname, databaseId) {
+    const pool = (0, pg_cache_1.getPgPool)((0, pg_env_1.getPgEnvOptions)({ database: dbname }));
+    const tables = await pool.query(`
+    select c.table_schema, c.table_name
+    from information_schema.columns c
+    join information_schema.tables t
+      on t.table_schema = c.table_schema
+      and t.table_name = c.table_name
+    where c.column_name = 'database_id'
+      and t.table_type = 'BASE TABLE'
+      and c.table_schema not in ('pg_catalog', 'information_schema')
+    order by c.table_schema, c.table_name
+  `);
+    const lines = [];
+    lines.push('');
+    lines.push('-- pgpm dump prune');
+    lines.push('-- this section keeps only one database_id after restore');
+    lines.push('do $$ begin');
+    lines.push(`  raise notice 'pruning data to database_id ${databaseId}';`);
+    lines.push('end $$;');
+    lines.push('set session_replication_role = replica;');
+    for (const row of tables.rows) {
+        const schema = String(row.table_schema);
+        const table = String(row.table_name);
+        // Use QuoteUtils for robust identifier quoting
+        const qualified = quote_utils_1.QuoteUtils.quoteQualifiedIdentifier(schema, table);
+        // Use formatEString to safely escape the UUID/string literal
+        const dbIdLiteral = quote_utils_1.QuoteUtils.formatEString(databaseId);
+        lines.push(`delete from ${qualified} where database_id <> ${dbIdLiteral};`);
+    }
+    // Handle metaschema_public.database deletion
+    const metaschemaDb = quote_utils_1.QuoteUtils.quoteQualifiedIdentifier('metaschema_public', 'database');
+    const dbIdLiteral = quote_utils_1.QuoteUtils.formatEString(databaseId);
+    lines.push(`delete from ${metaschemaDb} where id <> ${dbIdLiteral};`);
+    lines.push('set session_replication_role = origin;');
+    lines.push('do $$ begin');
+    lines.push(`  raise notice 'prune done';`);
+    lines.push('end $$;');
+    lines.push('');
+    return lines.join('\n');
+}
+// Helper to retrieve argument from parsed argv or positional _ array
+function getArg(argv, key) {
+    if (argv[key])
+        return argv[key];
+    const args = argv._ || [];
+    const idx = args.indexOf(`--${key}`);
+    if (idx > -1 && args.length > idx + 1) {
+        return args[idx + 1];
+    }
+    return undefined;
+}
+exports.default = async (argv, prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(dumpUsageText);
+        process.exit(0);
+    }
+    const cwd = argv.cwd || process.cwd();
+    const dbname = await (0, utils_1.getTargetDatabase)(argv, prompter, { message: 'Select database' });
+    const outPath = path_1.default.resolve(cwd, argv.out || `pgpm-dump-${dbname}-${nowStamp()}.sql`);
+    fs_1.default.mkdirSync(path_1.default.dirname(outPath), { recursive: true });
+    let databaseIdInfo = null;
+    const databaseIdRaw = getArg(argv, 'database-id');
+    if (databaseIdRaw) {
+        databaseIdInfo = await resolveDatabaseId(dbname, databaseIdRaw);
+        if (!databaseIdInfo) {
+            throw new Error(`unknown database-id ${databaseIdRaw}`);
+        }
+    }
+    log.info(`dumping database ${dbname}`);
+    log.info(`writing to ${outPath}`);
+    if (databaseIdInfo) {
+        log.info(`database id ${databaseIdInfo.id}`);
+    }
+    const pgEnv = (0, pg_env_1.getPgEnvOptions)({ database: dbname });
+    const spawnEnv = (0, pg_env_1.getSpawnEnvWithPg)(pgEnv);
+    const args = [
+        '--format=plain',
+        '--no-owner',
+        '--no-privileges',
+        '--file',
+        outPath,
+        dbname
+    ];
+    await runPgDump(args, spawnEnv);
+    if (databaseIdInfo) {
+        const pruneSql = await buildPruneSql(dbname, databaseIdInfo.id);
+        // Use writeFileSync with 'a' flag for explicit append as requested
+        fs_1.default.writeFileSync(outPath, pruneSql, { encoding: 'utf8', flag: 'a' });
+        log.info('added prune section to dump file');
+    }
+    log.success('dump complete');
+    return argv;
+};

package/commands/init/index.js

@@ -7,6 +7,7 @@ exports.createInitUsageText = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const core_1 = require("@pgpmjs/core");
+const env_1 = require("@pgpmjs/env");
 const types_1 = require("@pgpmjs/types");
 const inquirerer_1 = require("inquirerer");
 const DEFAULT_MOTD = `
@@ -97,7 +98,7 @@ async function handleInit(argv, prompter) {
             cwd,
         });
     }
-    // Default to module init (for 'module' type or unknown types)
+    // Default to module init (for 'module' type, 'generic' type, or unknown types)
     return handleModuleInit(argv, prompter, {
         fromPath,
         templateRepo,
@@ -105,6 +106,7 @@ async function handleInit(argv, prompter) {
         dir,
         noTty,
         cwd,
+        requiresWorkspace: inspection.config?.requiresWorkspace,
     }, wasExplicitModuleRequest);
 }
 async function handleBoilerplateInit(argv, prompter, ctx) {
@@ -172,7 +174,7 @@ async function handleBoilerplateInit(argv, prompter, ctx) {
             cwd: ctx.cwd,
         });
     }
-    // Default to module init (for 'module' type or unknown types)
+    // Default to module init (for 'module' type, 'generic' type, or unknown types)
     // When using --boilerplate, user made an explicit choice, so treat as explicit request
     return handleModuleInit(argv, prompter, {
         fromPath,
@@ -181,6 +183,7 @@ async function handleBoilerplateInit(argv, prompter, ctx) {
         dir: ctx.dir,
         noTty: ctx.noTty,
         cwd: ctx.cwd,
+        requiresWorkspace: inspection.config?.requiresWorkspace,
     }, true);
 }
 async function handleWorkspaceInit(argv, prompter, ctx) {
@@ -233,49 +236,67 @@ async function handleWorkspaceInit(argv, prompter, ctx) {
     return { ...argv, ...answers, cwd: targetPath };
 }
 async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest = false) {
+    // Determine workspace requirement (defaults to 'pgpm' for backward compatibility)
+    const workspaceType = ctx.requiresWorkspace ?? 'pgpm';
+    // Whether this is a pgpm-managed template (creates pgpm.plan, .control files)
+    const isPgpmTemplate = workspaceType === 'pgpm';
     const project = new core_1.PgpmPackage(ctx.cwd);
-    if (!project.workspacePath) {
-        const noTty = Boolean(argv.noTty || argv['no-tty'] || process.env.CI === 'true');
-        // If user explicitly requested module init or we're in non-interactive mode,
-        // just show the error with helpful guidance
-        if (wasExplicitModuleRequest || noTty) {
-            process.stderr.write('Not inside a PGPM workspace.\n');
-            throw types_1.errors.NOT_IN_WORKSPACE({});
+    // Check workspace requirement based on type (skip if workspaceType is false)
+    if (workspaceType !== false) {
+        let workspacePath;
+        let workspaceTypeName = '';
+        if (workspaceType === 'pgpm') {
+            workspacePath = project.workspacePath;
+            workspaceTypeName = 'PGPM';
         }
-        // Offer to create a workspace instead
-        const recoveryQuestion = [
-            {
-                name: 'workspace',
-                alias: 'w',
-                message: 'You are not inside a PGPM workspace. Would you like to create a new workspace instead?',
-                type: 'confirm',
-                required: true,
-            },
-        ];
-        const { workspace } = await prompter.prompt(argv, recoveryQuestion);
-        if (workspace) {
-            return handleWorkspaceInit(argv, prompter, {
-                fromPath: 'workspace',
-                templateRepo: ctx.templateRepo,
-                branch: ctx.branch,
-                dir: ctx.dir,
-                noTty: ctx.noTty,
-                cwd: ctx.cwd,
-            });
+        else {
+            workspacePath = (0, env_1.resolveWorkspaceByType)(ctx.cwd, workspaceType);
+            workspaceTypeName = workspaceType.toUpperCase();
+        }
+        if (!workspacePath) {
+            const noTty = Boolean(argv.noTty || argv['no-tty'] || process.env.CI === 'true');
+            // If user explicitly requested module init or we're in non-interactive mode,
+            // just show the error with helpful guidance
+            if (wasExplicitModuleRequest || noTty) {
+                process.stderr.write(`Not inside a ${workspaceTypeName} workspace.\n`);
+                throw types_1.errors.NOT_IN_WORKSPACE({});
+            }
+            // Only offer to create a workspace for pgpm templates
+            if (workspaceType === 'pgpm') {
+                const recoveryQuestion = [
+                    {
+                        name: 'workspace',
+                        alias: 'w',
+                        message: `You are not inside a ${workspaceTypeName} workspace. Would you like to create a new workspace instead?`,
+                        type: 'confirm',
+                        required: true,
+                    },
+                ];
+                const { workspace } = await prompter.prompt(argv, recoveryQuestion);
+                if (workspace) {
+                    return handleWorkspaceInit(argv, prompter, {
+                        fromPath: 'workspace',
+                        templateRepo: ctx.templateRepo,
+                        branch: ctx.branch,
+                        dir: ctx.dir,
+                        noTty: ctx.noTty,
+                        cwd: ctx.cwd,
+                    });
+                }
+            }
+            // User declined or non-pgpm workspace type, show the error
+            process.stderr.write(`Not inside a ${workspaceTypeName} workspace.\n`);
+            throw types_1.errors.NOT_IN_WORKSPACE({});
         }
-        // User declined, show the error
-        process.stderr.write('Not inside a PGPM workspace.\n');
-        throw types_1.errors.NOT_IN_WORKSPACE({});
     }
-    if (!project.isInsideAllowedDirs(ctx.cwd) && !project.isInWorkspace() && !project.isParentOfAllowedDirs(ctx.cwd)) {
-        process.stderr.write('You must be inside the workspace root or a parent directory of modules (like packages/).\n');
-        throw types_1.errors.NOT_IN_WORKSPACE_MODULE({});
+    // Only check workspace directory constraints if we're in a workspace
+    if (project.workspacePath) {
+        if (!project.isInsideAllowedDirs(ctx.cwd) && !project.isInWorkspace() && !project.isParentOfAllowedDirs(ctx.cwd)) {
+            process.stderr.write('You must be inside the workspace root or a parent directory of modules (like packages/).\n');
+            throw types_1.errors.NOT_IN_WORKSPACE_MODULE({});
+        }
     }
-    const availExtensions = await project.getAvailableModules();
-    // Note: moduleName is needed here before scaffolding because initModule creates
-    // the directory first, then scaffolds. The boilerplate's ____moduleName____ question
-    // gets skipped because the answer is already passed through. So users only see it
-    // once, but the definition exists in two places for this architectural reason.
+    // Build questions based on whether this is a pgpm template
     const moduleQuestions = [
         {
             name: 'moduleName',
@@ -283,7 +304,11 @@ async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest =
             required: true,
             type: 'text',
         },
-        {
+    ];
+    // Only ask for extensions if this is a pgpm template
+    if (isPgpmTemplate && project.workspacePath) {
+        const availExtensions = await project.getAvailableModules();
+        moduleQuestions.push({
             name: 'extensions',
             message: 'Which extensions?',
             options: availExtensions,
@@ -291,36 +316,61 @@ async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest =
             allowCustomOptions: true,
             required: true,
             default: ['plpgsql', 'uuid-ossp'],
-        },
-    ];
+        });
+    }
     const answers = await prompter.prompt(argv, moduleQuestions);
     const modName = (0, core_1.sluggify)(answers.moduleName);
-    const extensions = answers.extensions
-        .filter((opt) => opt.selected)
-        .map((opt) => opt.name);
+    const extensions = isPgpmTemplate && answers.extensions
+        ? answers.extensions
+            .filter((opt) => opt.selected)
+            .map((opt) => opt.name)
+        : [];
     const templateAnswers = {
         ...argv,
         ...answers,
         moduleName: modName,
         packageIdentifier: argv.packageIdentifier || modName
     };
-    await project.initModule({
-        name: modName,
-        description: answers.description || modName,
-        author: answers.author || modName,
-        extensions,
-        templateRepo: ctx.templateRepo,
-        templatePath: ctx.fromPath,
-        branch: ctx.branch,
-        dir: ctx.dir,
-        toolName: core_1.DEFAULT_TEMPLATE_TOOL_NAME,
-        answers: templateAnswers,
-        noTty: ctx.noTty
-    });
-    const isRoot = path_1.default.resolve(project.getWorkspacePath()) === path_1.default.resolve(ctx.cwd);
-    const modulePath = isRoot
-        ? path_1.default.join(ctx.cwd, 'packages', modName)
-        : path_1.default.join(ctx.cwd, modName);
+    // Determine output path based on whether we're in a workspace
+    let modulePath;
+    if (project.workspacePath) {
+        // Use workspace-aware initModule
+        await project.initModule({
+            name: modName,
+            description: answers.description || modName,
+            author: answers.author || modName,
+            extensions,
+            templateRepo: ctx.templateRepo,
+            templatePath: ctx.fromPath,
+            branch: ctx.branch,
+            dir: ctx.dir,
+            toolName: core_1.DEFAULT_TEMPLATE_TOOL_NAME,
+            answers: templateAnswers,
+            noTty: ctx.noTty,
+            pgpm: isPgpmTemplate,
+        });
+        const isRoot = path_1.default.resolve(project.workspacePath) === path_1.default.resolve(ctx.cwd);
+        modulePath = isRoot
+            ? path_1.default.join(ctx.cwd, 'packages', modName)
+            : path_1.default.join(ctx.cwd, modName);
+    }
+    else {
+        // Not in a workspace - scaffold directly to current directory
+        modulePath = path_1.default.join(ctx.cwd, modName);
+        fs_1.default.mkdirSync(modulePath, { recursive: true });
+        await (0, core_1.scaffoldTemplate)({
+            fromPath: ctx.fromPath,
+            outputDir: modulePath,
+            templateRepo: ctx.templateRepo,
+            branch: ctx.branch,
+            dir: ctx.dir,
+            answers: templateAnswers,
+            noTty: ctx.noTty,
+            toolName: core_1.DEFAULT_TEMPLATE_TOOL_NAME,
+            cwd: ctx.cwd,
+            prompter
+        });
+    }
     const motdPath = path_1.default.join(modulePath, '.motd');
     let motd = DEFAULT_MOTD;
     if (fs_1.default.existsSync(motdPath)) {
@@ -336,7 +386,6 @@ async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest =
     if (!motd.endsWith('\n')) {
         process.stdout.write('\n');
     }
-    const relPath = isRoot ? `packages/${modName}` : modName;
-    process.stdout.write(`\n✨ Enjoy!\n\ncd ./${relPath}\n`);
+    process.stdout.write(`\n✨ Enjoy!\n\ncd ./${modName}\n`);
     return { ...argv, ...answers };
 }

package/commands.js

@@ -14,6 +14,7 @@ const cache_1 = __importDefault(require("./commands/cache"));
 const clear_1 = __importDefault(require("./commands/clear"));
 const deploy_1 = __importDefault(require("./commands/deploy"));
 const docker_1 = __importDefault(require("./commands/docker"));
+const dump_1 = __importDefault(require("./commands/dump"));
 const env_1 = __importDefault(require("./commands/env"));
 const export_1 = __importDefault(require("./commands/export"));
 const extension_1 = __importDefault(require("./commands/extension"));
@@ -50,6 +51,7 @@ const createPgpmCommandMap = (skipPgTeardown = false) => {
         clear: pgt(clear_1.default),
         deploy: pgt(deploy_1.default),
         docker: docker_1.default,
+        dump: pgt(dump_1.default),
         env: env_1.default,
         verify: pgt(verify_1.default),
         revert: pgt(revert_1.default),

package/esm/commands/dump.js

@@ -0,0 +1,161 @@
+import { Logger } from '@pgpmjs/logger';
+import { getPgEnvOptions, getSpawnEnvWithPg } from 'pg-env';
+import { getPgPool } from 'pg-cache';
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { QuoteUtils } from 'pgsql-deparser/utils/quote-utils';
+import { getTargetDatabase } from '../utils';
+const log = new Logger('dump');
+const dumpUsageText = `
+Dump Command:
+
+  pgpm dump [options]
+
+  Dump a postgres database to a sql file.
+
+Options:
+  --help, -h                 Show this help message
+  --db, --database <name>    Target postgres database name
+  --out <path>               Output file path
+  --database-id <id>         When set, the dump will include a prune step that keeps only this database_id after restore
+  --cwd <directory>          Working directory (default: current directory)
+
+Examples:
+  pgpm dump
+  pgpm dump --database mydb
+  pgpm dump --database mydb --out ./mydb.sql
+  pgpm dump --database mydb --database-id 00000000-0000-0000-0000-000000000000
+`;
+function nowStamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+async function runPgDump(args, env) {
+    await new Promise((resolve, reject) => {
+        const child = spawn('pg_dump', args, {
+            env,
+            stdio: 'inherit',
+            shell: false
+        });
+        child.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                log.error('pg_dump not found; ensure PostgreSQL client tools are installed and in PATH');
+            }
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`pg_dump exited with code ${code ?? 1}`));
+        });
+    });
+}
+async function resolveDatabaseId(dbname, databaseIdRaw) {
+    const pool = getPgPool(getPgEnvOptions({ database: dbname }));
+    const res = await pool.query(`select id, name from metaschema_public.database order by name`);
+    const byId = res.rows.find((r) => String(r.id) === databaseIdRaw);
+    if (byId)
+        return { id: String(byId.id), name: String(byId.name) };
+    const byName = res.rows.find((r) => String(r.name) === databaseIdRaw);
+    if (byName)
+        return { id: String(byName.id), name: String(byName.name) };
+    return null;
+}
+async function buildPruneSql(dbname, databaseId) {
+    const pool = getPgPool(getPgEnvOptions({ database: dbname }));
+    const tables = await pool.query(`
+    select c.table_schema, c.table_name
+    from information_schema.columns c
+    join information_schema.tables t
+      on t.table_schema = c.table_schema
+      and t.table_name = c.table_name
+    where c.column_name = 'database_id'
+      and t.table_type = 'BASE TABLE'
+      and c.table_schema not in ('pg_catalog', 'information_schema')
+    order by c.table_schema, c.table_name
+  `);
+    const lines = [];
+    lines.push('');
+    lines.push('-- pgpm dump prune');
+    lines.push('-- this section keeps only one database_id after restore');
+    lines.push('do $$ begin');
+    lines.push(`  raise notice 'pruning data to database_id ${databaseId}';`);
+    lines.push('end $$;');
+    lines.push('set session_replication_role = replica;');
+    for (const row of tables.rows) {
+        const schema = String(row.table_schema);
+        const table = String(row.table_name);
+        // Use QuoteUtils for robust identifier quoting
+        const qualified = QuoteUtils.quoteQualifiedIdentifier(schema, table);
+        // Use formatEString to safely escape the UUID/string literal
+        const dbIdLiteral = QuoteUtils.formatEString(databaseId);
+        lines.push(`delete from ${qualified} where database_id <> ${dbIdLiteral};`);
+    }
+    // Handle metaschema_public.database deletion
+    const metaschemaDb = QuoteUtils.quoteQualifiedIdentifier('metaschema_public', 'database');
+    const dbIdLiteral = QuoteUtils.formatEString(databaseId);
+    lines.push(`delete from ${metaschemaDb} where id <> ${dbIdLiteral};`);
+    lines.push('set session_replication_role = origin;');
+    lines.push('do $$ begin');
+    lines.push(`  raise notice 'prune done';`);
+    lines.push('end $$;');
+    lines.push('');
+    return lines.join('\n');
+}
+// Helper to retrieve argument from parsed argv or positional _ array
+function getArg(argv, key) {
+    if (argv[key])
+        return argv[key];
+    const args = argv._ || [];
+    const idx = args.indexOf(`--${key}`);
+    if (idx > -1 && args.length > idx + 1) {
+        return args[idx + 1];
+    }
+    return undefined;
+}
+export default async (argv, prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(dumpUsageText);
+        process.exit(0);
+    }
+    const cwd = argv.cwd || process.cwd();
+    const dbname = await getTargetDatabase(argv, prompter, { message: 'Select database' });
+    const outPath = path.resolve(cwd, argv.out || `pgpm-dump-${dbname}-${nowStamp()}.sql`);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    let databaseIdInfo = null;
+    const databaseIdRaw = getArg(argv, 'database-id');
+    if (databaseIdRaw) {
+        databaseIdInfo = await resolveDatabaseId(dbname, databaseIdRaw);
+        if (!databaseIdInfo) {
+            throw new Error(`unknown database-id ${databaseIdRaw}`);
+        }
+    }
+    log.info(`dumping database ${dbname}`);
+    log.info(`writing to ${outPath}`);
+    if (databaseIdInfo) {
+        log.info(`database id ${databaseIdInfo.id}`);
+    }
+    const pgEnv = getPgEnvOptions({ database: dbname });
+    const spawnEnv = getSpawnEnvWithPg(pgEnv);
+    const args = [
+        '--format=plain',
+        '--no-owner',
+        '--no-privileges',
+        '--file',
+        outPath,
+        dbname
+    ];
+    await runPgDump(args, spawnEnv);
+    if (databaseIdInfo) {
+        const pruneSql = await buildPruneSql(dbname, databaseIdInfo.id);
+        // Use writeFileSync with 'a' flag for explicit append as requested
+        fs.writeFileSync(outPath, pruneSql, { encoding: 'utf8', flag: 'a' });
+        log.info('added prune section to dump file');
+    }
+    log.success('dump complete');
+    return argv;
+};

package/esm/commands/init/index.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { DEFAULT_TEMPLATE_REPO, DEFAULT_TEMPLATE_TOOL_NAME, inspectTemplate, PgpmPackage, resolveBoilerplateBaseDir, scaffoldTemplate, scanBoilerplates, sluggify, } from '@pgpmjs/core';
+import { resolveWorkspaceByType } from '@pgpmjs/env';
 import { errors } from '@pgpmjs/types';
 import { registerDefaultResolver } from 'inquirerer';
 const DEFAULT_MOTD = `
@@ -90,7 +91,7 @@ async function handleInit(argv, prompter) {
             cwd,
         });
     }
-    // Default to module init (for 'module' type or unknown types)
+    // Default to module init (for 'module' type, 'generic' type, or unknown types)
     return handleModuleInit(argv, prompter, {
         fromPath,
         templateRepo,
@@ -98,6 +99,7 @@ async function handleInit(argv, prompter) {
         dir,
         noTty,
         cwd,
+        requiresWorkspace: inspection.config?.requiresWorkspace,
     }, wasExplicitModuleRequest);
 }
 async function handleBoilerplateInit(argv, prompter, ctx) {
@@ -165,7 +167,7 @@ async function handleBoilerplateInit(argv, prompter, ctx) {
             cwd: ctx.cwd,
         });
     }
-    // Default to module init (for 'module' type or unknown types)
+    // Default to module init (for 'module' type, 'generic' type, or unknown types)
     // When using --boilerplate, user made an explicit choice, so treat as explicit request
     return handleModuleInit(argv, prompter, {
         fromPath,
@@ -174,6 +176,7 @@ async function handleBoilerplateInit(argv, prompter, ctx) {
         dir: ctx.dir,
         noTty: ctx.noTty,
         cwd: ctx.cwd,
+        requiresWorkspace: inspection.config?.requiresWorkspace,
     }, true);
 }
 async function handleWorkspaceInit(argv, prompter, ctx) {
@@ -226,49 +229,67 @@ async function handleWorkspaceInit(argv, prompter, ctx) {
     return { ...argv, ...answers, cwd: targetPath };
 }
 async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest = false) {
+    // Determine workspace requirement (defaults to 'pgpm' for backward compatibility)
+    const workspaceType = ctx.requiresWorkspace ?? 'pgpm';
+    // Whether this is a pgpm-managed template (creates pgpm.plan, .control files)
+    const isPgpmTemplate = workspaceType === 'pgpm';
     const project = new PgpmPackage(ctx.cwd);
-    if (!project.workspacePath) {
-        const noTty = Boolean(argv.noTty || argv['no-tty'] || process.env.CI === 'true');
-        // If user explicitly requested module init or we're in non-interactive mode,
-        // just show the error with helpful guidance
-        if (wasExplicitModuleRequest || noTty) {
-            process.stderr.write('Not inside a PGPM workspace.\n');
-            throw errors.NOT_IN_WORKSPACE({});
+    // Check workspace requirement based on type (skip if workspaceType is false)
+    if (workspaceType !== false) {
+        let workspacePath;
+        let workspaceTypeName = '';
+        if (workspaceType === 'pgpm') {
+            workspacePath = project.workspacePath;
+            workspaceTypeName = 'PGPM';
         }
-        // Offer to create a workspace instead
-        const recoveryQuestion = [
-            {
-                name: 'workspace',
-                alias: 'w',
-                message: 'You are not inside a PGPM workspace. Would you like to create a new workspace instead?',
-                type: 'confirm',
-                required: true,
-            },
-        ];
-        const { workspace } = await prompter.prompt(argv, recoveryQuestion);
-        if (workspace) {
-            return handleWorkspaceInit(argv, prompter, {
-                fromPath: 'workspace',
-                templateRepo: ctx.templateRepo,
-                branch: ctx.branch,
-                dir: ctx.dir,
-                noTty: ctx.noTty,
-                cwd: ctx.cwd,
-            });
+        else {
+            workspacePath = resolveWorkspaceByType(ctx.cwd, workspaceType);
+            workspaceTypeName = workspaceType.toUpperCase();
+        }
+        if (!workspacePath) {
+            const noTty = Boolean(argv.noTty || argv['no-tty'] || process.env.CI === 'true');
+            // If user explicitly requested module init or we're in non-interactive mode,
+            // just show the error with helpful guidance
+            if (wasExplicitModuleRequest || noTty) {
+                process.stderr.write(`Not inside a ${workspaceTypeName} workspace.\n`);
+                throw errors.NOT_IN_WORKSPACE({});
+            }
+            // Only offer to create a workspace for pgpm templates
+            if (workspaceType === 'pgpm') {
+                const recoveryQuestion = [
+                    {
+                        name: 'workspace',
+                        alias: 'w',
+                        message: `You are not inside a ${workspaceTypeName} workspace. Would you like to create a new workspace instead?`,
+                        type: 'confirm',
+                        required: true,
+                    },
+                ];
+                const { workspace } = await prompter.prompt(argv, recoveryQuestion);
+                if (workspace) {
+                    return handleWorkspaceInit(argv, prompter, {
+                        fromPath: 'workspace',
+                        templateRepo: ctx.templateRepo,
+                        branch: ctx.branch,
+                        dir: ctx.dir,
+                        noTty: ctx.noTty,
+                        cwd: ctx.cwd,
+                    });
+                }
+            }
+            // User declined or non-pgpm workspace type, show the error
+            process.stderr.write(`Not inside a ${workspaceTypeName} workspace.\n`);
+            throw errors.NOT_IN_WORKSPACE({});
         }
-        // User declined, show the error
-        process.stderr.write('Not inside a PGPM workspace.\n');
-        throw errors.NOT_IN_WORKSPACE({});
     }
-    if (!project.isInsideAllowedDirs(ctx.cwd) && !project.isInWorkspace() && !project.isParentOfAllowedDirs(ctx.cwd)) {
-        process.stderr.write('You must be inside the workspace root or a parent directory of modules (like packages/).\n');
-        throw errors.NOT_IN_WORKSPACE_MODULE({});
+    // Only check workspace directory constraints if we're in a workspace
+    if (project.workspacePath) {
+        if (!project.isInsideAllowedDirs(ctx.cwd) && !project.isInWorkspace() && !project.isParentOfAllowedDirs(ctx.cwd)) {
+            process.stderr.write('You must be inside the workspace root or a parent directory of modules (like packages/).\n');
+            throw errors.NOT_IN_WORKSPACE_MODULE({});
+        }
     }
-    const availExtensions = await project.getAvailableModules();
-    // Note: moduleName is needed here before scaffolding because initModule creates
-    // the directory first, then scaffolds. The boilerplate's ____moduleName____ question
-    // gets skipped because the answer is already passed through. So users only see it
-    // once, but the definition exists in two places for this architectural reason.
+    // Build questions based on whether this is a pgpm template
     const moduleQuestions = [
         {
             name: 'moduleName',
@@ -276,7 +297,11 @@ async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest =
             required: true,
             type: 'text',
         },
-        {
+    ];
+    // Only ask for extensions if this is a pgpm template
+    if (isPgpmTemplate && project.workspacePath) {
+        const availExtensions = await project.getAvailableModules();
+        moduleQuestions.push({
             name: 'extensions',
             message: 'Which extensions?',
             options: availExtensions,
@@ -284,36 +309,61 @@ async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest =
             allowCustomOptions: true,
             required: true,
             default: ['plpgsql', 'uuid-ossp'],
-        },
-    ];
+        });
+    }
     const answers = await prompter.prompt(argv, moduleQuestions);
     const modName = sluggify(answers.moduleName);
-    const extensions = answers.extensions
-        .filter((opt) => opt.selected)
-        .map((opt) => opt.name);
+    const extensions = isPgpmTemplate && answers.extensions
+        ? answers.extensions
+            .filter((opt) => opt.selected)
+            .map((opt) => opt.name)
+        : [];
     const templateAnswers = {
         ...argv,
         ...answers,
         moduleName: modName,
         packageIdentifier: argv.packageIdentifier || modName
     };
-    await project.initModule({
-        name: modName,
-        description: answers.description || modName,
-        author: answers.author || modName,
-        extensions,
-        templateRepo: ctx.templateRepo,
-        templatePath: ctx.fromPath,
-        branch: ctx.branch,
-        dir: ctx.dir,
-        toolName: DEFAULT_TEMPLATE_TOOL_NAME,
-        answers: templateAnswers,
-        noTty: ctx.noTty
-    });
-    const isRoot = path.resolve(project.getWorkspacePath()) === path.resolve(ctx.cwd);
-    const modulePath = isRoot
-        ? path.join(ctx.cwd, 'packages', modName)
-        : path.join(ctx.cwd, modName);
+    // Determine output path based on whether we're in a workspace
+    let modulePath;
+    if (project.workspacePath) {
+        // Use workspace-aware initModule
+        await project.initModule({
+            name: modName,
+            description: answers.description || modName,
+            author: answers.author || modName,
+            extensions,
+            templateRepo: ctx.templateRepo,
+            templatePath: ctx.fromPath,
+            branch: ctx.branch,
+            dir: ctx.dir,
+            toolName: DEFAULT_TEMPLATE_TOOL_NAME,
+            answers: templateAnswers,
+            noTty: ctx.noTty,
+            pgpm: isPgpmTemplate,
+        });
+        const isRoot = path.resolve(project.workspacePath) === path.resolve(ctx.cwd);
+        modulePath = isRoot
+            ? path.join(ctx.cwd, 'packages', modName)
+            : path.join(ctx.cwd, modName);
+    }
+    else {
+        // Not in a workspace - scaffold directly to current directory
+        modulePath = path.join(ctx.cwd, modName);
+        fs.mkdirSync(modulePath, { recursive: true });
+        await scaffoldTemplate({
+            fromPath: ctx.fromPath,
+            outputDir: modulePath,
+            templateRepo: ctx.templateRepo,
+            branch: ctx.branch,
+            dir: ctx.dir,
+            answers: templateAnswers,
+            noTty: ctx.noTty,
+            toolName: DEFAULT_TEMPLATE_TOOL_NAME,
+            cwd: ctx.cwd,
+            prompter
+        });
+    }
     const motdPath = path.join(modulePath, '.motd');
     let motd = DEFAULT_MOTD;
     if (fs.existsSync(motdPath)) {
@@ -329,7 +379,6 @@ async function handleModuleInit(argv, prompter, ctx, wasExplicitModuleRequest =
     if (!motd.endsWith('\n')) {
         process.stdout.write('\n');
     }
-    const relPath = isRoot ? `packages/${modName}` : modName;
-    process.stdout.write(`\n✨ Enjoy!\n\ncd ./${relPath}\n`);
+    process.stdout.write(`\n✨ Enjoy!\n\ncd ./${modName}\n`);
     return { ...argv, ...answers };
 }

package/esm/commands.js

@@ -8,6 +8,7 @@ import cache from './commands/cache';
 import clear from './commands/clear';
 import deploy from './commands/deploy';
 import docker from './commands/docker';
+import dump from './commands/dump';
 import env from './commands/env';
 import _export from './commands/export';
 import extension from './commands/extension';
@@ -44,6 +45,7 @@ export const createPgpmCommandMap = (skipPgTeardown = false) => {
         clear: pgt(clear),
         deploy: pgt(deploy),
         docker,
+        dump: pgt(dump),
         env,
         verify: pgt(verify),
         revert: pgt(revert),

package/esm/index.js

@@ -10,6 +10,7 @@ export { default as analyze } from './commands/analyze';
 export { default as clear } from './commands/clear';
 export { default as deploy } from './commands/deploy';
 export { default as docker } from './commands/docker';
+export { default as dump } from './commands/dump';
 export { default as env } from './commands/env';
 export { default as _export } from './commands/export';
 export { default as extension } from './commands/extension';

package/esm/utils/display.js

@@ -18,6 +18,7 @@ export const usageText = `
     upgrade            Upgrade installed pgpm modules to latest versions (alias: up)
 
   Database Administration:
+    dump               Dump a database to a sql file
     kill               Terminate database connections and optionally drop databases
     install            Install database modules
     tag                Add tags to changes for versioning

package/index.d.ts

@@ -9,6 +9,7 @@ export { default as analyze } from './commands/analyze';
 export { default as clear } from './commands/clear';
 export { default as deploy } from './commands/deploy';
 export { default as docker } from './commands/docker';
+export { default as dump } from './commands/dump';
 export { default as env } from './commands/env';
 export { default as _export } from './commands/export';
 export { default as extension } from './commands/extension';

package/index.js

@@ -18,7 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.options = exports.verify = exports.testPackages = exports.tag = exports.revert = exports.renameCmd = exports.remove = exports.plan = exports._package = exports.migrate = exports.kill = exports.install = exports.extension = exports._export = exports.env = exports.docker = exports.deploy = exports.clear = exports.analyze = exports.adminUsers = exports.add = exports.createPgpmCommandMap = exports.createInitUsageText = void 0;
+exports.options = exports.verify = exports.testPackages = exports.tag = exports.revert = exports.renameCmd = exports.remove = exports.plan = exports._package = exports.migrate = exports.kill = exports.install = exports.extension = exports._export = exports.env = exports.dump = exports.docker = exports.deploy = exports.clear = exports.analyze = exports.adminUsers = exports.add = exports.createPgpmCommandMap = exports.createInitUsageText = void 0;
 const find_and_require_package_json_1 = require("find-and-require-package-json");
 const inquirerer_1 = require("inquirerer");
 const commands_1 = require("./commands");
@@ -37,6 +37,8 @@ var deploy_1 = require("./commands/deploy");
 Object.defineProperty(exports, "deploy", { enumerable: true, get: function () { return __importDefault(deploy_1).default; } });
 var docker_1 = require("./commands/docker");
 Object.defineProperty(exports, "docker", { enumerable: true, get: function () { return __importDefault(docker_1).default; } });
+var dump_1 = require("./commands/dump");
+Object.defineProperty(exports, "dump", { enumerable: true, get: function () { return __importDefault(dump_1).default; } });
 var env_1 = require("./commands/env");
 Object.defineProperty(exports, "env", { enumerable: true, get: function () { return __importDefault(env_1).default; } });
 var export_1 = require("./commands/export");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgpm",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL Package Manager - Database migration and package management CLI",
   "main": "index.js",
@@ -33,7 +33,7 @@
     "test:watch": "jest --watch"
   },
   "devDependencies": {
-    "@inquirerer/test": "^1.2.3",
+    "@inquirerer/test": "^1.2.5",
     "@types/js-yaml": "^4.0.9",
     "@types/minimist": "^1.2.5",
     "@types/node": "^20.12.7",
@@ -46,19 +46,20 @@
     "ts-node": "^10.9.2"
   },
   "dependencies": {
-    "@inquirerer/utils": "^3.1.2",
-    "@pgpmjs/core": "^4.9.1",
-    "@pgpmjs/env": "^2.9.2",
+    "@inquirerer/utils": "^3.1.3",
+    "@pgpmjs/core": "^4.10.1",
+    "@pgpmjs/env": "^2.9.3",
     "@pgpmjs/logger": "^1.3.7",
     "@pgpmjs/types": "^2.14.0",
-    "appstash": "^0.2.7",
-    "find-and-require-package-json": "^0.8.5",
-    "genomic": "^5.2.0",
-    "inquirerer": "^4.2.0",
+    "appstash": "^0.2.8",
+    "find-and-require-package-json": "^0.8.6",
+    "genomic": "^5.2.3",
+    "inquirerer": "^4.3.1",
     "js-yaml": "^4.1.0",
     "minimist": "^1.2.8",
     "pg-cache": "^1.6.14",
     "pg-env": "^1.2.5",
+    "pgsql-deparser": "^17.17.2",
     "semver": "^7.6.2",
     "shelljs": "^0.10.0",
     "yanse": "^0.1.11"
@@ -75,5 +76,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "baa2f7598cde3baf3f05f161a11bafa12c66f6aa"
+  "gitHead": "22c89cfc6f67879e77ca47f652c31c80828665f5"
 }

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    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    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\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 PostgreSQL Docker containers (start/stop)\n    env                Manage PostgreSQL environment variables\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    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\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 PostgreSQL Docker containers (start/stop)\n    env                Manage PostgreSQL environment variables\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  ";

package/utils/display.js

@@ -21,6 +21,7 @@ exports.usageText = `
     upgrade            Upgrade installed pgpm modules to latest versions (alias: up)
 
   Database Administration:
+    dump               Dump a database to a sql file
     kill               Terminate database connections and optionally drop databases
     install            Install database modules
     tag                Add tags to changes for versioning