How to fix P1001: Can't reach database server at `localhost`:`5432` in Prisma

Check your .env file and ensure the DATABASE_URL follows the correct format for your database provider:

PostgreSQL:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"

MySQL:

DATABASE_URL="mysql://USER:PASSWORD@HOST:PORT/DATABASE"

MongoDB:

DATABASE_URL="mongodb+srv://USER:PASSWORD@HOST/DATABASE?retryWrites=true&w=majority"

Important: URL-encode special characters in passwords. For example, p@ssw0rd! becomes p%40ssw0rd%21.

Before troubleshooting Prisma, verify you can connect to the database using a database client or CLI:

PostgreSQL:

psql -h HOST -p PORT -U USER -d DATABASE

MySQL:

mysql -h HOST -P PORT -u USER -p DATABASE

If the direct connection fails, the issue is with your database server or network, not Prisma.

Serverless databases like Neon may need extra time to wake from idle state. Add connection timeout parameters to your DATABASE_URL:

DATABASE_URL="postgresql://user:pass@host:5432/db?connect_timeout=30&pool_timeout=30"

For production environments, consider these additional parameters:

DATABASE_URL="postgresql://user:pass@host:5432/db?connect_timeout=30&pool_timeout=30&connection_limit=5"

This gives the database 30 seconds to respond instead of the default 10 seconds.

Ensure your database server is running:

For local PostgreSQL:

# macOS
brew services list | grep postgresql

# Linux
sudo systemctl status postgresql

For local MySQL:

# macOS
brew services list | grep mysql

# Linux
sudo systemctl status mysql

For cloud providers: Check your database dashboard (Railway, Render, Supabase, etc.) to verify the instance is active.

Check that your database port is accessible:

# Test connectivity to database port
nc -zv HOST PORT

# Example for PostgreSQL
nc -zv localhost 5432

For cloud databases:
- Add your application's IP address to the database firewall allowlist
- For Vercel/serverless: Enable static IP and configure your database to allow those IPs
- For AWS RDS: Check security group inbound rules allow port 5432 (PostgreSQL) or 3306 (MySQL)
- For Railway/Render: Ensure the database is set to accept external connections

Many cloud database providers require SSL connections. Add the sslmode parameter:

PostgreSQL (Supabase, Neon, Railway):

DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"

MySQL with SSL:

DATABASE_URL="mysql://user:pass@host:3306/db?ssl=true"

Some providers may need sslmode=no-verify for development, but use sslmode=require or sslmode=verify-full in production.

If your password contains special characters and URL encoding doesn't work:

1. Reset your database password to use only alphanumeric characters (letters and numbers)
2. Update the password in your cloud provider's dashboard
3. Update your .env file with the new password
4. Test the connection again

This is particularly common with Supabase and other hosted databases.