pgpm

library0.1.62jsnpmunverified

pgpm is a powerful and opinionated command-line interface (CLI) for managing PostgreSQL database schemas, migrations, and modules, akin to a package manager for your database. It is designed for modular PostgreSQL development, enabling the creation and management of reusable database packages with dependency resolution and semantic versioning. The tool features a deterministic migration engine, offering version-controlled, plan-driven deployments with rollback capabilities and idempotent execution. It supports recursive module resolution across workspaces and provides turnkey module-first workspaces ready for CI/CD, Docker, and end-to-end testing with TypeScript tooling. The current stable version is 4.16.3, and it appears to be actively maintained with a focus on robust and reproducible database development workflows.

database devops web-framework

npm install pgpm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGPM

pgpm

databasejavascriptv0.1.62

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PgpmConfiguration

✓ import type { PgpmConfiguration } from 'pgpm'

While `pgpm` is primarily a CLI tool and not typically imported for runtime execution, it ships TypeScript types. This import is for type-checking configuration objects (e.g., in a `pgpm.config.ts` file) if such programmatic configuration is supported or exposed. Direct runtime imports of `pgpm`'s core functionality are uncommon.

deploy

✓ import { deploy } from 'pgpm/commands'

This is a hypothetical import for programmatic access to specific `pgpm` commands. The primary usage pattern for `pgpm` is via the command line. Direct programmatic invocation might exist for advanced scenarios or internal tooling, but is not the typical user interaction.

initWorkspace

✓ import { initWorkspace } from 'pgpm/workspace'

Similar to `deploy`, this is a hypothetical programmatic import for workspace initialization. Most users will interact with `pgpm` via `pgpm init workspace` directly from the terminal, reflecting its CLI-first design.

Demonstrates global installation, starting a local PostgreSQL instance via Docker, initializing a workspace and a module, adding a basic migration, and deploying changes to the database.

# Install pgpm globally npm install -g pgpm # Start a local PostgreSQL instance using Docker and export environment variables pgpm docker start eval "$(pgpm env)" # Create a new pgpm workspace pgpm init workspace my-app cd my-app # Create your first database module within the workspace pgpm init packages/my-module cd packages/my-module # Add a sample migration (e.g., create a users table) # Create src/migrations/001_create_users_table.sql with content: /* create table users ( id serial primary key, name text not null ); */ # Return to the workspace root cd ../.. # Deploy all changes and modules to the database, creating the database if it doesn't exist pgpm deploy --createdb --database mydatabase console.log("pgpm workspace and initial module deployed successfully!")

pgpm --version

Debug

Known issues

breakingMajor versions of `pgpm` may introduce changes to migration file formats, project structure, or command-line arguments. Always review release notes carefully before upgrading to avoid unexpected behavior or requiring manual migration adjustments.

fix

Consult the official `pgpm` release notes for your target version and update migration scripts or project configurations as specified. Back up your database and codebase before any major upgrade.

affects: >=4.0

gotchaWhen running `pgpm` commands that interact with a database (e.g., `deploy`, `verify`), ensure your `PG*` environment variables (like `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`) are correctly set. `pgpm` relies on these for connection, and incorrect settings will lead to connection errors.

fix

Use `eval "$(pgpm env)"` after `pgpm docker start` or manually set `PG*` environment variables in your shell. For CI/CD, configure these variables in your pipeline environment.

affects: >=1.0

breakingThe package resolution logic for `pgpm`'s database modules changed in prior versions, moving towards a more `npm`-like recursive dependency model. This might affect how modules are located and deployed if not updated.

fix

Ensure your `pgpm` workspace and module definitions conform to the latest recursive module resolution standards. Use `pgpm init` and `pgpm install` to correctly scaffold and manage module dependencies.

affects: >=3.0

gotchaDirect modification of `pgpm`-managed database objects outside of `pgpm` migrations can lead to 'migration checksum mismatch' errors, as `pgpm`'s deterministic engine expects controlled schema changes. This often happens if you manually alter the database schema or run raw SQL outside the `pgpm` workflow.

fix

Always use `pgpm`'s migration system to introduce schema changes. If a mismatch occurs, investigate the differences in your migration files and the applied schema. You may need to revert, fix, and re-deploy, or in rare cases, manually synchronize the migration state, understanding the associated risks.

affects: >=1.0

Errors

Common errors & fixes

Error: Database connection refused.

The `pgpm` CLI tool cannot establish a connection to the PostgreSQL database, likely due to incorrect connection parameters, the database not running, or network issues.

fix

Verify that your PostgreSQL database is running and accessible. Check your `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, and `PGDATABASE` environment variables. If using Docker, ensure `pgpm docker start` was successful and `eval "$(pgpm env)"` was run.

Error: Migration checksum mismatch detected for migration '001_initial_schema.sql'.

The content of a previously applied migration file has changed, or the corresponding schema object in the database no longer matches the expected state recorded by `pgpm`.

fix

Do NOT modify migration files after they have been deployed to a shared environment. If this occurred in development, revert the changes, or if necessary, reset your local database state and re-deploy. For production, a new 'reverting' migration or a data patch might be needed, with careful planning.

Error: Module '@pgpm/my-module' not found or dependency not resolved.

The `pgpm` CLI could not locate a referenced database module or resolve its dependencies, often due to an incorrect module name, missing installation, or an issue with the workspace configuration.

fix

Ensure the module name is correct. If it's a public module, run `pgpm install @pgpm/my-module`. If it's a local module within your workspace, verify its `package.json` and directory structure. Check your `pgpm.json` configuration for correct module paths.

Error: There are pending migrations that have not been applied.

The database schema is not up-to-date with the latest migration files in your project. This means new migration files exist in your codebase that haven't been run against the connected database.

fix

Run `pgpm deploy` to apply the pending migrations to your database. If you expect the database to be up-to-date, run `pgpm verify` to identify which migrations are pending or if there's a discrepancy.

Upgrade

Version history

0.1.62latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/constructive-io/constructive ↗

packagehttps://www.npmjs.com/package/pgpm ↗

homepagehttps://pgpm.org ↗