Connect to a CockroachCloud Free (beta) Cluster

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

Note:

CockroachCloud Free is currently in beta. For information about its limitations, see CockroachCloud Free (beta) FAQs.

Before you start

Step 1. Select a connection method

  1. In the top right corner of the CockroachCloud Console, click the Connect button.

    The Connect modal displays on the Step 2. Connect > Command Line subtab.

  2. (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.
  3. Select a connection method (the instructions in Step 2 below will adjust accordingly):

Step 2. Connect to your cluster

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.1.6.darwin-10.9-amd64.tgz | tar -xJ && cp -i cockroach-v21.1.6.darwin-10.9-amd64/cockroach /usr/local/bin/
    

    icon/buttons/copy
    curl https://binaries.cockroachdb.com/cockroach-v21.1.6.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v21.1.6.linux-amd64/cockroach /usr/local/bin/
    
    icon/buttons/copy
    $ErrorActionPreference = "Stop"; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; $ProgressPreference = 'SilentlyContinue'; mkdir -p $env:appdata/cockroach; Invoke-WebRequest -Uri https://binaries.cockroachdb.com/cockroach-v21.1.6.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Path cockroach.zip; Copy-Item cockroach/cockroach-v21.1.6.windows-6.2-amd64/cockroach.exe -Destination $env:appdata/cockroach; $Env:PATH += ";$env:appdata/cockroach"
    
  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://<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
    cockroach sql --url '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
    cockroach sql --url "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>"
    
  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.

    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 CockroachCloud Free (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.

    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