Quickstart with CockroachDB Advanced

This page shows you how to deploy a CockroachDB cluster on CockroachDB Advanced (free for a 30-day trial for your first cluster), connect to it using a sample workload, and run your first query.

To run CockroachDB on your local machine instead, see Start a Local Cluster.

Step 1. Create a free trial cluster

For this tutorial, you will create a 3-node GCP cluster in the us-west2 region.

1. If you haven't already, sign up for a CockroachDB Cloud account.
2. Log in to your CockroachDB Cloud account.
3. On the Overview page, click Create cluster.
4. On the Create Cluster page, select Advanced.
5. For Cloud provider, select Google Cloud.

6. For Regions & nodes, select California (us-west) region and 3 nodes.

   Note:

   To create a multi-region trial cluster, you can select 3 regions with 3 nodes per region, 9 nodes in total.

7. For VPC Peering, use the default selection of Use the default IP range. Click Next: Capacity.

8. On the Capacity page, select 4 vCPU for Compute per node and a 35 GiB disk for Storage per node.

   Note:

   You can select up to 9 nodes, 4 vCPUs of compute, and 150 GiB of storage. The trial code will not apply to larger clusters.

9. Click Next: Finalize.

10. On the Finalize page, enter your credit card details.

    Note:

    You will not be charged until after your free trial expires in 30 days.

11. Name the cluster. The cluster name must be 6-20 characters in length, and can include lowercase letters, numbers, and dashes (but no leading or trailing dashes).

12. Click Create cluster.

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

Once your cluster is created, you will be redirected to the Cluster Overview page.

Step 2. Create a SQL user

1. In the left navigation bar, click SQL Users.
2. Click Add User. The Add User dialog displays.
3. Enter a username and click Generate & Save Password.
4. Copy the generated password to a secure location, such as a password manager.
5. Click Close.

Step 3. Authorize your network

1. In the left navigation bar, click Networking.
2. Click Add Network. The Add Network dialog displays.
3. From the Network dropdown, select Current Network to auto-populate your local machine's IP address.
4. To allow the network to access the cluster's DB Console and to use the CockroachDB client to access the databases, select the DB Console to monitor the cluster and CockroachDB Client to access the databases checkboxes.
5. Click Apply.

Step 4. Connect to the cluster

To download CockroachDB locally and configure it to connect to the cluster with the SQL user you just created, refer to Connect to a CockroachDB Advanced cluster. Make a note of the cockroach sql command provided in the Connect dialog.

Step 5. Use the built-in SQL client

1. In your terminal, use the cockroach sql command from Step 4. Connect to the cluster to connect to the cluster using the binary you just configured.

   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 for the cluster, found at https://cockroachlabs.cloud/cluster/<CLUSTER ID>/users.

   cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
   

   cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
   

   cockroach sql --url "postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert=$env:appdata\CockroachCloud\certs\$<cluster-name>-ca.crt"
   

   Where:

   • <user> is the SQL user. By default, this is your CockroachDB Cloud account username.
   • <cluster-name>-<short-id> is the short name of your cluster plus the short ID. For example, funny-skunk-3ab.
   • <cluster-id> is a unique string used to identify your cluster when downloading the CA certificate. For example, 12a3bcde-4fa5-6789-1234-56bc7890d123.
   • <region> is the region in which your cluster is running. If you have a multi-region cluster, you can choose any of the regions in which your cluster is running. For example, aws-us-east-1.
   • <database> is the name for your database. For example, defaultdb.

   You can find these settings in the Connection parameters tab of the Connection info dialog.

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

3. 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)
   

4. To exit the SQL shell:

   > \q
   

What's next?

Learn more:

• Use the built-in SQL client to connect to your cluster and learn CockroachDB SQL.
• Build a "Hello World" app with the Django framework, or install a client driver for your favorite language.
• Use a local cluster to explore CockroachDB capabilities like fault tolerance and automated repair.

Before you move into production:

• Authorize the network from which your app will access the cluster.
• Configure every machine from which you want to connect to the cluster.
• Review the production checklist.