Connect to a CockroachDB Serverless (beta) Cluster

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

Note:

CockroachDB Serverless is currently in beta. For information about its limitations, see the Serverless FAQs.

Before you start

Step 1. Select a connection method

  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.

Step 2. Connect to your cluster

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

  1. In the Download CA Cert section of the dialog, select your operating system, and use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. 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 (beta).
  3. Add your copied connection string to your application code. For information about connecting to CockroachDB Serverless (beta) 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, a Console Admin 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, select your operating system, and use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. Select the Parameters only option of the Select option dropdown.

  3. 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.
    {routing-id} Your cluster's routing ID (e.g., funky-skunk-123). The routing ID identifies your tenant cluster on a multi-tenant host.

  1. In the Download CA Cert section of the dialog, select your operating system, and use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. In the Download the latest CockroachDB Client section of the dialog, select your operating system, and use the command provided to install CockroachDB.
  3. Copy the cockroach sql command and connection string provided in the Connect modal, which will be used in the next step (and to connect to your cluster in the future).
  4. In your terminal, enter the copied cockroach sql command and connection string to start the built-in SQL client.

  5. 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

YesYes NoNo