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.
In your PostgreSQL connection string, punctuation (excluding “-” and “.”) separates different information. Here’s a high-level breakdown of what information those segments correspond to:
The protocol field describes which type of database you’re connecting to. In this case, it should always be
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.
Database: The database field tells PostgreSQL which database you’re connecting to.
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
Below are some common database connectivity errors you might encounter.
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.
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.
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.
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.
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.
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.
psql: invalid URI query parameter: "PARAM"
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.