PostgreSQL Package Manager CLI

Common errors

• Error: Database connection refused.

  cause 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'.

  cause 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.

  cause 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.

  cause 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.

Warnings

• breaking Major 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.
• gotcha When 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.
• breaking The 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.
• gotcha Direct 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.

Install

• npm install pgpm npm
• yarn add pgpm yarn
• pnpm add pgpm pnpm

Imports

• 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.

Quickstart

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!")