PostgreSQL connection refused error occurs when a client cannot establish a connection to the database server. This typically happens when the server is not running, not listening on the expected port, or has firewall/network restrictions.
This error indicates that your PostgreSQL client cannot establish a TCP/IP or Unix socket connection to the PostgreSQL server. The "Connection refused" message specifically means the server is not listening on the port/socket you're trying to connect to. This is different from authentication failures—the server isn't even accepting the connection attempt.
On Linux/macOS, verify the PostgreSQL service status:
sudo systemctl status postgresqlOn macOS with Homebrew:
brew services listIf the service is inactive or not running, start it:
sudo systemctl start postgresqlOr with Homebrew:
brew services start postgresql@15Verify the process is listening on port 5432:
sudo lsof -i :5432
# or
sudo netstat -ltnp | grep postgresCheck your connection string parameters. The default PostgreSQL port is 5432.
If connecting locally, try these approaches:
# Using socket (fastest for local connections)
psql -U postgres
# Explicitly using localhost
psql -h localhost -U postgres
# Using IP address
psql -h 127.0.0.1 -U postgres
# Specifying port
psql -h localhost -p 5432 -U postgresIf your connection string has hostname/port mismatches, update your application config.
PostgreSQL must be configured to listen on the address you're connecting to. Edit the PostgreSQL configuration file (typically at /etc/postgresql/15/main/postgresql.conf on Linux):
sudo nano /etc/postgresql/15/main/postgresql.confFind the listen_addresses parameter:
# For local connections only:
listen_addresses = 'localhost'
# For all interfaces (less secure, use with firewall):
listen_addresses = '*'
# For specific IP:
listen_addresses = '192.168.1.5'After editing, reload the configuration:
sudo systemctl reload postgresqlVerify it's listening on the correct address:
sudo netstat -ltnp | grep postgresThe pg_hba.conf file controls which hosts can connect. It's usually at /etc/postgresql/15/main/pg_hba.conf.
Open it:
sudo nano /etc/postgresql/15/main/pg_hba.confAdd rules for your connection. For example:
# For local socket connections (most common)
local all all trust
# For localhost connections
host all all 127.0.0.1/32 md5
# For remote connections from specific IP
host all all 192.168.1.0/24 md5
# For all remote connections (less secure)
host all all 0.0.0.0/0 md5After changes, reload PostgreSQL:
sudo systemctl reload postgresqlIf connecting remotely, verify your firewall allows port 5432.
On Linux with UFW:
sudo ufw status
sudo ufw allow 5432/tcpOn Linux with iptables:
sudo iptables -L -n | grep 5432
sudo iptables -A INPUT -p tcp --dport 5432 -j ACCEPTIf using AWS/cloud providers, check security groups and network ACLs to ensure port 5432 is open.
Test connectivity from client:
telnet hostname 5432
nc -zv hostname 5432Verify port 5432 isn't already in use by another PostgreSQL instance or process:
sudo lsof -i :5432
sudo netstat -ltnp | grep 5432If another PostgreSQL instance is running, decide which one to keep and stop the other:
sudo systemctl stop postgresql
# or for specific version
sudo systemctl stop postgresql@15If a different service is using port 5432, either change that service's port or change PostgreSQL's port in postgresql.conf (look for the port parameter).
Unix Socket vs TCP/IP: PostgreSQL supports both Unix domain sockets (faster, local-only) and TCP/IP connections. If you're on the same machine, using the socket (psql -U postgres without -h) is preferred. Remote connections always use TCP/IP and require proper listen_addresses configuration.
Connection Pooling: If using a connection pool (PgBouncer, pgpool2), the error may originate from the pool itself. Verify the pool's backend settings and that it can reach the PostgreSQL server.
Docker/Kubernetes: In containerized environments, the PostgreSQL service DNS name or IP must be correct. Use the service name for Kubernetes DNS (postgres.default.svc.cluster.local) or the container network IP for Docker.
Database Cluster Issues: In rare cases where none of the above works, the PostgreSQL data directory may be corrupted. Try reinitializing the cluster (this destroys existing data):
sudo rm -rf /var/lib/postgresql/15/main
sudo -u postgres /usr/lib/postgresql/15/bin/initdb -D /var/lib/postgresql/15/main
sudo systemctl start postgresqlinsufficient columns in unique constraint for partition key
How to fix "insufficient columns in unique constraint for partition key" in PostgreSQL
ERROR 42501: must be owner of table
How to fix "must be owner of table" in PostgreSQL
trigger cannot change partition destination
How to fix "Trigger cannot change partition destination" in PostgreSQL
SSL error: certificate does not match host name
SSL error: certificate does not match host name in PostgreSQL
No SSL connection
No SSL connection to PostgreSQL