Quickstart with CockroachDB

On this page

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

curl https://binaries.cockroachdb.com/ccloud/ccloud_linux-amd64_0.3.7.tar.gz | tar -xz && cp -i ccloud /usr/local/bin/

$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
   postgresql://maxroach:ThisIsNotAGoodPassword@dim-dog-147.6wr.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fmaxroach%2F.postgresql%2Froot.crt
   

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):
     jdbc:postgresql://{host}:{port}/{database}?password={password}&sslmode=verify-full&user={username}
   

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

Was this helpful?