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 privilege to bypass row security
How to fix "insufficient privilege to bypass row security" in PostgreSQL
HV004: fdw_invalid_data_type
How to fix "HV004: fdw_invalid_data_type" in PostgreSQL
insufficient 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