Spin Up PostgreSQL for Local Dev with Docker Compose (Copy-Paste Guide)

Docker Compose starting a local PostgreSQL instance. — Spin up Postgres locally with one command.

TL;DR: Drop these two files in your project, run docker compose up -d, and you’ve got a clean, repeatable local Postgres—optionally with pgAdmin.

The story that sparked this guide#

Last week I helped a junior engineer spin up PostgreSQL for the first time—on Windows. What should’ve been a 15‑minute setup turned into a small odyssey of installers, PATH issues (psql is not recognized), service managers, and port conflicts. Switching my brain from macOS muscle memory to the Windows way in the middle of pairing was… not fun.

That session convinced me to standardize my local Postgres setup with Docker Compose and share a copy‑paste template that works the same on macOS, Windows, and Linux. If you’ve ever bounced between OSes (or onboarded folks who do), this is for you.

Moving from OS-specific installs to a Dockerized setup — This guide was born from helping a junior engineer set up Postgres on Windows.

Why Docker for Postgres?#

Reproducible: Same version/config for everyone on the team.
Disposable: Nuke volumes to start fresh; no OS cruft.
Safe: Your machine stays clean—no competing local installs or PATH drama.

Prerequisites#

Docker Desktop (or Docker Engine + Compose V2)
A terminal. That’s it.

Project Layout#

1) `.env`#

Never commit real credentials. Use .env.local for secrets if you prefer.

2) `docker-compose.yml`#

3) (Optional) One-Time Seed Script#

Create docker/initdb/001_init.sql (runs only when the data directory is empty):

Want multiple seed files? Prefix them: 001_*.sql, 002_*.sql, …

4) Start, Stop, Reset#

5) Connect from Your App#

Node (pg Pool):

Prisma .env:

psql (local):

psql (inside container):

6) pgAdmin (Optional GUI)#

Open http://localhost:8080 and add a new server:

7) Backups & Restores#

> Tip: keep dumps out of git. Add to .gitignore:

8) Handy Makefile (Optional)#

Create a Makefile for muscle-memory shortcuts:

9) Troubleshooting#

Port already in use (bind: address already in use)
Something else is on 5432. Change POSTGRES_PORT in .env (e.g., 5433), then
```
docker compose up -d
```
Healthcheck stuck / auth errors
Double-check POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB in both .env and your connection string.
Windows: psql is not recognized
Skip local installs—use the container:
docker compose exec -u postgres db psql -d app_db
Seed script didn’t run
initdb.d scripts only run on a fresh data directory. Do a full reset: docker compose down -v && docker compose up -d.
Apple Silicon perf
postgres:16 works well. If you need smaller footprint, try postgres:16-alpine.

10) Security & Team Tips#

Don’t hardcode credentials in code—load from env.
Use different users for app vs. admin if you need stricter roles.
For teams, commit docker-compose.yml and a template .env.example, not your real .env.

.env.example

11) Nice Next Steps#

Add a migration tool (Prisma, Knex, Rails migrations, Django migrations).
Script test database spin-up for CI with Docker service containers.
Consider a devcontainer.json to auto-provision Dockerized Postgres in VS Code.

Conclusion#

Running Postgres in Docker gives you a clean, reliable local DB you can spin up, tear down, and share with teammates in seconds. The Compose file above is production-inspired (healthcheck, volumes, init scripts) but minimal enough to drop into any project.