Get Started with the ccloud CLI

On this page Carat arrow pointing down

The ccloud tool is a command-line interface (CLI) tool that allows you to create, manage, and connect to CockroachDB Cloud clusters. If you are new to CockroachDB Cloud, install ccloud and use the ccloud quickstart command to interactively log in and create a new CockroachDB serverless cluster.

Install ccloud

Choose your OS:

You can install ccloud using either Homebrew or by downloading the binary.

Use Homebrew

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

    icon/buttons/copy
    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:

icon/buttons/copy
curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-amd64_0.2.5.tar.gz | tar -xJ && cp -i ccloud /usr/local/bin/

Use the ARM 64 binary if you have an M1 Mac:

icon/buttons/copy
curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-arm64_0.2.5.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:

icon/buttons/copy
curl https://binaries.cockroachdb.com/ccloud/ccloud_linux-amd64_0.2.5.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:

icon/buttons/copy
$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.2.5.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.

Use ccloud quickstart

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:

icon/buttons/copy
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 options, or create a new account using an email address.

Log in to CockroachDB Cloud using ccloud auth

In order to use the ccloud commands to configure and manage your clusters, you first need to log in to CockroachDB Cloud. Use the ccloud auth login command to open a browser window to log in to CockroachDB Cloud.

  1. Run the ccloud auth login command and press Enter to open a browser window:

    icon/buttons/copy
    ccloud auth login
    

    This will take you to the CockroachDB Cloud login page.

  2. Enter your username and password if you already have a CockroachDB Cloud account, then click Continue.

    If you do not have a CockroachDB Cloud account, click one of the single sign-on (SSO) options or Sign up to register.

  3. Close the browser window and return to your terminal.

If you are a member of more than one CockroachDB Cloud organization, use the --org flag to set the organization name when authenticating.

icon/buttons/copy
ccloud auth login --org <organization label>

The organization label is found on the Settings page of the CockroachDB Cloud Console.

Create a new cluster using ccloud cluster create

There are two ways to create clusters using ccloud: ccloud quickstart create and ccloud cluster create.

The ccloud quickstart create command interactively guides you through creating and connecting to a new CockroachDB serverless cluster.

The ccloud cluster create command creates a new CockroachDB serverless or CockroachDB dedicated CockroachDB cluster in your organization.

Use the ccloud cluster create command to create a new CockroachDB serverless cluster.

icon/buttons/copy
ccloud cluster create

This command creates a CockroachDB serverless cluster in the default cloud infrastructure provider (GCP) and the closest region for that provider. It will generate a cluster name.

∙∙∙ Creating cluster...
Success! Created cluster
  name: dim-dog
  id: ec5e50eb-67dd-4d25-93b0-91ee7ece778d

The id in the output is the cluster ID. You use the name in other ccloud commands to identify the cluster on which the ccloud command operates.

You can set the cluster name, cloud infrastructure provider, region, and spend limit as command options. The following command is equivalent to the previous command that uses the default values.

icon/buttons/copy
ccloud cluster create serverless dim-dog us-central1 --cloud GCP --spend-limit 0

Use the ccloud cluster create command to create a new CockroachDB dedicated cluster.

icon/buttons/copy
ccloud cluster create dedicated

This command creates a 1 node CockroachDB dedicated cluster with 2 virtual CPUs (vCPUs) and 15 GiB of storage in the default cloud infrastructure provider (GCP) and the closest region for that provider. It will generate a cluster name. The CockroachDB version will be the latest stable version.

You can set the cluster name, cloud infrastructure provider, region, number of nodes, and storage as command options. The following command is equivalent to the previous command that uses the default values.

icon/buttons/copy
ccloud cluster create dedicated dim-dog us-central1:1 --cloud GCP --vcpus 2 --storage-gib 15
∙∙∙ Creating cluster
Success! Created cluster
  name: dim-dog
  id: ec5e50eb-67dd-4d25-93b0-91ee7ece778d

The id in the output is the cluster ID. You use the name in other ccloud commands to identify the cluster on which the ccloud command operates.

When creating multi node clusters, you must specify how many nodes should be in each region supported by the cloud infrastructure provider. For example, the following command creates a 3 node cluster where 2 nodes are in us-central1 and 1 node is in us-west2:

icon/buttons/copy
ccloud cluster create dedicated dim-dog us-central1:2 us-west2:1 --cloud GCP --vcpus 2 --storage-gib 15
Note:

If you set a maximum spend limit greater than $0 on a CockroachDB serverless cluster, or create a CockroachDB dedicated cluster, you must add a credit card to your organization.

Create and manage IP allowlists using ccloud cluster networking allowlist

Use the ccloud cluster networking allowlist create command to create an IP allowlist, which allows incoming network connections from the specified network IP range. Use the --sql flag to allow incoming CockroachDB SQL shell connections from the specified network. Use the --ui flag to allow access to the DB Console from the specified network.

The IP range must be in Classless Inter-Domain Routing (CIDR) format. For more information on CIDR, see Understanding IP Addresses, Subnets, and CIDR Notation for Networking.

For example, to allow incoming connections from a single IP address, 1.1.1.1, to your cluster, including the CockroachDB SQL shell and DB Console, use the following command:

icon/buttons/copy
ccloud cluster networking allowlist create dim-dog 1.1.1.1/32 --sql --ui
∙∙∙ Creating IP allowlist entry...
Success! Created IP allowlist entry for
 network: 1.1.1.1/32
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d

Use the ccloud cluster networking allowlist list command to list the IP allowlists for your cluster:

icon/buttons/copy
ccloud cluster networking allowlist list dim-dog
∙●∙ Retrieving cluster allowlist...
NETWORK         NAME  UI  SQL
1.1.1.1/32            ✔   ✔

To modify an allowlist entry, use the ccloud cluster networking allowlist update command. The following command adds a descriptive name to the previously created entry.

icon/buttons/copy
ccloud cluster networking allowlist update dim-dog 1.1.1.1/32 --name home
∙∙● Updating IP allowlist entry...
Success! Updated IP allowlist entry for
 network: 1.1.1.1/32
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d

Rerunning the allowlist list command shows the updated entry:

icon/buttons/copy
ccloud cluster networking allowlist list dim-dog
∙∙∙ Retrieving cluster allowlist...
NETWORK         NAME  UI  SQL
1.1.1.1/32      home  ✔   ✔

To delete an entry, run the ccloud cluster networking allowlist delete command.

icon/buttons/copy
ccloud cluster networking allowlist delete dim-dog 1.1.1.1/32
∙∙∙ Deleting IP allowlist entry...
Success! Deleted IP allowlist entry for
 network: 1.1.1.1/32
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d

Get a list of all the clusters in your organization using ccloud cluster list

Use the ccloud cluster list command to show information about the clusters in your organization. It outputs columns with the cluster name, the cluster ID, the cluster plan, the creation date, the cluster's current state, the cloud provider, and the version of CockroachDB.

icon/buttons/copy
ccloud cluster list
∙∙∙ Retrieving clusters...
NAME                 ID                                    PLAN TYPE        CREATED AT                            STATE                   CLOUD               VERSION
dim-dog              041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d  PLAN_SERVERLESS  2022-03-20 13:47:40.529531 +0000 UTC  CLUSTER_STATE_CREATED   CLOUD_PROVIDER_GCP  v21.2.4
...
∙∙∙ Retrieving clusters...
NAME      ID                                    PLAN TYPE        CREATED AT                            STATE                   CLOUD               VERSION
dim-dog   041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d  PLAN_DEDICATED   2022-03-22 21:07:35.7177 +0000 UTC    CLUSTER_STATE_CREATING  CLOUD_PROVIDER_GCP  v21.2.4
...

Get information about your cluster using ccloud cluster info

Use the ccloud cluster info command with the cluster name as the parameter to show detailed information about your cluster. Find the Name column in the output of ccloud cluster list to find the name of the cluster.

icon/buttons/copy
ccloud cluster info dim-dog
∙∙∙ Retrieving cluster...
Cluster info
 name: dim-dog
 id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
 cockroach version: v21.2.4
 cloud: CLOUD_PROVIDER_GCP
 plan type: PLAN_SERVERLESS
 state: CLUSTER_STATE_CREATED
 spend limit: 0
 regions: us-central1
∙∙∙ Retrieving cluster...
Cluster info
 name: ievans-dim-dog-dos
 id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
 cockroach version: v21.2.4
 cloud: CLOUD_PROVIDER_GCP
 plan type: PLAN_DEDICATED
 state: CLUSTER_STATE_CREATING
 hardware per node:
  2 vCPU
  7.500000 GiB RAM
  15 GiB disk
  450 IOPS
 region nodes:
  us-central1: 1

Use a SQL client with a cluster using ccloud cluster sql

Use the ccloud cluster sql command to start a CockroachDB SQL shell connection to the specified cluster using the cluster ID. If you haven't created a SQL user for the specified cluster, you will be prompted to create a new user and set the user password.

icon/buttons/copy
ccloud cluster sql dim-dog
∙∙∙ Retrieving cluster info...
∙∙∙ Retrieving SQL user list...
No SQL users found. Create one now: y
Create a new SQL user:
Username: user
Password: ****************
∙∙∙ Creating SQL user...
Success! Created SQL user
 name: user
 cluster: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
Starting CockroachDB SQL shell...
#
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
# Client version: CockroachDB CCL v21.2.5 (x86_64-apple-darwin19, built 2022/02/07 21:04:05, go1.16.6)
# Server version: CockroachDB CCL v21.2.4-1-g70835279ac (x86_64-unknown-linux-gnu, built 2022/02/03 22:31:25, go1.16.6)

warning: server version older than client! proceed with caution; some features may not be available.

# Cluster ID: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
#
# Enter \? for a brief introduction.
#
user@free-tier7.gcp-us-central1.crdb.io:26257/defaultdb>

Get the connection information for your cluster using ccloud cluster sql

Use the ccloud cluster sql command to get connection information for the specified cluster using the cluster name.

To get the connection URL, use the --connection-url option.

icon/buttons/copy
ccloud cluster sql --connection-url dim-dog
∙∙∙ Retrieving cluster info...
postgresql://dim-dog-147.6wr.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fuser%2F.postgresql%2Froot.crt
∙∙∙ Retrieving cluster info...
postgresql://dim-dog-5bct.gcp-us-east4.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fuser%2FLibrary%2FCockroachCloud%2Fcerts%2Fdim-dog-ca.crt

To get the individual connection parameters, use the --connection-params option.

icon/buttons/copy
ccloud cluster sql --connection-params dim-dog
Connection parameters
 Database:  defaultdb
 Host:      dim-dog-147.6wr.cockroachlabs.cloud
 Port:      26257
∙∙∙ Retrieving cluster info...
Connection parameters
 Database:  defaultdb
 Host:      dim-dog-5bct.gcp-us-east4.cockroachlabs.cloud
 Port:      26257

Create a SQL user using ccloud cluster user create

Use the ccloud cluster user create command to create a new SQL user by passing in the cluster name and the username. By default, newly created users are assigned to the admin role. An admin SQL user has full privileges for all databases and tables in your cluster. This user can also create additional users and grant them appropriate privileges.

icon/buttons/copy
ccloud cluster user create dim-dog maxroach
Password: ****************
∙∙∙ Creating SQL user...

Delete a cluster using ccloud cluster delete

Use the ccloud cluster delete command to delete the specified cluster using the cluster name.

icon/buttons/copy
ccloud cluster delete dim-dog
∙∙∙ Deleting cluster...
Success! Deleted cluster
 id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
Note:

If the cluster state is CLUSTER_STATE_CREATING you cannot delete the cluster. You must wait until the cluster has been provisioned and started, with a status of CLUSTER_STATE_CREATED, before you can delete the cluster. CockroachDB serverless clusters are created in less than a minute. CockroachDB dedicated clusters can take an hour or more to provision and start.

Turn off telemetry events for ccloud

Cockroach Labs collects anonymized telemetry events to improve the usability of ccloud. Use the ccloud settings set command and disable sending telemetry events to Cockroach Labs.

icon/buttons/copy
ccloud settings set --disable-telemetry=true

Yes No
On this page

Yes No