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 Connection info dialog will display.

  6. Skip Step 1 (downloading the CA certificate) since we are going to connect with the less secure option sslmode=required instead.

Step 2. Install CockroachDB

If you have not done so already, install the CockroachDB binary:

  1. In your terminal, use Homebrew to install CockroachDB by running the following command:

    icon/buttons/copy
    $ brew install cockroachdb/tap/cockroach
    
  1. In your terminal, download the CockroachDB binary:

    icon/buttons/copy
    $ curl https://binaries.cockroachdb.com/cockroach-v21.1.2.linux-amd64.tgz \
    | tar -xz
    
  2. Copy the binary into the PATH:

    icon/buttons/copy
    $ sudo cp -i cockroach-v21.1.2.linux-amd64/cockroach /usr/local/bin/
    
  1. Download and extract the CockroachDB v21.1.2 archive for Windows.

  2. Open PowerShell, navigate to the directory containing the executable, and make sure it works:

    icon/buttons/copy
    PS C:\cockroach-v21.1.2.windows-6.2-amd64> .\cockroach.exe version
    

Step 3. Edit your connection string

  1. Copy the connection string provided in Step 3 of the dialog, and save it in a secure place (e.g., in a password manager) to use in the next steps (and to connect to your cluster in the future).

    Warning:

    This connection string contains your password, which will be provided only once. If you forget your password, you can reset it by going to the SQL Users page.

  2. Edit your connection string by replacing sslmode=verify-full&sslrootcert=<your_certs_directory>/cc-ca.crt with sslmode=require:

    icon/buttons/copy
    $ cockroach sql --url 'postgres://<username>:<password>@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/defaultdb?sslmode=require&options=--cluster=<cluster-name>'
    

    Your username, password, and cluster name are pre-populated for you.

Step 4. Use the built-in SQL client

You can now connect to your cluster using CockroachDB's built-in SQL client:

  1. In your terminal, run the command with the updated connection string:

    icon/buttons/copy
    $ cockroach sql --url 'postgres://<username>:<password>@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/defaultdb?sslmode=require&options=--cluster=<cluster-name>'
    

    A welcome message displays:

    #
    # Welcome to the CockroachDB SQL shell.
    # All statements must be terminated by a semicolon.
    # To exit, type: \q.
    #
    
  2. 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)
    
  3. 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