Quickstart with CockroachDB

On this page Carat arrow pointing down

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

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

  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.2.5.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.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:

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

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

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@dim-dog-147.6wr.cockroachlabs.cloud:26257/defaultdb?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 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 Java from the Select option dropdown.
  2. 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

  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.

  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/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:

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.

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}?password={password}&sslmode=verify-full&user={username}

In a terminal set the JDBC_DATABASE_URL environment variable to the JDBC 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.

In a terminal set the JDBC_DATABASE_URL environment variable to the JDBC 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.

Tip:

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

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

    icon/buttons/copy
    pip3 install "psycopg[binary]"
    
  4. Run the application:

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


Yes No
On this page

Yes No