ECONNREFUSED 127.0.0.1:5432 in production

Error: connect ECONNREFUSED 127.0.0.1:5432
    errno: -111,
    code: 'ECONNREFUSED',
    syscall: 'connect',
    address: '127.0.0.1',
    port: 5432

Why it happens

127.0.0.1 (or ::1) is "this machine". Port 5432 is Postgres. Locally that is your own database. In production there is nothing listening there, so the connection is refused.

The usual reasons:

• The database URL isn't set in production. If your code passes undefined, node-postgres falls back to its defaults, and the documented default host is localhost on port 5432. So a missing variable looks exactly like this error.
• The variable is set to your local value, copied from .env.
• You run in Docker, where localhost means the container itself, not the database container next to it.

Fix it by hand

1. Check the variable on your host. On Vercel, open Settings, then Environment Variables, and confirm DATABASE_URL (or whatever your code reads) exists and has Production ticked. Other hosts have the same idea under a different name.
2. Check the code reads it. Pass the URL explicitly so a missing value is obvious:

   import pg from 'pg';
   if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL is not set');
   const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

3. Use a database production can reach. If the only database you have is on your laptop, create a hosted one and copy its connection string into the production variable.
4. In Docker Compose, use the service name as the host. If your database service is called db, the URL is postgres://user:pass@db:5432/app, not localhost.
5. Redeploy. On Vercel, changed environment variables only apply to new deployments, so the running one keeps the old value until you deploy again.
6. If the error changes to a timeout or P1001, the address is now right but the database is refusing your host. See the P1001 fix.

Stop it happening again

• Fail fast at startup when a required variable is missing, so the error names the variable instead of a port.
• Never hardcode localhost as a fallback for a database URL in code that ships.
• Keep a committed .env.example listing every variable production needs, and check it against your host before each deploy.