Connect to a CockroachDB Serverless Cluster

On this page Carat arrow pointing down

This page shows you how to connect to your CockroachDB Serverless cluster. If you'd like to follow along with a video walkthrough, see How to connect to CockroachDB Cloud and Import Data.

Before you start

Authorize your network

On creation, a Serverless cluster is open to all traffic as it is created with a 0.0.0.0/0 IP allowlist.

It is recommended to restrict your network to allow access only from specific IP address ranges controlled by your organization. These might include specific networks for your application deployments, hardened administrator access points, or backup-restore pipelines for disaster recovery. Therefore, if possible you should replace the 0.0.0.0/0 allowlist entry with more specific CIDR ranges for legitimate access.

Removing or adding an authorized network on your CockroachDB Serverless cluster may take up to 30 seconds to take effect.

Note:

IPv6 addresses are currently not supported.

To prevent denial-of-service attacks, brute force password attacks, and other forms of malicious activity, it is recommended to restrict your cluster network to allow access only from specific IP address ranges controlled by your organization, corresponding to, for example, your application deployments, hardened administrator access points, or disaster recovery pipelines.

Add IP addresses to the allowlist

  1. Navigate to your cluster's Networking > IP Allowlist tab.

    The IP Allowlist tab displays a list of authorized networks (i.e., an IP network allowlist) that can access the cluster.

  2. Check if the current network has been authorized. If not, proceed with the following steps.

  3. Click the Add Network button.

    The Add Network dialog displays.

  4. (Optional) Enter a Network name.

  5. From the Network dropdown, select:

    • New Network to authorize the network of your local machine or application deployment or another valid source. Enter the public IPv4 address of the source machine in the Network field. To add a range of source IP addresses, use the CIDR (Classless Inter-Domain Routing) notation. For a general introduction to IP routing, refer to Digital Ocean—Understanding IP Addresses, Subnets, and CIDR Notation for Networking.
    • Current Network to auto-populate your local machine's IP address.
    • Public (Insecure) to allow all networks, use 0.0.0.0/0. Use this with caution as your cluster will be vulnerable to denial-of-service and brute force password attacks.
Note:

AWS PrivateLink for CockroachDB Serverless is in limited access and is only available for multi-region CockroachDB Serverless clusters deployed on AWS. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.

Amazon Web Services (AWS) PrivateLink support allows customers to establish SQL access to their clusters entirely through private AWS infrastructure, without exposure to the public internet, affording enhanced security and performance.

To configure PrivateLink, you create the AWS PrivateLink connection in your AWS account, then configure your cluster to allow connections from your private endpoint. For more information and detailed instructions, refer to Network Authorization: AWS PrivateLink.

AWS PrivateLink can be configured only after the cluster is created. For detailed instructions, refer to Managing AWS PrivateLink for a cluster.

Note:

Private connectivity is not available for CockroachDB Serverless clusters on GCP.

Connect to your cluster

  1. Select your cluster to navigate to the cluster Overview page.

  2. In the top right corner of the CockroachDB Cloud Console, click the Connect button.

    The Connect to cluster dialog displays.

  3. (Optional) If you have multiple SQL users or databases, you can:

    • Select the SQL user you want to connect with from the SQL user dropdown.
    • Select the database you want to connect to from the Database dropdown.

  4. Select a connection method from the Select option / Language dropdown (the instructions below will adjust accordingly):

  1. In the Download CA Cert section of the dialog, you can optionally download the CA certificate. The CA certificate is signed by Let's Encrypt, which may already be trusted by your local system. However, some use cases, such as developing with Python, do not use the operating system's local certificate store and require the CA certificate to be available locally. When developing with Javascript or Node, you do not need to download the CA certificate locally. To download the CA certificate, select your operating system, then use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. If you established a private connection using AWS PrivateLink, change Connection type from Public connection to Private connection to connect privately.
  3. Copy the connection string provided in the General connection string section of the dialog, which will be used to connect your application to CockroachDB Serverless.
  4. Add your copied connection string to your application code. For information about connecting to CockroachDB Serverless with a supported client, see Connect to a CockroachDB Cluster.
Warning:

PostgreSQL connection URIs do not support special characters. If you have special characters in your password, you will have to URL encode them (e.g., password! should be entered as password%21) to connect to your cluster.

Note:

If you forget your SQL user's password, an Org Administrator or a Cluster Admin on the cluster can change the password on the SQL Users page.

For connection examples and code snippets in your language, see the following:

  1. In the Download CA Cert section of the dialog, you can optionally download the CA certificate. The CA certificate is signed by Let's Encrypt, which may already be trusted by your local system. However, some use cases, such as developing with Python, do not use the operating system's local certificate store and require the CA certificate to be available locally. When developing with Javascript or Node, you do not need to download the CA certificate locally. To download the CA certificate, select your operating system, then use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. If you established a private connection using AWS PrivateLink, change Connection type from Public connection to Private connection to connect privately.
  3. Select the Parameters only option of the Select option dropdown.

  4. Use the connection parameters provided in the dialog to connect to your cluster using a CockroachDB-compatible tool.

    Parameter Description
    {username} The SQL user connecting to the cluster.
    {password} The password for the SQL user connecting to the cluster.
    {host} The host on which the CockroachDB node is running.
    {port} The port at which the CockroachDB node is listening.
    {database} The name of the (existing) database.

You can connect to your cluster with any supported version of the full CockroachDB binary or the built-in SQL client. To download the full binary and connect to a CockroachDB Serverless cluster, follow these steps.

  1. Select CockroachDB Client from the Select option/language dropdown.
  2. In the Download CA Cert section of the dialog, you can optionally download the CA certificate. The CA certificate is signed by Let's Encrypt, which may already be trusted by your local system. However, some use cases, such as developing with Python, do not use the operating system's local certificate store and require the CA certificate to be available locally. When developing with Javascript or Node, you do not need to download the CA certificate locally. To download the CA certificate, select your operating system, then use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  3. In the Download the latest CockroachDB Client section of the dialog, select your operating system, and use the command provided to install the latest downloadable version of CockroachDB on your local system.
  4. If you established a private connection using AWS PrivateLink, change Connection type from Public connection to Private connection to connect privately.
  5. Copy the cockroach sql command and connection string provided in the Connect dialog, which will be used in the next step (and to connect to your cluster in the future).

  6. In your terminal, enter the copied cockroach sql command and connection string to start the built-in SQL client.

  7. Enter the SQL user's password and hit enter.

    Warning:

    PostgreSQL connection URIs do not support special characters. If you have special characters in your password, you will have to URL encode them (e.g., password! should be entered as password%21) to connect to your cluster.

    A welcome message displays:

    #
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#

    You are now connected to the built-in SQL client, and can now run CockroachDB SQL statements.

What's next


Yes No
On this page

Yes No

Product

Resources

Learn

Support Channels

Company

Get developer news