Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Connecting to a Sharded PostgreSQL cluster

Written by
Updated at August 14, 2025

You can connect to Managed Service for Sharded PostgreSQL cluster hosts:

  • Over the internet, if you configured public access for the appropriate host. You can only access such hosts over an SSL connection.

  • From Yandex Cloud VMs located in the same cloud network. If the host is not publicly accessible, there is no need to use SSL for connections from such virtual machines.

You can connect to all host types: INFRA, ROUTER, COORDINATOR, PostgreSQL cluster hosts. The connection is established through port 6432. In the case of COORDINATOR hosts and the Sharded PostgreSQL admin console, you must connect as the spqr-console user to the spqr-console database. You can use the admin console to configure sharding rules. For more information, see the SPQR documentation.

Configuring security groups

To connect to a cluster, security groups must include rules allowing traffic from certain ports, IP addresses, or from other security groups.

Rule settings depend on the connection method you select:

Configure all the cluster security groups to allow incoming traffic on port 6432 from any IP address. To do this, create the following rule for inbound traffic:

  • Port range: 6432.
  • Protocol: TCP.
  • Source: CIDR.
  • CIDR blocks: 0.0.0.0/0.

  1. Configure all the cluster security groups to allow incoming traffic on port 6432 from the security group where the VM is located. To do this, create the following rule for incoming traffic in these groups:

    • Port range: 6432.
    • Protocol: TCP.
    • Source: Security group.
    • Security group: If your cluster and VM are in the same security group, select Current (Self). Otherwise, specify the VM security group.

  2. Configure the security group where the VM is located to enable connections to the VM and traffic between the VM and the cluster hosts.

    For example, you can set the following rules for a VM:

    • For incoming traffic:

      • Port range: 22.
      • Protocol: TCP.
      • Source: CIDR.
      • CIDR blocks: 0.0.0.0/0.

      This rule allows you to connect to a VM over SSH.

    • For outgoing traffic:

      • Port range: 0-65535.
      • Protocol: Any (Any).
      • Destination name: CIDR.
      • CIDR blocks: 0.0.0.0/0.

      This rule allows all outgoing traffic, thus enabling you not only to connect to the cluster but also to install the certificates and utilities your VM needs for the connection.

Note

You can specify more granular rules for your security groups, such as only allowing traffic within specific subnets.

You must configure security groups correctly for all subnets in which the cluster hosts will reside.

Getting an SSL certificate

Sharded PostgreSQL hosts with public access only support encrypted connections. To use them, get an SSL certificate:

mkdir -p ~/.postgresql && \
wget "https://storage.yandexcloud.net/cloud-certs/CA.pem" \
     --output-document ~/.postgresql/root.crt && \
chmod 0655 ~/.postgresql/root.crt

The certificate will be saved to the ~/.postgresql/root.crt file.

mkdir $HOME\.postgresql; curl.exe -o $HOME\.postgresql\root.crt https://storage.yandexcloud.net/cloud-certs/CA.pem

The certificate will be saved to the $HOME\.postgresql\root.crt file.

Corporate policies and antivirus software can block the download of certificates. For more information, see FAQ.

Sharded PostgreSQL host FQDN

To connect to a host, you need its fully qualified domain name (FQDN).

You can view the FQDN in the management console:

  1. Navigate to the cluster page.
  2. Navigate to Hosts.
  3. Copy the Host FQDN column value.

Connecting with Bash

Before connecting, install the following dependencies:

sudo apt update && sudo apt install --yes postgresql-client

  1. Connect to a database:

    psql "host=<host_FQDN> \
      port=6432 \
      sslmode=disable \
      dbname=<DB_name> \
      user=<username> \
      target_session_attrs=read-write"

    Where target_session_attrs defines the type of request to the host. For example, read-write enables both reading and writing. For more information, see the SPQR documentation.

    After running the command, enter the user password to complete the connection process.

  2. To check the connection, run this query:

    SELECT version();

  1. Connect to a database:

    psql "host=<host_FQDN> \
      port=6432 \
      sslmode=verify-full \
      dbname=<DB_name> \
      user=<username> \
      target_session_attrs=read-write"

    Where target_session_attrs defines the type of request to the host. For example, read-write enables both reading and writing. For more information, see the SPQR documentation.

    After running the command, enter the user password to complete the connection process.

  2. To check the connection, run this query:

    SELECT version();

Connecting from pgAdmin 4

The connection was tested for pgAdmin 4 version 9.1 on Windows 10.

You can only use pgAdmin 4 to connect to public cluster hosts using an SSL certificate.

Create a new server connection:

  1. Select Object → Register → Server....

  2. On the General tab, in the Name field, specify the name for the cluster. This name will be shown in the pgAdmin 4 interface. You can set any name.

  3. In the Connection tab, specify the connection parameters:

    • Host name/address: Host FQDN.
    • Port: 6432.
    • Maintenance database: DB you want to connect to.
    • Username: Username for connection.
    • Password: User password.

  4. In the Parameters tab:

    • Set the SSL mode parameter to verify-full.
    • Add a new Root certificate parameter and specify the path to the saved SSL certificate file in it.

  5. Click Save to save the server connection settings.

As a result, the cluster appears in the server list in the navigation menu.

Previous
Creating a cluster
Next
Updating a cluster