PGPM Troubleshooting

Quick fixes for common pgpm, PostgreSQL, and testing issues.

When to Apply

Use this skill when encountering:

• Connection errors to PostgreSQL

• Docker-related issues

• Environment variable problems

• Transaction aborted errors in tests

• Deployment failures

PostgreSQL Connection Issues

Docker Not Running

Symptom:

Cannot connect to the Docker daemon

Solution:

• Start Docker Desktop

• Wait for it to fully initialize

• Then run pgpm commands

PostgreSQL Not Accepting Connections

Symptom:

psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed

Solution:

Start PostgreSQL container

pgpm docker start

Load environment variables

eval "$(pgpm env)"

Verify connection

psql -c "SELECT version();"

Wrong Port or Host

Symptom:

connection refused

Solution:

Check current environment

echo $PGHOST $PGPORT

Reload environment

eval "$(pgpm env)"

Verify settings

pgpm env

Environment Variable Issues

PGHOST Not Set

Symptom:

PGHOST not set

or

could not connect to server: No such file or directory

Solution:

Load pgpm environment

eval "$(pgpm env)"

Permanent fix - add to shell config:

Add to ~/.bashrc or ~/.zshrc

eval "$(pgpm env)"

Environment Not Persisting

Symptom: Environment variables reset after each command

Cause: Running eval $(pgpm env) in a subshell or script

Solution: Run in current shell:

Correct - runs in current shell

eval "$(pgpm env)"

Wrong - runs in subshell

bash -c 'eval "$(pgpm env)"'

Testing Issues

Tests Fail to Connect

Symptom: Tests time out or fail with connection errors

Solution:

1. Start PostgreSQL

pgpm docker start

2. Load environment

eval "$(pgpm env)"

3. Bootstrap users (run once)

pgpm admin-users bootstrap --yes

4. Run tests

pnpm test

Current Transaction Is Aborted

Symptom:

current transaction is aborted, commands ignored until end of transaction block

Cause: An error occurred in the transaction, and PostgreSQL marks the entire transaction as aborted. All subsequent queries fail until the transaction ends.

Solution: Use savepoints when testing operations that should fail:

// Before the expected failure const point = 'my_savepoint'; await db.savepoint(point);

// Operation that should fail await expect( db.query('INSERT INTO restricted_table ...') ).rejects.toThrow(/permission denied/);

// After the failure - rollback to savepoint await db.rollback(point);

// Now you can continue using the connection const result = await db.query('SELECT 1');

Pattern for multiple failures:

it('tests multiple failure scenarios', async () => { // First failure const point1 = 'first_failure'; await db.savepoint(point1); await expect(db.query('...')).rejects.toThrow(); await db.rollback(point1);

// Second failure const point2 = 'second_failure'; await db.savepoint(point2); await expect(db.query('...')).rejects.toThrow(); await db.rollback(point2);

// Continue with passing assertions const result = await db.query('SELECT 1'); expect(result.rows[0]).toBeDefined(); });

Tests Interfering with Each Other

Symptom: Tests pass individually but fail when run together

Cause: Missing or incorrect beforeEach/afterEach hooks

Solution:

beforeEach(async () => { await pg.beforeEach(); await db.beforeEach(); });

afterEach(async () => { await db.afterEach(); await pg.afterEach(); });

Deployment Issues

Module Not Found

Symptom:

Error: Module 'mymodule' not found

Solution:

• Ensure you're in a pgpm workspace (has pgpm.json )

• Check module is in packages/ directory

• Verify module has .control file

Dependency Not Found

Symptom:

Error: Change 'module:path/to/change' not found

Solution:

• Check the referenced module exists

• Verify the change path matches exactly

• Check -- requires: comment syntax: -- requires: other_module:schemas/other/tables/table

Deploy Order Wrong

Symptom: Foreign key or reference errors during deployment

Solution:

• Check pgpm.plan for correct order

• Verify -- requires: comments in deploy files

• Regenerate plan if needed: pgpm plan

Docker Issues

Container Won't Start

Symptom:

Error starting container

Solution:

Stop any existing containers

pgpm docker stop

Remove old containers

docker rm -f pgpm-postgres

Start fresh

pgpm docker start

Port Already in Use

Symptom:

port 5432 is already in use

Solution:

Find what's using the port

lsof -i :5432

Either stop that process or use a different port

Edit docker-compose.yml to use different port

Volume Permission Issues

Symptom:

Permission denied on volume mount

Solution:

Remove old volumes

docker volume rm pgpm_data

Restart

pgpm docker start

Quick Reference

Issue Quick Fix

Can't connect pgpm docker start && eval "$(pgpm env)"

PGHOST not set eval "$(pgpm env)"

Transaction aborted Use savepoint pattern

Tests interfere Check beforeEach/afterEach hooks

Module not found Verify workspace structure

Port in use lsof -i :5432 then stop conflicting process

Getting Help

If issues persist:

• Check pgpm version: pgpm --version

• Check Docker status: docker ps

• Check PostgreSQL logs: docker logs pgpm-postgres

• Verify environment: pgpm env

References

• Related skill: pgpm-docker for Docker management

• Related skill: pgpm-env for environment configuration

• Related skill: pgsql-test-exceptions for transaction handling