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.
- Install Homebrew.
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.
In a terminal, run
ccloud quickstart
:ccloud quickstart
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.
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.
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.
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 postgresql://maxroach:ThisIsNotAGoodPassword@dim-dog-147.6wr.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fmaxroach%2F.postgresql%2Froot.crt
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): jdbc:postgresql://{host}:{port}/{database}?password={password}&sslmode=verify-full&user={username}
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
Clone the
quickstart-code-samples
repo:git clone https://github.com/cockroachdb/quickstart-code-samples
Navigate to the
java
directory of the repo:cd quickstart-code-samples/java
The 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_URL
environment 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 run
The output should look like this:
> Task :app:run Hello world! BUILD SUCCESSFUL in 3s 2 actionable tasks: 2 executed
Learn more
Now that you have a free CockroachDB Serverless cluster running, try out the following:
- 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 about
ccloud
.
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:
- To create a Self-Hosted cluster, see Start a Local Cluster.
- To create a CockroachDB Dedicated cluster, see Quickstart with CockroachDB Dedicated.
- To create a CockroachDB Serverless cluster with other configurations (e.g., a different cloud provider, region, or monthly budget), see Create a CockroachDB Serverless Cluster.
- To connect to a CockroachDB Serverless 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.