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 CockroachDB Serverless (beta) 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 modal displays on the Step 2. Connect > Command Line subtab.

  3. (Optional) To configure your connection information, click Go Back:

    • Select the SQL User you want to connect with.
    • Select the Database you want to connect to.
    • Click Next.
  4. Select a connection method (the instructions in Step 2 below will adjust accordingly):

Step 2. Connect to your cluster

Warning:

We have updated the CA certificate used by CockroachDB Serverless (beta) clusters. If you downloaded this certificate prior to June 17, 2021, you must download the updated certificate by September 30, 2021 to avoid disruptions to your service.

To connect to your cluster with the built-in SQL client:

  1. Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.

  2. If you have not done so already, run the first command in the dialog to install the CockroachDB binary and copy it into the PATH:

    icon/buttons/copy

    curl https://binaries.cockroachdb.com/cockroach-v21.2.0.darwin-10.9-amd64.tgz | tar -xJ && cp -i cockroach-v21.2.0.darwin-10.9-amd64/cockroach /usr/local/bin/
    

    icon/buttons/copy
    curl https://binaries.cockroachdb.com/cockroach-v21.2.0.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v21.2.0.linux-amd64/cockroach /usr/local/bin/
    
    icon/buttons/copy
    $ErrorActionPreference = "Stop"; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;$ProgressPreference = 'SilentlyContinue'; $null = New-Item -Type Directory -Force $env:appdata/cockroach; Invoke-WebRequest -Uri https://binaries.cockroachdb.com/cockroach-v21.2.0.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Force -Path cockroach.zip; Copy-Item -Force "cockroach/cockroach-v21.2.0.windows-6.2-amd64/cockroach.exe" -Destination $env:appdata/cockroach; $Env:PATH += ";$env:appdata/cockroach"
    

    We recommend adding ;$env:appdata/cockroach to the PATH variable for your system environment so you can run cockroach commands from any shell. See Microsoft's environment variable documentation for more information.

  3. In your terminal, run the second command from the dialog to create a new certs directory on your local machine and download the CA certificate to that directory:

    icon/buttons/copy

    curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/.postgres/root.crt.

    icon/buttons/copy
    curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/.postgres/root.crt.

    icon/buttons/copy
    mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata\.postgresql\root.crt
    

    Your cert file will be downloaded to %APPDATA%/.postgres/root.crt.

  4. 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):

    icon/buttons/copy

    cockroach sql --url 'postgresql://<username>:<password>@<serverless-host>:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
    

    icon/buttons/copy
    cockroach sql --url 'postgresql://<username>:<password>@<serverless-host>:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
    
    icon/buttons/copy
    cockroach sql --url "postgresql://<username>:<password>@<serverless-host>:26257/defaultdb?sslmode=verify-full&sslrootcert=$env:appdata/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>"
    

    Where:

    • <username> is the SQL user. By default, this is your CockroachDB Cloud account username.
    • <password> is the password for the SQL user. The password will be shown only once in the Connection info dialog after creating the cluster.
    • <serverless-host> is the hostname of the CockroachDB Serverless (beta) cluster.
    • <cluster-name>-<tenant-id> is the short name of your cluster plus the tenant ID. For example, funny-skunk-123. The <tenant-id> is used to identify your tenant cluster on a multitenant host.
    • <cluster-id> is a unique string used to identify your cluster when downloading the CA certificate. For example, 12a3bcde-4fa5-6789-1234-56bc7890d123.

    You can find these settings in the Connection parameters tab of the Connection info dialog.

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

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

To connect to your cluster with your application, use the connection string provided in the Console:

  1. Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.

  2. In your terminal, run the first command from the dialog to create a new certs directory on your local machine and download the CA certificate to that directory:

    icon/buttons/copy

    curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/.postgres/root.crt.

    icon/buttons/copy
    curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/.postgres/root.crt.

    icon/buttons/copy
    mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata\.postgresql\root.crt
    

    Your cert file will be downloaded to %APPDATA%/.postgres/root.crt.

  3. Copy the connection string provided in the Connect modal, which will be used to connect your application to CockroachDB Serverless (beta):

    icon/buttons/copy
    'postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
    
    icon/buttons/copy
    'postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
    
    icon/buttons/copy
    "postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=$env:appdata/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>"
    
  4. Add your copied connection string to your application code.

    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:

To connect to your cluster with a CockroachDB-compatible tool, use the connection parameters provided in the Console.

Note:

For most tools, the full name of your database should be in the format <cluster-name>-<tenant-id>.<database>.

What's next

YesYes NoNo