pgpm 0.2.1 → 0.2.3

package/README.md

@@ -14,28 +14,39 @@
 - 🚀 **Turnkey Module-First Workspaces** — `pgpm init` delivers a ready-to-code Postgres workspace with CI/CD, Docker, end-to-end testing, and modern TS tooling.
 
 
+Here’s a version that keeps it **light**, **simple**, and **zero-fluff**, but still feels tight and confident:
+
 ## 🚀 Quick Start
 
-### Installation
+### Install & Setup
 
 ```bash
+# Install pgpm globally
 npm install -g pgpm
+
+# Start local Postgres (via Docker) and export env vars
+pgpm docker start
+eval "$(pgpm env)"
 ```
 
+> **Tip:** Already running Postgres? Skip the Docker step and just export your PG* vars.
+
+---
+
 ### Create Your First Project
 
 ```bash
-# 1. Create workspace
+# 1. Create a workspace
 pgpm init --workspace
 cd my-app
 
 # 2. Create your first module
 pgpm init
 
-# 3. Add some SQL migrations to sql/ directory
+# 3. Add a database change
 pgpm add some_change
 
-# 4. Deploy to database
+# 4. Deploy everything
 pgpm deploy --createdb
 ```
 
@@ -46,6 +57,12 @@ pgpm deploy --createdb
 - `pgpm init` - Initialize a new module
 - `pgpm init --workspace` - Initialize a new workspace
 
+### Development Setup
+
+- `pgpm docker start` - Start PostgreSQL container (via Docker)
+- `pgpm docker stop` - Stop PostgreSQL container
+- `pgpm env` - Print PostgreSQL environment variables for shell export
+
 ### Database Operations
 
 - `pgpm deploy` - Deploy database changes and migrations

package/commands/docker.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer } from 'inquirerer';
+declare const _default: (argv: Partial<Record<string, any>>, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/commands/docker.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const utils_1 = require("../utils");
+const dockerUsageText = `
+Docker Command:
+
+  pgpm docker <subcommand> [OPTIONS]
+
+  Manage PostgreSQL Docker containers for local development.
+
+Subcommands:
+  start              Start PostgreSQL container
+  stop               Stop PostgreSQL container
+
+Options:
+  --help, -h         Show this help message
+  --name <name>      Container name (default: postgres)
+  --image <image>    Docker image (default: pyramation/pgvector:13.3-alpine)
+  --port <port>      Host port mapping (default: 5432)
+  --user <user>      PostgreSQL user (default: postgres)
+  --password <pass>  PostgreSQL password (default: password)
+  --recreate         Remove and recreate container on start
+
+Examples:
+  pgpm docker start                           Start default PostgreSQL container
+  pgpm docker start --port 5433               Start on custom port
+  pgpm docker start --recreate                Remove and recreate container
+  pgpm docker stop                            Stop PostgreSQL container
+`;
+function run(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const stdio = options.stdio || 'pipe';
+        const child = (0, child_process_1.spawn)(command, args, { stdio });
+        let stdout = '';
+        let stderr = '';
+        if (stdio === 'pipe') {
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code) => {
+            resolve({
+                code: code ?? 0,
+                stdout: stdout.trim(),
+                stderr: stderr.trim()
+            });
+        });
+    });
+}
+async function checkDockerAvailable() {
+    try {
+        const result = await run('docker', ['--version']);
+        return result.code === 0;
+    }
+    catch (error) {
+        return false;
+    }
+}
+async function isContainerRunning(name) {
+    try {
+        const result = await run('docker', ['inspect', '-f', '{{.State.Running}}', name]);
+        if (result.code === 0) {
+            return result.stdout.trim() === 'true';
+        }
+        return null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+async function containerExists(name) {
+    try {
+        const result = await run('docker', ['inspect', name]);
+        return result.code === 0;
+    }
+    catch (error) {
+        return false;
+    }
+}
+async function startContainer(options) {
+    const { name, image, port, user, password, recreate } = options;
+    const dockerAvailable = await checkDockerAvailable();
+    if (!dockerAvailable) {
+        await (0, utils_1.cliExitWithError)('Docker is not installed or not available in PATH. Please install Docker first.');
+        return;
+    }
+    const exists = await containerExists(name);
+    const running = await isContainerRunning(name);
+    if (running === true) {
+        console.log(`✅ Container "${name}" is already running`);
+        return;
+    }
+    if (recreate && exists) {
+        console.log(`🗑️  Removing existing container "${name}"...`);
+        const removeResult = await run('docker', ['rm', '-f', name], { stdio: 'inherit' });
+        if (removeResult.code !== 0) {
+            await (0, utils_1.cliExitWithError)(`Failed to remove container "${name}"`);
+            return;
+        }
+    }
+    if (exists && running === false) {
+        console.log(`🔄 Starting existing container "${name}"...`);
+        const startResult = await run('docker', ['start', name], { stdio: 'inherit' });
+        if (startResult.code === 0) {
+            console.log(`✅ Container "${name}" started successfully`);
+        }
+        else {
+            await (0, utils_1.cliExitWithError)(`Failed to start container "${name}"`);
+        }
+        return;
+    }
+    console.log(`🚀 Creating and starting new container "${name}"...`);
+    const runArgs = [
+        'run',
+        '-d',
+        '--name', name,
+        '-e', `POSTGRES_USER=${user}`,
+        '-e', `POSTGRES_PASSWORD=${password}`,
+        '-p', `${port}:5432`,
+        image
+    ];
+    const runResult = await run('docker', runArgs, { stdio: 'inherit' });
+    if (runResult.code === 0) {
+        console.log(`✅ Container "${name}" created and started successfully`);
+        console.log(`📌 PostgreSQL is available at localhost:${port}`);
+        console.log(`👤 User: ${user}`);
+        console.log(`🔑 Password: ${password}`);
+    }
+    else {
+        await (0, utils_1.cliExitWithError)(`Failed to create container "${name}". Check if port ${port} is already in use.`);
+    }
+}
+async function stopContainer(name) {
+    const dockerAvailable = await checkDockerAvailable();
+    if (!dockerAvailable) {
+        await (0, utils_1.cliExitWithError)('Docker is not installed or not available in PATH. Please install Docker first.');
+        return;
+    }
+    const exists = await containerExists(name);
+    if (!exists) {
+        console.log(`ℹ️  Container "${name}" not found`);
+        return;
+    }
+    const running = await isContainerRunning(name);
+    if (running === false) {
+        console.log(`ℹ️  Container "${name}" is already stopped`);
+        return;
+    }
+    console.log(`🛑 Stopping container "${name}"...`);
+    const stopResult = await run('docker', ['stop', name], { stdio: 'inherit' });
+    if (stopResult.code === 0) {
+        console.log(`✅ Container "${name}" stopped successfully`);
+    }
+    else {
+        await (0, utils_1.cliExitWithError)(`Failed to stop container "${name}"`);
+    }
+}
+exports.default = async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(dockerUsageText);
+        process.exit(0);
+    }
+    const { first: subcommand, newArgv } = (0, utils_1.extractFirst)(argv);
+    const args = newArgv;
+    if (!subcommand) {
+        console.log(dockerUsageText);
+        await (0, utils_1.cliExitWithError)('No subcommand provided. Use "start" or "stop".');
+        return;
+    }
+    const name = args.name || 'postgres';
+    const image = args.image || 'pyramation/pgvector:13.3-alpine';
+    const port = typeof args.port === 'number' ? args.port : 5432;
+    const user = args.user || 'postgres';
+    const password = args.password || 'password';
+    const recreate = args.recreate === true;
+    switch (subcommand) {
+        case 'start':
+            await startContainer({ name, image, port, user, password, recreate });
+            break;
+        case 'stop':
+            await stopContainer(name);
+            break;
+        default:
+            console.log(dockerUsageText);
+            await (0, utils_1.cliExitWithError)(`Unknown subcommand: ${subcommand}. Use "start" or "stop".`);
+    }
+};

package/commands.js

@@ -10,6 +10,7 @@ const admin_users_1 = __importDefault(require("./commands/admin-users"));
 const analyze_1 = __importDefault(require("./commands/analyze"));
 const clear_1 = __importDefault(require("./commands/clear"));
 const deploy_1 = __importDefault(require("./commands/deploy"));
+const docker_1 = __importDefault(require("./commands/docker"));
 const env_1 = __importDefault(require("./commands/env"));
 const export_1 = __importDefault(require("./commands/export"));
 const extension_1 = __importDefault(require("./commands/extension"));
@@ -44,6 +45,7 @@ const createPgpmCommandMap = (skipPgTeardown = false) => {
         'admin-users': pgt(admin_users_1.default),
         clear: pgt(clear_1.default),
         deploy: pgt(deploy_1.default),
+        docker: docker_1.default,
         env: env_1.default,
         verify: pgt(verify_1.default),
         revert: pgt(revert_1.default),

package/esm/commands/docker.js

@@ -0,0 +1,192 @@
+import { spawn } from 'child_process';
+import { cliExitWithError, extractFirst } from '../utils';
+const dockerUsageText = `
+Docker Command:
+
+  pgpm docker <subcommand> [OPTIONS]
+
+  Manage PostgreSQL Docker containers for local development.
+
+Subcommands:
+  start              Start PostgreSQL container
+  stop               Stop PostgreSQL container
+
+Options:
+  --help, -h         Show this help message
+  --name <name>      Container name (default: postgres)
+  --image <image>    Docker image (default: pyramation/pgvector:13.3-alpine)
+  --port <port>      Host port mapping (default: 5432)
+  --user <user>      PostgreSQL user (default: postgres)
+  --password <pass>  PostgreSQL password (default: password)
+  --recreate         Remove and recreate container on start
+
+Examples:
+  pgpm docker start                           Start default PostgreSQL container
+  pgpm docker start --port 5433               Start on custom port
+  pgpm docker start --recreate                Remove and recreate container
+  pgpm docker stop                            Stop PostgreSQL container
+`;
+function run(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const stdio = options.stdio || 'pipe';
+        const child = spawn(command, args, { stdio });
+        let stdout = '';
+        let stderr = '';
+        if (stdio === 'pipe') {
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code) => {
+            resolve({
+                code: code ?? 0,
+                stdout: stdout.trim(),
+                stderr: stderr.trim()
+            });
+        });
+    });
+}
+async function checkDockerAvailable() {
+    try {
+        const result = await run('docker', ['--version']);
+        return result.code === 0;
+    }
+    catch (error) {
+        return false;
+    }
+}
+async function isContainerRunning(name) {
+    try {
+        const result = await run('docker', ['inspect', '-f', '{{.State.Running}}', name]);
+        if (result.code === 0) {
+            return result.stdout.trim() === 'true';
+        }
+        return null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+async function containerExists(name) {
+    try {
+        const result = await run('docker', ['inspect', name]);
+        return result.code === 0;
+    }
+    catch (error) {
+        return false;
+    }
+}
+async function startContainer(options) {
+    const { name, image, port, user, password, recreate } = options;
+    const dockerAvailable = await checkDockerAvailable();
+    if (!dockerAvailable) {
+        await cliExitWithError('Docker is not installed or not available in PATH. Please install Docker first.');
+        return;
+    }
+    const exists = await containerExists(name);
+    const running = await isContainerRunning(name);
+    if (running === true) {
+        console.log(`✅ Container "${name}" is already running`);
+        return;
+    }
+    if (recreate && exists) {
+        console.log(`🗑️  Removing existing container "${name}"...`);
+        const removeResult = await run('docker', ['rm', '-f', name], { stdio: 'inherit' });
+        if (removeResult.code !== 0) {
+            await cliExitWithError(`Failed to remove container "${name}"`);
+            return;
+        }
+    }
+    if (exists && running === false) {
+        console.log(`🔄 Starting existing container "${name}"...`);
+        const startResult = await run('docker', ['start', name], { stdio: 'inherit' });
+        if (startResult.code === 0) {
+            console.log(`✅ Container "${name}" started successfully`);
+        }
+        else {
+            await cliExitWithError(`Failed to start container "${name}"`);
+        }
+        return;
+    }
+    console.log(`🚀 Creating and starting new container "${name}"...`);
+    const runArgs = [
+        'run',
+        '-d',
+        '--name', name,
+        '-e', `POSTGRES_USER=${user}`,
+        '-e', `POSTGRES_PASSWORD=${password}`,
+        '-p', `${port}:5432`,
+        image
+    ];
+    const runResult = await run('docker', runArgs, { stdio: 'inherit' });
+    if (runResult.code === 0) {
+        console.log(`✅ Container "${name}" created and started successfully`);
+        console.log(`📌 PostgreSQL is available at localhost:${port}`);
+        console.log(`👤 User: ${user}`);
+        console.log(`🔑 Password: ${password}`);
+    }
+    else {
+        await cliExitWithError(`Failed to create container "${name}". Check if port ${port} is already in use.`);
+    }
+}
+async function stopContainer(name) {
+    const dockerAvailable = await checkDockerAvailable();
+    if (!dockerAvailable) {
+        await cliExitWithError('Docker is not installed or not available in PATH. Please install Docker first.');
+        return;
+    }
+    const exists = await containerExists(name);
+    if (!exists) {
+        console.log(`ℹ️  Container "${name}" not found`);
+        return;
+    }
+    const running = await isContainerRunning(name);
+    if (running === false) {
+        console.log(`ℹ️  Container "${name}" is already stopped`);
+        return;
+    }
+    console.log(`🛑 Stopping container "${name}"...`);
+    const stopResult = await run('docker', ['stop', name], { stdio: 'inherit' });
+    if (stopResult.code === 0) {
+        console.log(`✅ Container "${name}" stopped successfully`);
+    }
+    else {
+        await cliExitWithError(`Failed to stop container "${name}"`);
+    }
+}
+export default async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(dockerUsageText);
+        process.exit(0);
+    }
+    const { first: subcommand, newArgv } = extractFirst(argv);
+    const args = newArgv;
+    if (!subcommand) {
+        console.log(dockerUsageText);
+        await cliExitWithError('No subcommand provided. Use "start" or "stop".');
+        return;
+    }
+    const name = args.name || 'postgres';
+    const image = args.image || 'pyramation/pgvector:13.3-alpine';
+    const port = typeof args.port === 'number' ? args.port : 5432;
+    const user = args.user || 'postgres';
+    const password = args.password || 'password';
+    const recreate = args.recreate === true;
+    switch (subcommand) {
+        case 'start':
+            await startContainer({ name, image, port, user, password, recreate });
+            break;
+        case 'stop':
+            await stopContainer(name);
+            break;
+        default:
+            console.log(dockerUsageText);
+            await cliExitWithError(`Unknown subcommand: ${subcommand}. Use "start" or "stop".`);
+    }
+};

package/esm/commands.js

@@ -4,6 +4,7 @@ import adminUsers from './commands/admin-users';
 import analyze from './commands/analyze';
 import clear from './commands/clear';
 import deploy from './commands/deploy';
+import docker from './commands/docker';
 import env from './commands/env';
 import _export from './commands/export';
 import extension from './commands/extension';
@@ -38,6 +39,7 @@ export const createPgpmCommandMap = (skipPgTeardown = false) => {
         'admin-users': pgt(adminUsers),
         clear: pgt(clear),
         deploy: pgt(deploy),
+        docker,
         env,
         verify: pgt(verify),
         revert: pgt(revert),

package/esm/index.js

@@ -9,6 +9,7 @@ export { default as adminUsers } from './commands/admin-users';
 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 env } from './commands/env';
 export { default as _export } from './commands/export';
 export { default as extension } from './commands/extension';

package/index.d.ts

@@ -7,6 +7,7 @@ export { default as adminUsers } from './commands/admin-users';
 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 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.tag = exports.revert = exports.renameCmd = exports.remove = exports.plan = exports._package = exports.migrate = exports.kill = exports.install = exports.extension = exports._export = exports.env = exports.deploy = exports.clear = exports.analyze = exports.adminUsers = exports.add = exports.createPgpmCommandMap = void 0;
+exports.options = exports.verify = 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 = void 0;
 const fs_1 = require("fs");
 const inquirerer_1 = require("inquirerer");
 const path_1 = require("path");
@@ -34,6 +34,8 @@ var clear_1 = require("./commands/clear");
 Object.defineProperty(exports, "clear", { enumerable: true, get: function () { return __importDefault(clear_1).default; } });
 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 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": "0.2.1",
+  "version": "0.2.3",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "description": "PostgreSQL Package Manager - Database migration and package management CLI",
   "main": "index.js",
@@ -70,5 +70,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "2bc45c48444fc9c2cce9f082cf33d533915bb048"
+  "gitHead": "6fc8eb0f1fdf69575f7198708121e4f43134c965"
 }