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:

1. Start Docker Desktop
2. Wait for it to fully initialize
3. 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:

1. Ensure you're in a pgpm workspace (has pgpm.json)
2. Check module is in packages/ directory
3. Verify module has .control file

Dependency Not Found

Symptom:

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

Solution:

1. Check the referenced module exists
2. Verify the change path matches exactly
3. Check -- requires: comment syntax:

   -- requires: other_module:schemas/other/tables/table
   

Deploy Order Wrong

Symptom: Foreign key or reference errors during deployment

Solution:

1. Check pgpm.plan for correct order
2. Verify -- requires: comments in deploy files
3. 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:

1. Check pgpm version: pgpm --version
2. Check Docker status: docker ps
3. Check PostgreSQL logs: docker logs pgpm-postgres
4. 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