RunbooksPostgres refused

Postgres connection refused

Applies to: core

Symptom

Starting pnpm --filter @hivecfm/web dev or running PrismaPrismaThe TypeScript ORM HiveCFM uses to talk to Postgres. The schema lives at packages/database/schema.prisma. against the dev database fails with:

Error: P1001: Can't reach database server at `localhost:5433`
Error: connect ECONNREFUSED 127.0.0.1:5433

Likely cause

One of three:

  1. Postgres container is not running. docker compose up -d was never issued, or the container exited.
  2. Dev-ports override missing. The default docker-compose.yml only exposes Postgres inside the hivecfm-network bridge. Port 5433 on the host is only mapped when docker-compose.dev-ports.yml is layered on top.
  3. DATABASE_URL points at the wrong port. .env.local should use localhost:5433; .env inside the Docker stack uses postgres:5432.

Fix

Confirm the container state

cd /home/ubuntu/AG-DEV/hivecfm-core
docker compose ps

Look for a hivecfm-postgres row in state running / healthy. If it is missing or exited, go to step 2. If it is running, skip to step 3.

Start Postgres with the dev-ports override

docker compose -f docker-compose.yml -f docker-compose.dev-ports.yml up -d postgres

This layers the override that maps the container’s 5432 to 127.0.0.1:5433 on the host.

Check the connection string

Open hivecfm-core/.env.local and confirm:

DATABASE_URL=postgresql://postgres:postgres@localhost:5433/hivecfm?schema=public

If you edited it to something else (wrong port, wrong host), put it back. .env (not .env.local) uses the in-network hostname postgres:5432 and is only read by containers.

Test connectivity directly

docker exec -it hivecfm-postgres pg_isready -U postgres
psql "postgresql://postgres:postgres@localhost:5433/hivecfm" -c "select 1;"

Verify

pnpm --filter @hivecfm/database db:migrate:dev   # applies migrations, exits 0
pnpm --filter @hivecfm/web dev                   # boots without P1001

Prevent

  • Always start the stack with the dev-ports override when running native dev: 
    docker compose -f docker-compose.yml -f docker-compose.dev-ports.yml up -d
  • Do not edit DATABASE_URL in .env.local away from localhost:5433 unless you actually moved Postgres elsewhere.
  • If the container keeps crashing on boot, see Docker volumes — a dirty hivecfm-postgres-data volume is the usual cause.
Build OOMHub 401