Skip to main content
Achromatic
Live demo
General
Troubleshooting

Database

Learn about database troubles and their solutions.

Open MarkdownFull AI corpusFeedback

Use the first database error from the server log as the starting point. Do not paste a complete DATABASE_URL into an issue or support message because it contains credentials.

The application cannot connect

Check the connection in this order:

  1. Confirm DATABASE_URL exists in the root .env file for local development or in the deployed environment's settings.
  2. Restart the development server or redeploy after changing the value.
  3. For the included local PostgreSQL service, run npm run docker:up and inspect startup failures with npm run docker:logs.
  4. For a managed database, confirm the hostname, database name, user, password and required SSL query parameters with the provider.
  5. Confirm the provider allows connections from the application environment.

Run npm run db:studio only after the connection is available. If Studio also fails, diagnose the database connection before changing application code.

Production queries are slow

Place the application and PostgreSQL database in nearby regions. Cross-region network latency is paid on every query and transaction, but the exact impact depends on the query count and provider network.

Measure a slow request in server traces or logs before changing regions. Check whether it issues repeated queries, waits for a connection or spends most of its time on one database operation. Moving regions does not fix missing indexes or an inefficient query.

A committed migration fails

Treat a production migration as a release operation:

  1. Back up data you need before applying a schema change.
  2. Confirm the deployment uses the intended DATABASE_URL without printing its value.
  3. Review the committed Prisma migration files included with the release.
  4. Confirm the database user can change the required schema objects.
  5. Run npm run db:migrate once from CI or a one-off release task.

Do not replace a failed production migration with npm run db:push. Do not delete committed migration history to make the current environment appear clean. Resolve the reported migration or schema difference and test the fix on a disposable copy first.

Follow the Prisma database guide for the development workflow used to author new migrations.