Quickstart with CockroachCloud Free (beta)

This page guides you through the quickest way to get started with CockroachDB by setting up a CockroachCloud Free (beta) cluster with the default options and minimal connection security. For information on how to create a CockroachCloud cluster with other options, see the Learn more section.

Note:

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

Step 1. Create a free cluster

  1. If you haven't already, sign up for a CockroachCloud account.
  2. Log in to your CockroachCloud account.
  3. On the Clusters page, click Create Cluster.
  4. On the Create your cluster page, select CockroachCloud Free.
  5. Click Create your free cluster.

    Your cluster will be created in approximately 20-30 seconds and the Connect dialog will display.

Step 2. Choose your OS

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

Step 3. Install CockroachDB

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"

Step 4. Download the CA certificate

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.

Step 4. 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>@<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>"
    
  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
    

Learn more

This page outlines the quickest way to get started with CockroachDB. For information on other options that are available when creating a CockroachCloud Free (beta) cluster, see the following:

Next steps:

YesYes NoNo