Quickstart with CockroachDB Dedicated

This page shows you how to deploy a CockroachDB cluster on CockroachDB Dedicated (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.

Step 1. Create a free trial cluster

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

  1. If you haven't already, sign up for a CockroachDB Cloud account.
  2. Log in to your CockroachDB Cloud account.
  3. On the Overview page, click Create Cluster.
  4. On the Create new cluster page, for Cloud provider, select Google Cloud.
  5. For Regions & nodes, use the default selection of California (us-west) region and 3 nodes.
  6. Under Hardware per node, select 2vCPU for Compute and a 35 GiB disk for Storage.


    You can select up to 9 nodes, 4 vCPUs of compute, and 150 GiB of storage. The trial code will not apply to larger clusters.

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

  8. Click Next.

  9. On the Summary page, enter your credit card details.


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

  10. 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:


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

    curl https://binaries.cockroachdb.com/cockroach-v21.2.10.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v21.2.10.linux-amd64/cockroach /usr/local/bin/
    $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.10.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Force -Path cockroach.zip; Copy-Item -Force "cockroach/cockroach-v21.2.10.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.

  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.


    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.

    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.

    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.


    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.


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

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


    • <user> is the SQL user. By default, this is your CockroachDB Cloud account username.
    • <cluster-name>-<short-id> is the short name of your cluster plus the short ID. For example, funny-skunk-3ab.
    • <cluster-id> is a unique string used to identify your cluster when downloading the CA certificate. For example, 12a3bcde-4fa5-6789-1234-56bc7890d123.
    • <region> is the region in which your cluster is running. If you have a multi-region cluster, you can choose any of the regions in which your cluster is running. For example, aws-us-east-1.
    • <database> is the name for your database. For example, defaultdb.

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

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


    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.
  3. You can now run CockroachDB SQL statements:

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

    > \q

What's next?

Learn more:

Before you move into production:

YesYes NoNo