Quickstart with CockroachDB

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 (beta) is the easiest way to get started with CockroachDB Cloud. Follow these steps to create a new CockroachDB Serverless (beta) cluster.

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

Note:

CockroachDB Serverless is currently in beta. For information about its limitations, see the Serverless FAQs.

Follow these steps to get started with CockroachDB using a CockroachDB Self-Hosted cluster.

Choose your installation method

You can install a CockroachDB Serverless (beta) 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 (beta) cluster using the CockroachDB Cloud Console, a web based GUI.

Create a free cluster

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

  4. On the Create your cluster page, select Serverless.

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

  5. 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.

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

  4. 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 (beta) cluster using the ccloud CLI tool.
Note:
The ccloud CLI tool is in beta.

Install ccloud

Choose your OS:

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

Use Homebrew

  1. Install Homebrew.

  2. Install using the ccloud tap:

    icon/buttons/copy 
    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:

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

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

icon/buttons/copy 
curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-arm64_0.1.1.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:

icon/buttons/copy 
curl https://binaries.cockroachdb.com/ccloud/ccloud_linux-amd64_0.1.1.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:

icon/buttons/copy 
$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.1.1.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 (beta) with a $0 spend limit, and connecting to the new cluster. Run ccloud quickstart and follow the instructions:

icon/buttons/copy 
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.

  1. Select General connection string from the Select option dropdown.

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

  1. Select General connection string from the Select option dropdown.

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

  1. Select General connection string from the Select option dropdown.
  2. 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.

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

  1. Select General connection string from the Select option dropdown.

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

  3. If you haven't already, install the cockroach binary and add it to your OS's PATH.

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 psycopg2 driver in a Python application.

Use the pgx driver in a Go application.

Use the JDBC driver in a Java application.

Configure the connection environment variable

Start CockroachDB

  1. If you haven't already, download the latest version of CockroachDB.

  2. Run the cockroach demo command:

    icon/buttons/copy 
    $ 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.

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

Configure the connection environment variable

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

icon/buttons/copy 
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:

icon/buttons/copy 
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:

icon/buttons/copy 
$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.

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

icon/buttons/copy 
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:

icon/buttons/copy 
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:

icon/buttons/copy 
$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.

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

icon/buttons/copy 
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:

icon/buttons/copy 
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:

icon/buttons/copy 
$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.

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

    icon/buttons/copy 
    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}

  2. Set the JDBC_DATABASE_URL environment variable to the JDBC-compatible connection string:

    icon/buttons/copy 
    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.

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

    icon/buttons/copy 
    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}

  2. Set the JDBC_DATABASE_URL environment variable to the JDBC-compatible connection string:

    icon/buttons/copy 
    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.

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

    icon/buttons/copy 
    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}

  2. Set the JDBC_DATABASE_URL environment variable to the JDBC-compatible connection string:

    icon/buttons/copy 
    $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.

Run the sample code

Run the sample code

  1. Clone the quickstart-code-samples repo:

    icon/buttons/copy 
    git clone https://github.com/cockroachdb/quickstart-code-samples

  2. Navigate to the node directory of the repo:

    icon/buttons/copy 
    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 connectiong 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.

  3. Install the code dependencies:

    icon/buttons/copy 
    npm install

  4. Run the code:

    icon/buttons/copy 
    node app.js

    The output will look like this:

    Hello world!

  1. Clone the quickstart-code-samples repo:

    icon/buttons/copy 
    git clone https://github.com/cockroachdb/quickstart-code-samples

  2. Navigate to the python directory of the repo:

    icon/buttons/copy 
    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 connectiong 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.

  3. Install psycopg2.

    icon/buttons/copy 
    pip install psycopg2-binary

  4. Run the application:

    icon/buttons/copy 
    python main.py

    The output will look like this:

    Hello world!

  1. Clone the quickstart-code-samples repo:

    icon/buttons/copy 
    git clone https://github.com/cockroachdb/quickstart-code-samples

  2. Navigate to the go directory of the repo:

    icon/buttons/copy 
    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 connectiong 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.

  3. Initialize and run the app:

    icon/buttons/copy 
    $ go mod init basic-sample
    icon/buttons/copy 
    go mod tidy
    icon/buttons/copy 
    $ go run main.go

    The output will look like this:

    Hello world!

  1. Clone the quickstart-code-samples repo:

    icon/buttons/copy 
    git clone https://github.com/cockroachdb/quickstart-code-samples

  2. Navigate to the java directory of the repo:

    icon/buttons/copy 
    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 connectiong 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.

  3. Run the application using gradlew:

    icon/buttons/copy 
    ./gradlew run

    The output should look like this:

    > Task :app:run
Hello world!

BUILD SUCCESSFUL in 3s
2 actionable tasks: 2 executed

Next steps

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:

YesYes NoNo

Product

Resources

Learn

Support Channels

Company

Get developer news