Skip to main content

Database and Redis

Symptoms​

Prisma cannot connect, migrate deploy fails, or Bull workers log Redis connection errors. The API may exit if boot validation or the first query fails.

Likely causes​

  • Host DATABASE_URL points at the wrong port. Inside Compose the URL is rewritten to PgBouncer. On the host you use the published Postgres port from .env.
  • Migrations were run through PgBouncer. Use DIRECT_DATABASE_URL.
  • Shadow database missing pgvector while authoring a migration.
  • REDIS_URL not set. Local default cited in the workflow notes is redis://localhost:6379 when you are not using Compose DNS.

How to investigate​

  • docker compose ps for Postgres, PgBouncer, and Redis.
  • yarn prisma:studio only after generate and a working direct URL.
  • Worker and API logs for ECONNREFUSED.

Useful commands​

docker compose up -d
yarn prisma:generate
yarn migrate:deploy

Resolution​

Fix the URL, start Redis, and migrate with the direct URL. Do not point the app at the shadow database.

Unknown​

Backup and restore steps beyond Compose comments that mention pgBackRest and WAL. Whether that backup is live was not confirmed.