Quickstart with CockroachCloud

This page shows you how to deploy a CockroachDB cluster on CockroachCloud (free for a 30-day trial for your first cluster), connect to it using a sample workload, and run your first query.

To run CockroachDB on your local machine instead, see Start a Local Cluster.

Before you begin

If you haven't already, sign up for a CockroachCloud account.

Step 1. Create a free trial cluster

For this tutorial, we will create a 3-node GCP cluster in the us-west2 region.

  1. Log in to your CockroachCloud account.
  2. On the Overview page, click Create Cluster.
  3. On the Create new cluster page, for Cloud provider, select Google Cloud.
  4. For Regions & nodes, use the default selection of California (us-west) region and 3 nodes.
  5. For Hardware per node, select Option 1 (2vCPU, 60 GB disk).
  6. Name the cluster. The cluster name must be 6-20 characters in length, and can include lowercase letters, numbers, and dashes (but no leading or trailing dashes).
  7. Click Next.
  8. On the Summary page, enter your credit card details.

    Note:

    You will not be charged until after your free trial expires in 30 days.

  9. Click Create cluster.

Your cluster will be created in approximately 20-30 minutes. Watch this video while you wait to get a preview of how you'll connect to your cluster.

Once your cluster is created, you will be redirected to the Cluster Overview page.

Step 2. Create a SQL user

  1. In the left navigation bar, click SQL Users.
  2. Click Add User. The Add User dialog displays.
  3. Enter a Username and Password.
  4. Click Save.

Step 3. Authorize your network

  1. In the left navigation bar, click Networking.
  2. Click Add Network. The Add Network dialog displays.
  3. From the Network dropdown, select Current Network to auto-populate your local machine's IP address.
  4. To allow the network to access the cluster's DB Console and to use the CockroachDB client to access the databases, select the DB Console to monitor the cluster and CockroachDB Client to access the databases checkboxes.
  5. Click Apply.

Step 4. Connect to your cluster

  1. In the top-right corner of the Console, click the Connect button. The Connect dialog will display.
  2. From the SQL user dropdown, select the SQL user you created in Step 2. Create a SQL user.
  3. Verify that the us-west2 GCP region and defaultdb database are selected.
  4. Click Next. The Connect tab is displayed.
  5. Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.

  6. 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"
    
  7. 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 ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.

    icon/buttons/copy
    curl --create-dirs -o ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.

    icon/buttons/copy
    mkdir -p $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt
    

    Your cert file will be downloaded to %APPDATA%/CockroachCloud/certs/<cluster-name>-ca.crt.

Step 5. Use the built-in SQL client

  1. In your terminal, run the connection string provided in the third step of the dialog to connect to CockroachDB's built-in SQL client. Your username and cluster name are pre-populated for you in the dialog.

    Warning:

    This connection string contains your password, which will be provided only once. Save it in a secure place (e.g., in a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the SQL Users page.

    icon/buttons/copy

    cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.<host>:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
    

    icon/buttons/copy
    cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.<host>:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
    
    icon/buttons/copy
    cockroach sql --url "postgresql://<user>@<cluster-name>-<short-id>.<region>.<host>:26257/<database>?sslmode=verify-full&sslrootcert=$env:appdata\CockroachCloud\certs\$<cluster-name>-ca.crt"
    
  2. 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.
    #
    
  3. You can now run CockroachDB SQL statements:

    icon/buttons/copy
    > CREATE DATABASE bank;
    
    icon/buttons/copy
    > CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);
    
    icon/buttons/copy
    > INSERT INTO bank.accounts VALUES (1, 1000.50);
    
    icon/buttons/copy
    > SELECT * FROM bank.accounts;
    
      id | balance
    -----+----------
       1 | 1000.50
    (1 row)
    
  4. To exit the SQL shell:

    icon/buttons/copy
    > \q
    

What's next?

Learn more:

Before you move into production:

YesYes NoNo