Webhook Relay

localhost:5432: the PostgreSQL default port and connection fixes

5432 is the default port of PostgreSQL, so localhost:5432 is a Postgres server running on your own machine. It speaks the PostgreSQL wire protocol, not HTTP, so you connect with psql, pgAdmin, DBeaver or your app's driver rather than a browser. The classic error is connection refused ... Is the server running on host "localhost" and accepting TCP/IP connections on port 5432?, which means exactly that: nothing is accepting connections there.

What runs on port 5432

InstallTypical start command
Homebrew (macOS)brew services start postgresql@16
Postgres.app (macOS)Start from the menu bar
Linux packagessudo systemctl start postgresql
Dockerdocker run -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres
Windows installerpostgresql-x64-<version> service

Tools that speak the Postgres protocol, such as CockroachDB (26257) or a local Supabase stack (54322 by default), deliberately use other ports.

psql -h localhost -p 5432 -U postgres
# or a connection string
psql "postgresql://postgres:secret@localhost:5432/postgres"

Fix "connection refused" on localhost:5432

  1. Is it running?
    pg_isready -h localhost -p 5432

    no response means the server is down. Start it with the command for your install and read its log if it exits straight away.
  2. Socket vs TCP. psql without -h uses a Unix socket. If that works but -h localhost fails, the server isn't listening on TCP: check listen_addresses in postgresql.conf (it should include localhost).
  3. Wrong port. SHOW port; from a working session, or sudo lsof -i -P | grep postgres. Multiple Homebrew versions can each claim a port.
  4. Docker. The container needs -p 5432:5432. From another container in the same Compose project, use the service name (db:5432), not localhost.
  5. Authentication errors are progress. password authentication failed or no pg_hba.conf entry means you reached the server. Fix the credentials or the matching line in pg_hba.conf.

Find and free a busy port 5432

could not bind IPv4 address "127.0.0.1": Address already in use usually means a second Postgres: Postgres.app and Homebrew both running, or a Docker container holding the host port.

# macOS / Linux
sudo lsof -i :5432
docker ps --filter "publish=5432"
brew services list

# Windows
netstat -ano | findstr :5432

Stop the duplicate cleanly (brew services stop postgresql@16, quit Postgres.app, docker stop <container>, or stop the Windows service) rather than kill -9, which skips a clean shutdown. To run both, move one: port = 5433 in postgresql.conf, or -p 5433:5432 in Docker.

Connect from another machine (safely)

To accept LAN connections, set listen_addresses = '*' in postgresql.conf, add a pg_hba.conf line limited to your subnet (for example host all all 192.168.1.0/24 scram-sha-256), restart, and allow 5432 through the firewall only for that subnet.

For anything beyond a trusted LAN, use an SSH tunnel and leave Postgres bound to localhost:

ssh -L 5433:localhost:5432 user@db-server
psql -h localhost -p 5433 -U app

Don't put Postgres on the public internet

Internet-wide scanners probe 5432 constantly, and a weak password or a permissive pg_hba.conf is enough to lose the database. An HTTP tunnel won't carry the Postgres protocol anyway, and opening a raw TCP path is rarely the right answer. Use SSH, a VPN, or your cloud provider's private networking.

If the reason you wanted Postgres reachable is to get webhook data into it, expose the app instead of the database. Forward webhooks to a handler on localhost:

relay forward --bucket orders http://localhost:8000/webhooks

The handler validates the signature and writes to localhost:5432. Because providers retry, make inserts idempotent, for example with a unique constraint on the event ID and INSERT ... ON CONFLICT DO NOTHING.

Frequently asked questions

What is the default PostgreSQL port?

PostgreSQL listens on TCP port 5432 by default. A local server is reached at localhost:5432, for example with psql -h localhost -p 5432 -U postgres.

Why do I get connection refused on localhost port 5432?

No PostgreSQL server is accepting TCP connections on port 5432. Either the server is not running, it is listening on a different port, or listen_addresses does not include localhost. Check with pg_isready -h localhost -p 5432 and look at the server log.

Can I open localhost:5432 in a browser?

No. 5432 speaks the PostgreSQL wire protocol, not HTTP. Use a database client such as psql, pgAdmin, DBeaver or TablePlus, or your application's database driver.

How do I run two PostgreSQL servers at once?

Give the second one another port. Set port = 5433 in postgresql.conf, or with Docker publish the container's 5432 on a different host port with -p 5433:5432, then connect with -p 5433.

How do I connect to PostgreSQL on a remote server securely?

Use an SSH tunnel. Run ssh -L 5433:localhost:5432 user@server and connect your client to localhost:5433. Postgres stays bound to localhost on the server and is never exposed to the internet.

Related