Quickstart with CockroachDB Dedicated

On this page

This page shows you how to deploy a CockroachDB cluster on CockroachDB Dedicated (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.

If you haven't already, sign up for a CockroachDB Cloud account.
Log in to your CockroachDB Cloud account.
On the Overview page, click Create Cluster.
On the Create Cluster page, select Dedicated standard.

Note:

Free trials do not apply to Dedicated advanced clusters.
For Cloud provider, select Google Cloud.
For Regions & nodes, use the default selection of California (us-west) region and 3 nodes.

Note:

You can also select 3 regions with 3 nodes per region if you want to create a multi-region trial cluster.
Under Hardware per node, select 2vCPU for Compute and a 35 GiB disk for Storage.

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.
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).
Click Next.
On the Summary page, enter your credit card details.

Note:

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

Your cluster will be created in approximately 20-30 minutes. Watch this video while you wait to get a preview of how you'll connect to your cluster.

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

Step 2. Create a SQL user

In the left navigation bar, click SQL Users.
Click Add User. The Add User dialog displays.
Enter a Username and Password.
Click Save.

Step 3. Authorize your network

In the left navigation bar, click Networking.
Click Add Network. The Add Network dialog displays.
From the Network dropdown, select Current Network to auto-populate your local machine's IP address.
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.
Click Apply.

Step 4. Connect to your cluster

Tip:

PowerShell is required to complete these steps.

In the top-right corner of the Console, click the Connect button. The Connect dialog will display.
From the SQL user dropdown, select the SQL user you created in Step 2. Create a SQL user.
Verify that the us-west2 GCP region and defaultdb database are selected.
Click Next. The Connect tab is displayed.
Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.
If you have not done so already, run the first command in the dialog to install the CockroachDB binary in /usr/local/bin, which is usually in the system PATH. To install it into a different location, replace /usr/local/bin/.
```
curl https://binaries.cockroachdb.com/cockroach-v23.1.13.darwin-10.9-amd64.tgz | tar -xJ && sudo cp -i cockroach-v23.1.13.darwin-10.9-amd64/cockroach /usr/local/bin/
```
If you have not done so already, run the first command in the dialog to install the CockroachDB binary in /usr/local/bin, which is usually in the system PATH. To install it into a different location, replace /usr/local/bin/.
```
curl https://binaries.cockroachdb.com/cockroach-v23.1.13.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v23.1.13.linux-amd64/cockroach /usr/local/bin/
```
If you have not done so already, use PowerShell to run the first command in the dialog, which is a PowerShell script that installs the CockroachDB binary and adds its location in the system PATH:
```
$ErrorActionPreference = "Stop"; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;$ProgressPreference = 'SilentlyContinue'; $null = New-Item -Type Directory -Force $env:appdata/cockroach; Invoke-WebRequest -Uri https://binaries.cockroachdb.com/cockroach-v23.1.13.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Force -Path cockroach.zip; Copy-Item -Force "cockroach/cockroach-v23.1.13.windows-6.2-amd64/cockroach.exe" -Destination $env:appdata/cockroach; $Env:PATH += ";$env:appdata/cockroach"
```
We recommend adding ;$env:appdata/cockroach to the PATH variable for your system environment so you can run cockroach commands from any shell. See Microsoft's environment variable documentation for more information.
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 ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
```
Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.
```
curl --create-dirs -o ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
```
Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.
```
mkdir -p $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt
```
Your cert file will be downloaded to %APPDATA%/CockroachCloud/certs/<cluster-name>-ca.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 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.
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
```

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.
Download the ca.crt file to every machine from which you want to connect to the cluster.
Review the production checklist.

Was this helpful?

Cockroach
University

Docs Hub

Quickstart with CockroachDB Dedicated

Step 1. Create a free trial cluster

Step 2. Create a SQL user

Step 3. Authorize your network

Step 4. Connect to your cluster

Step 5. Use the built-in SQL client

What's next?

Cockroach University

Docs Hub

Cockroach University

Docs Hub

Quickstart with CockroachDB Dedicated

Step 1. Create a free trial cluster

Step 2. Create a SQL user

Step 3. Authorize your network

Step 4. Connect to your cluster

Step 5. Use the built-in SQL client

What's next?

Cockroach
University

Cockroach
University