PGPM Docker
Manage PostgreSQL Docker containers for local development using the pgpm docker command.
When to Apply
Use this skill when:
- Setting up a local PostgreSQL database for development
- Starting or stopping PostgreSQL containers
- Recreating a fresh database container
- User asks to run tests that need a database
- Troubleshooting database connection issues
Quick Start
Start PostgreSQL Container
pgpm docker startThis starts a PostgreSQL 17 container with default settings:
- Container name:
postgres - Port:
5432 - User:
postgres - Password:
password
Start with Custom Options
pgpm docker start --port 5433 --name my-postgresRecreate Container (Fresh Database)
pgpm docker start --recreateStop Container
pgpm docker stopCommand Reference
pgpm docker start
Start a PostgreSQL Docker container.
| Option | Description | Default |
|---|---|---|
--name <name> | Container name | postgres |
--image <image> | Docker image | pyramation/postgres:17 |
--port <port> | Host port mapping | 5432 |
--user <user> | PostgreSQL user | postgres |
--password <pass> | PostgreSQL password | password |
--recreate | Remove and recreate container | false |
pgpm docker stop
Stop a running PostgreSQL container.
| Option | Description | Default |
|---|---|---|
--name <name> | Container name to stop | postgres |
Common Workflows
Development Setup
# Start fresh database
pgpm docker start --recreate
# Load environment variables
eval "$(pgpm env)"
# Deploy your PGPM modules
pgpm deployRunning Tests
# Ensure database is running
pgpm docker start
# Run tests with environment
pgpm env pnpm testMultiple Databases
# Start main database on default port
pgpm docker start --name main-db
# Start test database on different port
pgpm docker start --name test-db --port 5433PostgreSQL Version
The default image pyramation/postgres:17 includes PostgreSQL 17 which is required for:
security_invokerviews- Latest PostgreSQL features used by Constructive
If you see errors like "unrecognized parameter security_invoker", ensure you're using PostgreSQL 17+.
Troubleshooting
| Issue | Solution |
|---|---|
| "Docker is not installed" | Install Docker Desktop or Docker Engine |
| "Port already in use" | Use --port to specify a different port, or stop the conflicting container |
| Container won't start | Check docker logs postgres for errors |
| "Container already exists" | Use --recreate to remove and recreate |
| Permission denied | Ensure Docker daemon is running and user has permissions |
Environment Variables
After starting the container, use pgpm env to set up environment variables:
eval "$(pgpm env)"This sets:
PGHOST=localhostPGPORT=5432PGUSER=postgresPGPASSWORD=passwordPGDATABASE=postgres
References
For related skills:
- Environment management: See
pgpm-envskill - Running tests: See
pgpm-testingskill