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
- 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.6.12.tar.gz | tar -xJ && cp -i ccloud /usr/local/bin/
Use the ARM 64 binary if you have an M-series Mac:
curl https://binaries.cockroachdb.com/ccloud/ccloud_darwin-arm64_0.6.12.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.6.12.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.6.12.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/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 cluster, 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 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.
Run the
ccloud auth logincommand and press Enter to open a browser window:ccloud auth loginThis will take you to the CockroachDB Cloud login page.
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.
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.
ccloud auth login --org {organization-label}
The organization label is found on the Settings page of the CockroachDB Cloud Console.
If your organization has a custom URL, use the --vanity-name flag to log in:
ccloud auth login --vanity-name {custom-organization-name}
Replace {custom-organization-name} with the portion of the custom sign-in URL that follows /login/. Do not pass the full custom sign-in URL.
Log in to CockroachDB Cloud on a headless server
If you are using ccloud on a headless machine, use the --no-redirect flag to log in. This allows you to log in to CockroachDB Cloud on a different machine, retrieve an authorization code, and enter the code on the headless machine so ccloud can complete authentication.
ccloud auth login --no-redirect
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.
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: blue-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 resource limits as command options. The following command is equivalent to the previous command that uses the default values.
ccloud cluster create serverless blue-dog us-central1 --cloud GCP --spend-limit 0
Use the ccloud cluster create command to create a new CockroachDB Dedicated cluster.
ccloud cluster create dedicated
This command creates a 1 node CockroachDB Dedicated cluster with 2 virtual CPUs (vCPUs) and 110 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.
ccloud cluster create dedicated blue-dog us-central1:1 --cloud GCP --vcpus 2 --storage-gib 15
∙∙∙ Creating cluster
Success! Created cluster
name: blue-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:
ccloud cluster create dedicated blue-dog us-central1:2 us-west2:1 --cloud GCP --vcpus 2 --storage-gib 15
To set resource limits for 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:
ccloud cluster networking allowlist create blue-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:
ccloud cluster networking allowlist list blue-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.
ccloud cluster networking allowlist update blue-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:
ccloud cluster networking allowlist list blue-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.
ccloud cluster networking allowlist delete blue-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.
ccloud cluster list
∙∙∙ Retrieving clusters...
NAME ID PLAN TYPE CREATED AT STATE CLOUD VERSION
blue-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
blue-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.
ccloud cluster info blue-dog
∙∙∙ Retrieving cluster...
Cluster info
name: blue-dog
id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
cockroach version: v21.2.4
cloud: CLOUD_PROVIDER_GCP
plan type: PLAN_SERVERLESS
state: CLUSTER_STATE_CREATED
resource limit: 0
regions: us-central1
∙∙∙ Retrieving cluster...
Cluster info
name: ievans-blue-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.
ccloud cluster sql blue-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>
Connect to your cluster using SSO
Use the --sso flag to connect to your cluster using single sign-on (SSO) authentication, which will allow you to start a SQL shell without using a password.
ccloud cluster sql --sso blue-dog
This will open a browser window on the local machine where you will log in to your organization if you are not already authenticated.
If you are running ccloud on a remote machine, use the --no-redirect flag. ccloud will output a URL that you must copy and paste in your local machine's browser in order to authenticate. After authentication, paste in the authorization code you received in the remote terminal to complete the login process.
ccloud cluster sql --sso --no-redirect blue-dog
Using SSO login requires that a separate SSO SQL user for your account is created on the cluster you are connecting to. SSO SQL usernames are prefixed with sso_. The SSO SQL username you use must match the SSO SQL username generated for you.
To create a SSO SQL user:
Connect to the cluster using the
--ssoflag.ccloud cluster sql --sso blue-dogLog in to your organization when prompted by
ccloud.Copy the command in the error message to create the SSO SQL user with the correct username.
You must have
adminprivileges to create the SSO SQL user.Create the SSO SQL user by pasting and running the command you copied.
For example, if the command in the error message creates a
sso_maxroachuser:ccloud cluster user create blue-dog sso_maxroachRe-run the SQL client command to login and connect to your cluster.
ccloud cluster sql blue-dog --sso
Use the ccloud auth whoami command to check that you are logged into the correct organization.
If the organization is incorrect:
Log out of the current organization.
ccloud auth logoutLog in to the correct organization.
ccloud auth login --org {organization name}
Skip the IP allowlist check when connecting to your cluster
By default, the ccloud cluster sql command will allow connections only from IP addresses in your cluster's allowlist. Use the --skip-ip-check flag to disable the client-side IP allowlist check:
ccloud cluster sql blue-dog --skip-ip-check
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.
ccloud cluster sql --connection-url blue-dog
∙∙∙ Retrieving cluster info...
postgresql://blue-dog-147.6wr.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fuser%2F.postgresql%2Froot.crt
∙∙∙ Retrieving cluster info...
postgresql://blue-dog-5bct.gcp-us-east4.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fuser%2FLibrary%2FCockroachCloud%2Fcerts%2Fblue-dog-ca.crt
To get the individual connection parameters, use the --connection-params option.
ccloud cluster sql --connection-params blue-dog
Connection parameters
Database: defaultdb
Host: blue-dog-147.6wr.cockroachlabs.cloud
Port: 26257
∙∙∙ Retrieving cluster info...
Connection parameters
Database: defaultdb
Host: blue-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.
ccloud cluster user create blue-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.
ccloud cluster delete blue-dog
∙∙∙ Deleting cluster...
Success! Deleted cluster
id: 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d
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.
ccloud settings set --disable-telemetry=true
Was this helpful?
