Running PostgreSQL in Docker with prorm

Running PostgreSQL in Docker with prorm A container is the fastest way to get a throwaway PostgreSQL for integration tests or local development: no system package, no leftover cluster, and you can destroy it when you are done. This guide starts postgres:16-alpine, waits for it to accept connections, and connects prorm to it. Start the container The repository already ships this service. If you only want the databases the test suite uses, prefer the compose file: wait blocks until every service reports healthy, which is what you want in CI — see Waiting for readiness. Waiting for readiness The container accepts TCP connections a moment before PostgreSQL is ready to serve queries, so connecting immediately after docker run fails intermittently. Poll pgisready instead of sleeping a fixed number of seconds: The compose file encodes the same check as a healthcheck, which is why wait is reliable. Connect prorm to it A worked example JSONB round-trips as a parsed value on every dialect as of 2.0.0. See Data types. Extensions The dev compose file (docker-compose.yml) enables uuid-ossp, pgtrgm, pgcron, citext and pgcrypto. To add one by hand: Data persistence The compose services mount tmpfs at /var/lib/postgresql/data, so the data lives in RAM and vanishes on teardown. That is deliberate — tests should start from a clean slate and it is considerably faster. For data that must survive a restart, use a named volume instead: Tear down Troubleshooting Symptom | Cause | --- | --- | ECONNREFUSED 127.0.0.1:5432 | The container is still starting. Poll pgisready rather than sleeping. | port is already allocated | Something else holds 5432 — a system PostgreSQL, or a previous container. docker ps -a, then remove it or publish a different host port. | password authentication failed | The env vars only apply on first start. If you changed them, the old volume still has the old credentials; remove the volume. | Connects but every query is slow | tmpfs not in use and the host disk is the bottleneck; or the container is memory-starved. | Related reading PostgreSQL dialect Connection pooling Data types