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

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

curl https://binaries.cockroachdb.com/cockroach-v21.1.9.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v21.1.9.linux-amd64/cockroach /usr/local/bin/

$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.9.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Path cockroach.zip; Copy-Item "cockroach/cockroach-v21.1.9.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:

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.

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.

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 5. Use the built-in SQL client

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.

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>'

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>'

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>"

Enter the SQL user's password and hit enter.

Warning:

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.
#
```
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: