Connect to a PostgreSQL TimescaleDB cluster

Last update: September 29 2026Open in Markdown

You can connect to the PostgreSQL TimescaleDB cluster:

• using the psql console client;
• using graphical database management tools: pgAdmin or an office suite with ODBC or JDBC support;
• from application code.

For all methods, connection with SSL and without SSL is available.

When connecting, specify the port and address.

Connection ports

To connect to PostgreSQL TimescaleDB, use ports:

• 5433 — port for connecting to the selected node via a connection pooler — allows you to reduce the load on PostgreSQL TimescaleDB;
• 5432 — port for connecting directly to the process of PostgreSQL TimescaleDB.

Connection addresses

You can select a connection address based on one of the following scenarios:

• connecting to a cluster in a public subnet;
• connecting from a private subnet to a cluster in a private subnet;
• connecting from the internet to a cluster in a private subnet.

You can view the connection address in the Control Panel.

Connecting to a cluster in a public subnet

If the cluster is in a public subnet, you can connect to the nodes using a DNS address or an IP address from the public subnet.

We recommend connecting via a DNS address. The cluster uses the master discovery mechanism for DNS addresses: the address is bound to the node role rather than the node itself. If the master becomes unavailable, one of the replicas becomes the new master, and the address moves to the new node along with the role.

When connecting via an IP address from a public subnet, the master discovery mechanism is not used. If one of the replicas becomes the new master, the master's IP address will change, and the connection using the old IP address will stop working.

Connecting from a private subnet to a cluster in a private subnet

If you are connecting from a private subnet to a cluster in a private subnet, you can use a DNS address or a private IP address.

We recommend connecting via a DNS address. The cluster uses the master discovery mechanism for DNS addresses: the address is bound to the node role rather than the node itself. If the master becomes unavailable, one of the replicas becomes the new master, and the address moves to the new node along with the role.

When connecting via a private IP address, the master discovery mechanism is not used. If one of the replicas becomes the new master, the master's IP address will change, and the connection using the old IP address will stop working.

To connect from another private subnet, first connect both private subnets to a cloud router.

Connecting from the Internet to a cluster in a private subnet

If you connect to a cluster in a private subnet from the internet, you can only use a public floating IP address (Floating IP).

For public floating IP addresses (Floating IPs), the master discovery mechanism is used — the address is bound to the node's role, not to the node itself. If the master becomes unavailable, one of the replicas becomes the new master, and the address moves to the new node along with the role.

View the connection address

1. In the Control panel, in the top menu, click Products and select Cloud Databases.
2. Open the Active tab.
3. Go to the database cluster page → Connection tab.
4. In the Connection addresses block, check the address.

Connect with SSL

Connecting using TLS(SSL) encryption provides a secure connection between your server and the database cluster.

Bash

1. Download the root certificate and place it in the ~/.postgresql/ folder:

   mkdir -p ~/.postgresql/
   wget https://storage.dbaas.selcloud.ru/CA.pem -O ~/.postgresql/root.crt
   chmod 0600 ~/.postgresql/root.crt

2. Connect to the cluster:

   psql "host=<host> \
         port=<port> \
         dbname=<database_name> \
         user=<database_user_name> \
         sslmode=verify-ca"

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <port> — connection port;
   • <database_name> — database name;
   • <database_user_name> — database username.

PowerShell

1. In the Control panel, click Download certificate to download the root certificate and place it in the folder %APPDATA%\postgresql\.

2. Connect to the cluster:

   psql "host=<host> `
         port=<port> `
         dbname=<database_name> `
         user=<database_user_name> `
         sslmode=verify-ca"

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <port> — connection port;
   • <database_name> — database name;
   • <database_user_name> — database username.

Python

1. Download the root certificate and place it in the ~/.postgresql/ folder:

   mkdir -p ~/.postgresql/
   wget https://storage.dbaas.selcloud.ru/CA.pem -O ~/.postgresql/root.crt
   chmod 0600 ~/.postgresql/root.crt

2. Install the psycopg2 library:

   pip3 install psycopg2-binary

3. Use the connection example:

   import psycopg2
   
   conn = psycopg2.connect("""
         host=<host>
         dbname=<database_name>
         user=<database_user_name>
         password=<password>
         sslrootcert=<path>
         sslmode=verify-ca
         port=<port>
   """)
   
   cur = conn.cursor()
   cur.execute('SELECT 40+2')
   
   print(cur.fetchone())
   
   cur.close()
   conn.close()

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <database_name> — database name;
   • <database_user_name> — database username;
   • <password> — user password;
   • <path> — full path to the root certificate;
   • <port> — connection port.

PHP

1. Download the root certificate and place it in the ~/.postgresql/ folder:

   mkdir -p ~/.postgresql/
   wget https://storage.dbaas.selcloud.ru/CA.pem -O ~/.postgresql/root.crt
   chmod 0600 ~/.postgresql/root.crt

2. Install the pgsql library:

   apt install php-pgsql

3. Use the connection example:

   <?php
   
   $dbconn = pg_connect("
         host=<host>
         dbname=<database_name>
         user=<database_user_name>
         password=<password>
         sslrootcert=<path>
         sslmode=verify-ca
         port=<port>
   ");
   
   $query = 'SELECT 40 + 2';
   $result = pg_query($query);
   $row = pg_fetch_row($result);
   
   echo $row[0];
   
   pg_close($dbconn);
   ?>

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <database_name> — database name;
   • <database_user_name> — database username;
   • <password> — user password;
   • <path> — full path to the root certificate;
   • <port> — connection port.

Go

1. Download the root certificate and place it in the ~/.postgresql/ folder:

   mkdir -p ~/.postgresql/
   wget https://storage.dbaas.selcloud.ru/CA.pem -O ~/.postgresql/root.crt
   chmod 0600 ~/.postgresql/root.crt

2. Use the connection example:

   package main
   
   import (
         "context"
         "fmt"
         "os"
   
         "github.com/jackc/pgx/v4"
   )
   
   func main() {
   
         connectionString := fmt.Sprintf("postgres://%s:%s@%s:<port>/%s?sslmode=verify-ca&sslrootcert=%s",
             "<database_user_name>",
             "<password>",
             "<host>",
             "<database_name>",
             "<path>"
         )
   
         conn, err := pgx.Connect(context.Background(), connectionString)
         if err != nil {
             fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
             os.Exit(1)
         }
         defer conn.Close(context.Background())
   
         var sum int64
         err = conn.QueryRow(context.Background(), "SELECT 40+2").Scan(&sum)
         if err != nil {
             fmt.Fprintf(os.Stderr, "QueryRow failed: %v\n", err)
             os.Exit(1)
         }
   
         fmt.Println(sum)
   }

   Specify:

   • <port> — connection port;
   • <database_user_name> — database username;
   • <password> — user password;
   • <host> — DNS address or public floating IP address of the node;
   • <database_name> — database name;
   • <path> — full path to the root certificate.

Node.js

1. Download the root certificate and place it in the ~/.postgresql/ folder:

   mkdir -p ~/.postgresql/
   wget https://storage.dbaas.selcloud.ru/CA.pem -O ~/.postgresql/root.crt
   chmod 0600 ~/.postgresql/root.crt

2. Install the pg library:

   npm install pg

3. Use the connection example:

   const fs = require('fs');
   const pg = require('pg');
   
   const config = {
       host: '<host>',
       port: '<port>',
       database: '<database_name>',
       user: '<database_user_name>',
       password: '<password>',
       ssl: {
         rejectUnauthorized: true,
         ca: fs.readFileSync('<path>').toString(),
       },
   };
   
   const client = new pg.Client(config);
   
   client.connect((error) => {
       if (error) throw error;
   });
   
   client.query('SELECT 40 + 2 AS sum', (error, res) => {
       if (error) throw error;
       console.log(res.rows);
       client.end();
   });

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <port> — connection port;
   • <database_name> — database name;
   • <database_user_name> — database username;
   • <password> — user password;
   • <path> — full path to the root certificate.

Connect without SSL

Bash

1. Open the CLI.

2. Connect to the cluster:

   psql "host=<host> \
         port=<port> \
         dbname=<database_name> \
         user=<database_user_name> \
         sslmode=disable"

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <port> — connection port;
   • <database_name> — database name;
   • <database_user_name> — database username.

PowerShell

1. Open the CLI.

2. Connect to the cluster:

   psql "host=<host> `
         port=<port> `
         dbname=<database_name> `
         user=<database_user_name> `
         sslmode=disable"

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <port> — connection port;
   • <database_name> — database name;
   • <database_user_name> — database username.

Python

1. Install the psycopg2 library:

   pip3 install psycopg2-binary

2. Use the connection example:

   import psycopg2
   
   conn = psycopg2.connect("""
         host=<host>
         dbname=<database_name>
         user=<database_user_name>
         password=<password>
         port=<port>
   """)
   
   cur = conn.cursor()
   cur.execute('SELECT 40+2')
   
   print(cur.fetchone())
   
   cur.close()
   conn.close()

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <database_name> — database name;
   • <database_user_name> — database username;
   • <password> — user password;
   • <port> — connection port.

PHP

1. Install the pgsql library:

   apt install php-pgsql

2. Use the connection example:

   <?php
   
   $dbconn = pg_connect("
         host=<host>
         dbname=<database_name>
         user=<database_user_name>
         password=<password>
         port=<port>
   ");
   
   $query = 'SELECT 40 + 2';
   $result = pg_query($query);
   $row = pg_fetch_row($result);
   
   echo $row[0];
   
   pg_close($dbconn);
   ?>

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <database_name> — database name;
   • <database_user_name> — database username;
   • <password> — user password;
   • <port> — connection port.

Go

Use the connection example:

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/jackc/pgx/v4"
)

func main() {
    connectionString := fmt.Sprintf("postgres://%s:%s@%s:<port>/%s",
        "<database_user_name>",
        "<password>",
        "<host>",
        "<database_name>",
    )

    conn, err := pgx.Connect(context.Background(), connectionString)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
        os.Exit(1)
    }
    defer conn.Close(context.Background())

    var sum int64
    err = conn.QueryRow(context.Background(), "SELECT 40+2").Scan(&sum)
    if err != nil {
        fmt.Fprintf(os.Stderr, "QueryRow failed: %v\n", err)
        os.Exit(1)
    }

    fmt.Println(sum)
}

Specify:

• <port> — connection port;
• <database_user_name> — database username;
• <password> — user password;
• <host> — DNS address or public floating IP address of the node;
• <database_name> — database name.

Node.js

1. Install the pg library:

   npm install pg

2. Use the connection example:

   const pg = require('pg');
   
   const config = {
       host: '<host>',
       port: '<port>',
       database: '<database_name>',
       user: '<database_user_name>',
       password: '<password>',
   };
   
   const client = new pg.Client(config);
   
   client.connect((error) => {
       if (error) throw error;
   });
   
   client.query('SELECT 40 + 2 AS sum', (error, res) => {
       if (error) throw error;
       console.log(res.rows);
       client.end();
   });

   Specify:

   • <host> — DNS address or public floating IP address of the node;
   • <port> — connection port;
   • <database_name> — database name;
   • <database_user_name> — database username;
   • <password> — user password.