How to Troubleshoot PostgreSQL Database Connectivity Issues

Prerequisites

To connect to your database or troubleshoot your connection, you’ll need your connection string. A database’s connection string can be found on the database’s overview page in the control panel. If you’re unable to find the connection string or aren’t sure how to use it, please read our connection guide.

Before troubleshooting connection problems, check the DigitalOcean status page for ongoing issues in your database’s region.

Anatomy of the connection string

In your PostgreSQL connection string, punctuation (excluding “-” and “.”) separates different information. Here’s a high-level breakdown of what information those segments correspond to:

PROTOCOL://USERNAME:PASSWORD@HOSTNAME:PORT/DBNAME?PARAM
  1. Protocol: The protocol field describes which type of database you’re connecting to. In this case, it should always be postgresql.

  2. Username and Password: By default your database has only one accessible user, doadmin. Ensure new users have the correct permissions.

  3. Hostname and Port: The cluster hostname is unique and tells your client computer how to reach the cluster. Then, the port tells your cluster what application you’re accessing.

  4. Database: The database field tells PostgreSQL which database you’re connecting to.

  5. Parameters: PostgreSQL supports a lot of options for customizing connections. You can include those commands in the connection string, or use the Flags version of the connection information. The only required parameter is sslmode.

Errors

Below are some common database connectivity errors you might encounter.

Connection Refused (Hostname)

psql: could not connect to server: Connection refused         
Is the server running on host "HOSTNAME" (HOSTNAME_DNS) and accepting         
TCP/IP connections on port PORT?

This error generally means one of two things:

  • You are attempting to connect from a client computer which is not allowed in your inbound sources

  • You are using the wrong PORT value

If you’ve verified that your client computer is allowed to connect and your PORT value is correct, you may have a firewall or local DNS issue.

Connection Refused (IP Address)

psql: could not connect to server: Connection refused
Is the server running on host "IP_ADDRESS" and accepting
TCP/IP connections on port PORT?

This error indicates your compter can’t find a route to the database, which means you’re using either a Private IP or the wrong IP entirely. We do not recommend using an IP address to connect to the database publicly, as that IP address may change while the database’s hostname does not.

If you are using your database’s Private IP, note that you can only connect to that IP from a Droplet on the same DigitalOcean account in the same datacenter. That Droplet must also have private networking enabled and configured.

No Such File or Directory

bash: postgresql://USERNAME:PASSWORD@HOSTNAME:PORT/DBNAME?PARAM: No such file or directory

A message like the one above indicates you didn’t add psql before the text of the connection string. If you don’t have psql installed or don’t know what it is, please refer to our PostgreSQL connection guide.

Authentication Failed

psql: FATAL:  password authentication failed for user "USERNAME"

This error means you may be connecting to the wrong database cluster or using the wrong username/password combination. If you are customizing the string, try using the Flags version which can make it easier to review changes.

Could Not Translate Hostname to Address

psql: could not translate host name "HOSTNAME" to address: Name or service not known

This error can mean one of two things:

  • There’s an error in your HOSTNAME field

  • Your client computer is unable to resolve DNS

To rule out a mistake in the spelling of the HOSTNAME, we recommend copying the connection string again and re-trying the connection.

If the HOSTNAME isn’t the problem, it’s possible your client machine is having problems with DNS resolution.

Database Does Not Exist

psql: FATAL:  database "DBNAME" does not exist

This command indicates psql couldn’t find the database name you specified. If you’re sure that database exists on your cluster, ensure you’re connecting to the right cluster.

Invalid Parameters and Values

psql: invalid URI query parameter: "PARAM"

Or

psql: invalid PARAM value: "VALUE"

Either of these errors indicates an invalid or mistyped parameter or parameter value. If this keeps happening, it may be easier to use the Flags version of the connection details to form your connection string.