Quickstart with CockroachDB

On this page

This page shows you how to get started with CockroachDB quickly. You'll create a CockroachDB cluster, and then insert and read some sample data from a sample application.

CockroachDB serverless is the easiest way to get started with CockroachDB Cloud. Follow these steps to create a new CockroachDB serverless cluster.

To get started with CockroachDB Cloud using CockroachDB dedicated clusters, see Quickstart with CockroachDB dedicated.

Follow these steps to get started with CockroachDB using a CockroachDB self-hosted cluster.

Choose your installation method

You can install a CockroachDB serverless cluster using either the CockroachDB Cloud Console, a web-based graphical user interface (GUI) tool, or ccloud, a command-line interface (CLI) tool.

Follow these steps to create a CockroachDB serverless cluster using the CockroachDB Cloud Console, a web based GUI.

Create a free cluster

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

Unless you change your monthly budget, this cluster will be free forever.
Click Create cluster.

Your cluster will be created in a few seconds and the Create SQL user dialog will display.

Create a SQL user

The Create SQL user dialog allows you to create a new SQL user and password.

Enter a username in the SQL user field or use the one provided by default.
Click Generate & save password.
Copy the generated password and save it in a secure location.
Click Next.

Currently, all new users are created with full privileges. For more information and to change the default settings, see Granting privileges and Using roles.

Connect to the cluster

Follow these steps to create a CockroachDB serverless cluster using the ccloud CLI tool.

Note:

The ccloud CLI tool is in Preview.

Install `ccloud`

Choose your OS:

You can install ccloud using either Homebrew or by downloading the binary.

Use Homebrew

Install Homebrew.
Install using the ccloud tap:
```
brew install cockroachdb/tap/ccloud
```

Download the binary

In a terminal, enter the following command to download and extract the ccloud binary and add it to your PATH:

curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-amd64_0.2.5.tar.gz | tar -xJ && cp -i ccloud /usr/local/bin/

Use the ARM 64 binary if you have an M1 Mac:

curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-arm64_0.2.5.tar.gz | tar -xJ && cp -i ccloud /usr/local/bin/

In a terminal, enter the following command to download and extract the ccloud binary and add it to your PATH:

curl https://binaries.cockroachdb.com/ccloud/ccloud_linux-amd64_0.2.5.tar.gz | tar -xz && cp -i ccloud /usr/local/bin/

In a PowerShell window, enter the following command to download and extract the ccloud binary and add it to your PATH:

$ErrorActionPreference = "Stop"; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; $ProgressPreference = 'SilentlyContinue'; $null = New-Item -Type Directory -Force $env:appdata/ccloud; Invoke-WebRequest -Uri https://binaries.cockroachdb.com/ccloud/ccloud_windows-amd64_0.2.5.zip -OutFile ccloud.zip; Expand-Archive -Force -Path ccloud.zip; Copy-Item -Force ccloud/ccloud.exe -Destination $env:appdata/ccloud; $Env:PATH += ";$env:appdata/ccloud"; # We recommend adding ";$env:appdata/ccloud" to the Path variable for your system environment. See https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables#saving-changes-to-environment-variables for more information.

Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.

The easiest way of getting started with CockroachDB Cloud is to use ccloud quickstart. The ccloud quickstart command guides you through logging in to CockroachDB Cloud, creating a new CockroachDB serverless with a $0 spend limit, and connecting to the new cluster. Run ccloud quickstart and follow the instructions:

ccloud quickstart

The ccloud quickstart command will open a browser window to log you in to CockroachDB Cloud. If you are new to CockroachDB Cloud, you can register using one of the single sign-on (SSO) options, or create a new account using an email address.

The ccloud quickstart command will prompt you for the cluster name, cloud provider, and cloud provider region, then ask if you want to connect to the cluster. Each prompt has default values that you can select, or change if you want a different option.

Select General connection string, then copy the connection string displayed and save it in a secure location. The connection string is the line starting postgresql://.

? How would you like to connect? General connection string
Retrieving cluster info: succeeded
 Downloading cluster cert to /Users/maxroach/.postgresql/root.crt: succeeded
postgresql://maxroach:ThisIsNotAGoodPassword@free-tier4.aws-us-west-2.cockroachlabs.cloud:26257/defaultdb?options=--cluster%3Ddim-dog-147&sslmode=verify-full&sslrootcert=%2FUsers%2Fmaxroach%2F.postgresql%2Froot.crt

The Connect to cluster dialog shows information about how to connect to your cluster.

Select General connection string from the Select option dropdown.
Open the General connection string section, then copy the connection string provided and save it in a secure location.

This Quickstart uses default certificates, so you can skip the Download CA Cert instructions.

Note:

The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided only once. Save it in a secure place (Cockroach Labs recommends 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.

The Connect to cluster dialog shows information about how to connect to your cluster.

Select General connection string from the Select option dropdown.
Open a new terminal on your local machine, and run the CA Cert download command provided in the Download CA Cert section. This certificate is required by most Python clients connecting to CockroachDB Cloud.
Open the General connection string section, then copy the connection string provided and save it in a secure location.

Note:

The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided only once. Save it in a secure place (Cockroach Labs recommends 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.

The Connect to cluster dialog shows information about how to connect to your cluster.

Select Java from the Select option dropdown.
Copy the JDBC_DATABASE_URL environment variable command provided and save it in a secure location.

This Quickstart uses default certificates, so you can skip the Download CA Cert instructions.

Note:

The connection string is pre-populated with your username, password, cluster name, and other details. Your password, in particular, will be provided only once. Save it in a secure place (Cockroach Labs recommends 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.

Choose your language

The sample code used in this tutorial is located in the quickstart-code-samples GitHub repo. This repo contains code samples written in JavaScript, Python, Go, and Java.

Use the node-postgres driver in a Node.js application.

Use the psycopg3 driver in a Python application.

Use the pgx driver in a Go application.

Use the JDBC driver in a Java application.

Start CockroachDB

If you haven't already, download the latest version of CockroachDB.
Run the cockroach demo command:
```
$ cockroach demo \
--no-example-database
```
This starts a temporary, in-memory cluster and opens an interactive SQL shell to the cluster. Any changes to the database will not persist after the cluster is stopped.

Note:

If cockroach demo fails due to SSL authentication, make sure you have cleared any previously downloaded CA certificates from the directory ~/.postgresql.

Copy the (sql/unix) connection string in the SQL shell welcome text:

# Connection parameters:
#   (webui)    http://127.0.0.1:8080/demologin?password=demo76950&username=demo
#   (sql)      postgres://demo:demo76950@127.0.0.1:26257?sslmode=require
#   (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26257

You'll use the sql/unix connection string to connect to the cluster later in this tutorial.

If you haven't already, download the latest version of CockroachDB.
Run the cockroach demo command:
```
$ cockroach demo \
--no-example-database
```
This starts a temporary, in-memory cluster and opens an interactive SQL shell to the cluster. Any changes to the database will not persist after the cluster is stopped.

Note:

If cockroach demo fails due to SSL authentication, make sure you have cleared any previously downloaded CA certificates from the directory ~/.postgresql.

Copy the (sql/jdbc) connection string in the SQL shell welcome text:

# Connection parameters:
#   (webui)    http://127.0.0.1:8080/demologin?password=demo76950&username=demo
#   (sql)      postgres://demo:demo76950@127.0.0.1:26257?sslmode=require
#   (sql/jdbc) jdbc:postgresql://127.0.0.1:26257/defaultdb?password=demo76950&sslmode=require&sslrootcert=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957%2Fca.crt&user=demo
#   (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26257

You'll use the sql/jdbc connection string to connect to the cluster later in this tutorial.

Configure the connection environment variable

In a terminal set the DATABASE_URL environment variable to the connection string that you copied earlier:

export DATABASE_URL="<connection-string>"

The code sample uses the connection string stored in the environment variable DATABASE_URL to connect to your cluster.

In a terminal set the DATABASE_URL environment variable to the connection string that you copied earlier:

export DATABASE_URL="<connection-string>"

The code sample uses the connection string stored in the environment variable DATABASE_URL to connect to your cluster.

In a terminal set the DATABASE_URL environment variable to the connection string that you copied earlier:

$env:DATABASE_URL = "<connection-string>"

The code sample uses the connection string stored in the environment variable DATABASE_URL to connect to your cluster.

Tip:

For reference information about connecting to CockroachDB with supported client drivers, see Connect to a CockroachDB Cluster.

Use the cockroach convert-url command to convert the connection string that you copied earlier to a valid connection string for JDBC connections:

cockroach convert-url --url "<connection-string>"

...
# Connection URL for JDBC (Java and JVM-based languages):
jdbc:postgresql://{host}:{port}/{database}?options=--cluster%3D{routing-id}&password={password}&sslmode=verify-full&user={username}

In a terminal set the JDBC_DATABASE_URL environment variable to the JDBC connection string:

export JDBC_DATABASE_URL="<jdbc-connection-string>"

The code sample uses the connection string stored in the environment variable JDBC_DATABASE_URL to connect to your cluster.

In a terminal set the JDBC_DATABASE_URL environment variable to the JDBC connection string:

$env:JDBC_DATABASE_URL = "<jdbc-connection-string>"

The code sample uses the connection string stored in the environment variable JDBC_DATABASE_URL to connect to your cluster.

Tip:

For reference information about connecting to CockroachDB with supported client drivers, see Connect to a CockroachDB Cluster.

Run the sample code

Clone the quickstart-code-samples repo:
```
git clone https://github.com/cockroachdb/quickstart-code-samples
```
Navigate to the node directory of the repo:
```
cd quickstart-code-samples/node
```
The code sample in this directory does the following:
1. Connects to CockroachDB Cloud with the node-postgres driver using the connection string set in the DATABASE_URL environment variable.
2. Creates a table.
3. Inserts some data into the table.
4. Reads the inserted data.
5. Prints the data to the terminal.
Install the code dependencies:
```
npm install
```
Run the code:
```
node app.js
```
The output will look like this:
```
Hello world!
```

Clone the quickstart-code-samples repo:
```
git clone https://github.com/cockroachdb/quickstart-code-samples
```
Navigate to the python directory of the repo:
```
cd quickstart-code-samples/python
```
The code sample in this directory does the following:
1. Connects to CockroachDB Cloud with the psycopg2 driver using the connection string set in the DATABASE_URL environment variable.
2. Creates a table.
3. Inserts some data into the table.
4. Reads the inserted data.
5. Prints the data to the terminal.
Install psycopg3.
```
pip3 install "psycopg[binary]"
```
Run the application:
```
python3 main.py
```
The output will look like this:
```
Hello world!
```

Clone the quickstart-code-samples repo:
```
git clone https://github.com/cockroachdb/quickstart-code-samples
```
Navigate to the go directory of the repo:
```
cd quickstart-code-samples/go
```
The code sample in this directory does the following:
1. Connects to CockroachDB Cloud with the pgx driver using the connection string set in the DATABASE_URL environment variable.
2. Creates a table.
3. Inserts some data into the table.
4. Reads the inserted data.
5. Prints the data to the terminal.
Initialize and run the app:
```
$ go mod init basic-sample
```
```
go mod tidy
```
```
$ go run main.go
```
The output will look like this:
```
Hello world!
```

Clone the quickstart-code-samples repo:
```
git clone https://github.com/cockroachdb/quickstart-code-samples
```
Navigate to the java directory of the repo:
```
cd quickstart-code-samples/java
```
The code sample in this directory does the following:
1. Connects to CockroachDB Cloud with the JDBC driver using the JDBC connection string set in the JDBC_DATABASE_URL environment variable.
2. Creates a table.
3. Inserts some data into the table.
4. Reads the inserted data.
5. Prints the data to the terminal.
Run the application using gradlew:
```
./gradlew run
```
The output should look like this:
```
> Task :app:run
Hello world!

BUILD SUCCESSFUL in 3s
2 actionable tasks: 2 executed
```

Next steps

Build a simple CRUD application in Go, Java, Node.js, or Python.
Learn CockroachDB SQL.
Create and manage SQL users.
Explore our example apps for examples on how to build applications using your preferred driver or ORM and run it on CockroachDB.
Migrate your existing data.

Learn more

This page outlines the quickest way to get started with CockroachDB. For information on other options that are available when creating a CockroachDB cluster, see the following:

To create a free cluster with other configurations (e.g., a different cloud provider, region, or monthly budget), see Create a CockroachDB serverless Cluster.
To connect to a free cluster with other options (e.g., a different SQL user) and connection methods (with an application or CockroachDB compatible tool), see Connect to a CockroachDB serverless Cluster.
To watch a video tutorial of connecting to a cluster, see Setting Up a CockroachDB serverless Cluster.
To watch a video tutorial of running queries against a cluster, see Using a CockroachDB serverless Cluster.

Was this helpful?

Cockroach
University

Docs Hub

Choose your installation method

Create a free cluster

Create a SQL user

Connect to the cluster

Install `ccloud`

Use Homebrew

Download the binary

Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.

Choose your language

Start CockroachDB

Configure the connection environment variable

Run the sample code

Next steps

Learn more

Cockroach University

Docs Hub

Cockroach University

Docs Hub

Quickstart with CockroachDB

Choose your installation method

Create a free cluster

Create a SQL user

Connect to the cluster

Install ccloud

Use Homebrew

Download the binary

Run ccloud quickstart to create a new cluster, create a SQL user, and retrieve the connection string.

Choose your language

Start CockroachDB

Configure the connection environment variable

Run the sample code

Next steps

Learn more

Cockroach
University

Cockroach
University

Install `ccloud`

Run `ccloud quickstart` to create a new cluster, create a SQL user, and retrieve the connection string.