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.
CockroachCloud Free is currently in beta. For information about its limitations, see CockroachCloud Free (beta) FAQs.
To run CockroachDB on your local machine instead, see Start a Local Cluster.
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 the Free Plan.Note:
This cluster will be free forever.
(Optional) Select a cloud provider (GCP or AWS) in the Additional configuration section.
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 dialog displays. Use the information provided in the dialog to set up your cluster connection for the SQL user that was created by default:
- Click the name of the
cc-ca.crtto download the CA certificate to your local machine.
certsdirectory on your local machine:
$ mkdir certs
Move the downloaded
cc-ca.crtfile to the
$ mv <path>/<to>/cc-ca.crt <path>/<to>/certs
$ mv Users/maxroach/Downloads/cc-ca.crt Users/maxroach/certs
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:
If you have not done so already, download the CockroachDB binary:
$ curl https://binaries.cockroachdb.com/cockroach-v20.2.5.darwin-10.9-amd64.tgz \ | tar -xJNote:
You can also use Homebrew to install the CockroachDB binary by running
brew install cockroachdb/tap/cockroach.
$ wget -qO- https://binaries.cockroachdb.com/cockroach-v20.2.5.linux-amd64.tgz \ | tar xvz
Copy the binary into the
PATHso it's easy to run the SQL client from any location:
$ cp -i cockroach-v20.2.5.darwin-10.9-amd64/cockroach /usr/local/bin/Note:
If you used Homebrew, Homebrew will automatically add the CockroachDB binary to your path.
$ sudo cp -i cockroach-v20.2.5.linux-amd64/cockroach /usr/local/bin/
In your terminal, connect to your cluster using the connection string:
$ 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 dialog, your username, password, and cluster name are pre-populated. Replace the
<certs_dir>placeholder with the path to the
certsdirectory that you created in Step 2. For example:
$ cockroach sql --url 'postgres://maxroach:email@example.com:26257/test-cluster.defaultdb?sslmode=verify-full&sslrootcert=/Users/maxroach/certs/cc-ca.crt'
> 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:
- Use the built-in SQL client to connect to your cluster and learn CockroachDB SQL.
- Create and manage SQL users.
- Build a "Hello World" app with the Django framework, or install a client driver for your favorite language.
- Explore our sample apps for examples on how to build simple "Hello World" applications using CockroachCloud Free (beta).