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

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

Your cluster will be created in approximately 20-30 seconds and the Connection info dialog will display.
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:

In your terminal, use Homebrew to install CockroachDB by running the following command:
```
$ brew install cockroachdb/tap/cockroach
```

In your terminal, download the CockroachDB binary:
```
$ curl https://binaries.cockroachdb.com/cockroach-v21.1.2.linux-amd64.tgz \
| tar -xz
```
Copy the binary into the PATH:
```
$ sudo cp -i cockroach-v21.1.2.linux-amd64/cockroach /usr/local/bin/
```

Download and extract the CockroachDB v21.1.2 archive for Windows.
Open PowerShell, navigate to the directory containing the executable, and make sure it works:
```
PS C:\cockroach-v21.1.2.windows-6.2-amd64> .\cockroach.exe version
```

Step 3. Edit your connection string

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.
Edit your connection string by replacing sslmode=verify-full&sslrootcert=<your_certs_directory>/cc-ca.crt with sslmode=require:
```
$ 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:

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

$ 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.
#

You can now run CockroachDB SQL statements:
```
> CREATE DATABASE bank;
```
```
> 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)
```
To exit the SQL shell:
```
> \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:

To create a free cluster with other configurations (e.g., a different cloud provider or region), see Create a CockroachCloud Free (beta) Cluster.
To connect to a free cluster with other options (e.g., a CA certificate or different SQL user) and connection methods (with an application or CockroachDB compatible tool), see Connect to a CockroachCloud Free (beta) Cluster.
For information about how to connect securely to your cluster (recommended), see Authentication.
To watch a video walkthrough of connecting to a cluster, see How to connect to CockroachCloud and Import Data.

Next steps: