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.

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.

Step 1. 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.

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

Step 3. Connect to the cluster

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.

Step 4. Configure the connection environment variable

Step 1. 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.

Step 2. Configure the connection environment variable

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.

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.

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.

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.

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.

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

Step 5. Run the sample code

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