How to Fix Database Connection Errors in Next.js Production Deployments

A production deployment can fail with a database connection error even when the application connects correctly during local development. The cause is usually the difference between a persistent local database server and the serverless execution environment on Vercel.

Problem

When deploying to Vercel, the application throws a connection error on the first database query. The same connection string works locally.

Symptoms

Error messages include ECONNREFUSED or connection refused on the database host and port.
The error occurs only in production or preview deployments, not in next dev.
The database host is reachable from the developer's machine but fails from the deployed function.

Environment

Next.js 16 (App Router)
Vercel production / preview deployment (serverless functions)
PostgreSQL 15+ or MySQL 8+ (self-hosted or managed)
Connection via process.env.DATABASE_URL

Exact Error

The error message from the database driver (e.g., pg for PostgreSQL, mysql2 for MySQL) is:

ECONNREFUSED 127.0.0.1:5432

This indicates the deployed function is attempting to connect to localhost (127.0.0.1) rather than the remote database host.

Cause

In serverless environments, the database connection must use the actual host and port configured for production. A common mistake is using .env.local values locally that are not properly set in Vercel project settings, or using localhost as the host in the production environment variable. Additionally, many managed database providers (e.g., Supabase, Render, AWS RDS) require SSL (sslmode=require or equivalent) in production, which local configurations often omit. Verify the provider's documentation for the exact parameter.

Diagnosis

Check the production environment variables in the Vercel dashboard. Confirm DATABASE_URL points to the external database host (not localhost or 127.0.0.1). Verify the database provider's connection requirements: many managed providers require sslmode=require or ?ssl=true in production.

Check the Vercel function logs for the exact connection attempt. If the logs show a connection to an IP that is not the database host, the environment variable is misconfigured.

Solution

Update the production environment variable in Vercel project settings:

Set DATABASE_URL to the full connection string with the external host, port, credentials, and SSL parameters required by the provider.
For PostgreSQL, include sslmode=require when required by the provider.
For Prisma, ensure the connection string uses the production URL and that any SSL mode is set in the provider-specific format (e.g., ?sslmode=require for some providers, or ssl=true for others — check the provider documentation).
Redeploy and check the function logs for a successful connection.

Verification

After redeploying, trigger the database query from a production endpoint. Confirm the response returns the expected data without connection errors. Check Vercel function logs to confirm no ECONNREFUSED errors.

Common Mistakes

Using localhost or 127.0.0.1 in the production DATABASE_URL.
Omitting SSL parameters when the managed database requires them.
Copying .env.local directly to Vercel settings without changing the host.
Not redeploying after changing environment variables (Vercel requires a redeploy for environment changes to take effect in serverless functions).

Related Issues

This error shares a root cause with other production-only failures: differences between local persistent servers and serverless execution environments. See Next.js build failures for production build failures, and Docker restart loops for container-level connection issues.