This page shows you how to deploy a CockroachDB cluster on CockroachCloud Free (beta), connect to it using the CockroachDB built-in SQL client, and run sample SQL statements.

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 cluster

  1. Log in to your CockroachCloud account.
  2. On the Clusters page, click Create Cluster.
  3. On the Create your cluster page, select the Free Plan.

    Note:

    This cluster will be free forever.

  4. Click Create your free cluster.

Your cluster will be created in approximately 20-30 seconds.

Step 2. Set up your cluster connection

Once your cluster is created, the Connection info modal displays. Use the information provided in the modal to set up your cluster connection for the SQL user that was created by default:

  1. Click the name of the cc-ca.crt to download the CA certificate to your local machine.
  2. Create a certs directory on your local machine:

    copy
    icon/buttons/copy
    $ mkdir certs
    
  3. Move the downloaded cc-ca.crt file to the certs directory:

    copy
    icon/buttons/copy
    $ mv <path>/<to>/cc-ca.crt <path>/<to>/certs
    

    For example:

    copy
    icon/buttons/copy
    $ mv Users/maxroach/Downloads/cc-ca.crt Users/maxroach/certs
    
  4. Copy the connection string provided, which will be used 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.

Step 3. Use the built-in SQL client

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

  1. If you have not done so already, download the CockroachDB binary:

    copy
    icon/buttons/copy
    $ curl https://binaries.cockroachdb.com/cockroach-v20.2.3.darwin-10.9-amd64.tgz \
    | tar -xJ
    
    copy
    icon/buttons/copy
    $ wget -qO- https://binaries.cockroachdb.com/cockroach-v20.2.3.linux-amd64.tgz \
    | tar  xvz
    
    copy
    icon/buttons/copy
    $ brew install cockroachdb/tap/cockroach
    
  2. Copy the binary into the PATH so it's easy to run the SQL client from any location:

    copy
    icon/buttons/copy
    $ cp -i cockroach-v20.2.3.darwin-10.9-amd64/cockroach /usr/local/bin/
    
    copy
    icon/buttons/copy
    $ sudo cp -i cockroach-v20.2.3.linux-amd64/cockroach /usr/local/bin/
    
  3. In your terminal, connect to your cluster using the connection string:

    copy
    icon/buttons/copy
    $ cockroach sql --url 'postgres://<username>:<password>@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/<cluster_name>.defaultdb?sslmode=verify-full&sslrootcert=<certs_dir>/cc-ca.crt'
    

    In the connection string copied from the Connection info modal, your username, password and cluster name are pre-populated. Replace the <certs_dir> placeholder with the path to the certs directory that you created in Step 2. For example:

    copy
    icon/buttons/copy
    $ cockroach sql --url 'postgres://maxroach:password123@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/test-cluster.defaultdb?sslmode=verify-full&sslrootcert=/Users/maxroach/certs/cc-ca.crt'
    
  4. Using the built-in SQL client, you can now run CockroachDB SQL statements:

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

    copy
    icon/buttons/copy
    > \q
    

What's next?

Learn more:



YesYes NoNo