Troubleshooting Connectivity

Check if we have a quickstart guide for your language or tool

Check for a quickstart guide in this section of the documentation.

If there is not already a guide, please reach out to Tembo Support, and we will make a guide for your client.

Checking if you can reach the Tembo Platform

• Can you get 404 from your domain name?
  • Just type the domain into browser or use curl
  • For example: org-your-org-name-inst-your-cluster-name.data-1.use1.tembo.io
  • If you get a 404, then you have network connectivity to Tembo

Tembo requires PostgreSQL clients that support Server Name Indication (SNI)

Server Name Indication was introduced in Postgres version 14, and this feature is used in Tembo to route requests to the appropriate databases. Please review the Postgres release notes for details.

Often upgrading your dependency’s version will resolve this issue. Sometimes, a Postgres client will use the underlying system’s libpq, in which case this needs to be updated.

Here’s an example of how you would install an updated PostgreSQL client on a Debian-based Linux system:

sudo apt-get update && sudo apt-get install -y lsb-release
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget -qO- https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo tee /etc/apt/trusted.gpg.d/pgdg.asc &>/dev/null
sudo apt-get update && sudo apt-get install -y postgresql-client

Here’s an example of updating psql and libpq on a Mac, using brew:

brew reinstall libpq

Tembo aims to have a simple connection guide for any client language, so please reach out to support if you don’t see your language in this list of guides.

If you want to check if you can connect to Tembo using a known, working version of a client, please use the following command. Replace the connection string with your connection string, found in the Tembo UI.

 docker run -it --rm \
    --entrypoint=psql postgres:15 \
    'postgresql://postgres:***@***.data-1.use1.tembo.io:5432'

If the above fails, you may be having problems reaching your cluster. Please check the previous section, or reach out to Tembo support.

SNI workaround

If you cannot update the Postgres client, you can use Tembo’s SNI workaround.

Certificate validation

Tembo uses self-signed certificates for databases.

Most Postgres clients by default do not verify the server’s identity using TLS, using sslmode=default. It’s better practice to connect with sslmode=verify-ca, especially when connecting over an untrusted network.

Some clients, for example Node, by default require certificate validation, checking against your system’s trust store, similar to how it works with HTTPS in the browser. In these cases, connection issues can be resolved by specifying a value for the configuration option sslrootcert, which may be named differently in each client language.

Tembo aims to have a simple connection guide for any client language, so please reach out to support if you don’t see your language in this list of guides.

Connection issues from a third party

If you are using a different service that cannot connect to Tembo Cloud, it may be because of SNI or certificate validation issues. Tembo support is happy to help, so please reach out and we will help improve the third party service to support certificate validation or SNI.

Often, a connection issue related to certificate validation can be resolved by uploading your sslrootcert to the third party.

SNI issues typically require the third party to update the version of their client libraries.

Connecting with Unix domain sockets

Some extensions connect to the database using local access. This type of connection is known as an Unix domain socket connection.

local all all peer

Unix domain socket files are not in the default path on Tembo Cloud. Instead, the files are located in the directory /controller/run, which can be found by the configuration unix_socket_directories.

If you are using an extension which requires local access, you must configure this option. When connecting to Postgres, the host option is understood as a path to the Unix domain socket when it starts with a slash.

For example, in the case of cron, the configuration cron.host can be set to /controller/run. In the case of dblink, you can connect with: dblink('dbname=sample host=/controller/run', 'SELECT 1')