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, orccloud, 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
ccloud CLI tool.
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
ccloudtap: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.1.1.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.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:
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:
$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 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 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_URLenvironment 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 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
If you haven't already, download the latest version of CockroachDB.
Run the
cockroach democommand:$ cockroach demo \ --no-example-databaseThis 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 demofails 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=26257You'll use the
sql/unixconnection 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.
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:
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.
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:
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.
For reference information about connecting to CockroachDB with supported client drivers, see Connect to a CockroachDB Cluster.
In a terminal set the JDBC_DATABASE_URL environment variable to the connection string by running the command that you copied earlier:
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 connection string by running the command that you copied earlier:
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 connection string by running the command that you copied earlier:
$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.
For reference information about connecting to CockroachDB with supported client drivers, see Connect to a CockroachDB Cluster.
Run the sample code
Run the sample code
Clone the
quickstart-code-samplesrepo:git clone https://github.com/cockroachdb/quickstart-code-samplesNavigate to the
nodedirectory of the repo:cd quickstart-code-samples/nodeThe code sample in this directory does the following:
- Connects to CockroachDB Cloud with the node-postgres driver using the connection string set in the
DATABASE_URLenvironment variable. - Creates a table.
- Inserts some data into the table.
- Reads the inserted data.
- Prints the data to the terminal.
- Connects to CockroachDB Cloud with the node-postgres driver using the connection string set in the
Install the code dependencies:
npm installRun the code:
node app.jsThe output will look like this:
Hello world!
Clone the
quickstart-code-samplesrepo:git clone https://github.com/cockroachdb/quickstart-code-samplesNavigate to the
pythondirectory of the repo:cd quickstart-code-samples/pythonThe code sample in this directory does the following:
- Connects to CockroachDB Cloud with the psycopg2 driver using the connection string set in the
DATABASE_URLenvironment variable. - Creates a table.
- Inserts some data into the table.
- Reads the inserted data.
- Prints the data to the terminal.
- Connects to CockroachDB Cloud with the psycopg2 driver using the connection string set in the
Install psycopg2.
pip install psycopg2-binaryRun the application:
python main.pyThe output will look like this:
Hello world!
Clone the
quickstart-code-samplesrepo:git clone https://github.com/cockroachdb/quickstart-code-samplesNavigate to the
godirectory of the repo:cd quickstart-code-samples/goThe code sample in this directory does the following:
- Connects to CockroachDB Cloud with the pgx driver using the connection string set in the
DATABASE_URLenvironment variable. - Creates a table.
- Inserts some data into the table.
- Reads the inserted data.
- Prints the data to the terminal.
- Connects to CockroachDB Cloud with the pgx driver using the connection string set in the
Initialize and run the app:
$ go mod init basic-samplego mod tidy$ go run main.goThe output will look like this:
Hello world!
Clone the
quickstart-code-samplesrepo:git clone https://github.com/cockroachdb/quickstart-code-samplesNavigate to the
javadirectory of the repo:cd quickstart-code-samples/javaThe code sample in this directory does the following:
- Connects to CockroachDB Cloud with the JDBC driver using the JDBC connection string set in the
JDBC_DATABASE_URLenvironment variable. - Creates a table.
- Inserts some data into the table.
- Reads the inserted data.
- Prints the data to the terminal.
- Connects to CockroachDB Cloud with the JDBC driver using the JDBC connection string set in the
Run the application using
gradlew:./gradlew runThe 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?
