Quickstart with CockroachDB

On this page Carat arrow pointing down

This page shows you how to get started with CockroachDB quickly. You'll use ccloud, CockroachDB Cloud's command-line interface (CLI) tool, to create a CockroachDB Serverless cluster and then insert and read some sample data from a Java sample application.

Install ccloud


This feature is in preview. This feature is subject to change. To share feedback and/or issues, contact Support.

  1. Install Homebrew.
  2. Install using the ccloud tap:

    brew install cockroachdb/tap/ccloud

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

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.

  1. In a terminal, run ccloud quickstart:

    ccloud quickstart
  2. Log in to CockroachDB Cloud using the browser window opened by ccloud quickstart.

    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.

  3. In your terminal, follow the ccloud quickstart prompts to choose a cluster name, cloud provider, and cloud provider region, and then create the cluster.

    Each prompt has default values that you can select, or change if you want a different option.

  4. Once your cluster has been created, follow the prompts in your terminal to connect to your cluster.

    You will have to create a SQL user and password, but you can use the default values for the database name and CA certificate path.

  5. From the list of available connection options, select General connection string, then copy the connection string displayed and save it in a secure location. The connection string is the line starting with postgresql://:

    ? How would you like to connect? General connection string
    Retrieving cluster info: succeeded
     Downloading cluster cert to /Users/maxroach/.postgresql/root.crt: succeeded
  6. 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):
  7. Run the following command to set the JDBC_DATABASE_URL environment variable to the JDBC connection string:

    export JDBC_DATABASE_URL="<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.

Run the Java sample code

  1. Clone the quickstart-code-samples repo:

    git clone https://github.com/cockroachdb/quickstart-code-samples
  2. 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.
  3. Run the application using gradlew:

    ./gradlew run

    The output should look like this:

    > Task :app:run
    Hello world!
    2 actionable tasks: 2 executed

Learn more

Now that you have a free CockroachDB Serverless cluster running, try out the following:

This page highlights just one way you can 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