ccloud tool or logged into CockroachDB Cloud, refer to .
Log in to a CockroachDB Cloud organization
Run theccloud auth login command and press Enter to open a browser window:
--org flag to set the organization name when authenticating.
Create a new cluster
There are two ways to create clusters usingccloud: ccloud quickstart create and ccloud cluster create.
The ccloud quickstart create command interactively guides you through creating and connecting to a new CockroachDB Basic cluster.
The ccloud cluster create command creates a new CockroachDB Cloud cluster in your organization with the desired plan.
Create a Basic cluster
Use theccloud cluster create basic command to create a new CockroachDB Basic cluster.
id in the output is the cluster ID. 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 as command options. The following command is equivalent to the previous command that uses the default values.
Create a Standard cluster
Use theccloud cluster create standard command to create a new CockroachDB Standard cluster.
id in the output is the cluster ID. 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 as command options. The following command is equivalent to the previous command that uses the default values.
Create an Advanced cluster
Use theccloud cluster create dedicated command to create a new CockroachDB Advanced cluster.
id in the output is the cluster ID. 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, number of nodes, and storage as command options. The following command is equivalent to the previous command that uses the default values.
us-central1 and 4 nodes are in us-west2. For optimum performance, it is generally recommended to configure the same number of nodes in each region.
List clusters in an organization
Use theccloud 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.
Get information about a cluster
Use theccloud 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.
Delete a cluster
Use theccloud cluster delete command to delete the specified cluster using the cluster name.
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 Advanced clusters can take an hour or more to provision and start.Connect to a cluster with a SQL client
Use theccloud cluster sql command to start a CockroachDB SQL shell connection to the specified cluster using the cluster ID. If you haven’t created a for the specified cluster, you will be prompted to create a new user and set the user password.
Connect to your cluster using SSO
Use the--sso flag to connect to your cluster using , which will allow you to start a SQL shell without using a password.
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.
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. -
Log 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: -
Re-run the SQL client command to login and connect to your cluster.
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.
-
Log in to the correct organization.
Skip the IP allowlist check when connecting to your cluster
By default, theccloud cluster sql command will allow connections only from IP addresses in your cluster’s . Use the --skip-ip-check flag to disable the client-side IP allowlist check:
Create a SQL user
Use theccloud cluster user create command to create a new 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.
Get connection information for a cluster
Use theccloud cluster sql command to get connection information for the specified cluster using the cluster name.
To get the , use the --connection-url option.
--connection-params option.
Manage databases
Theccloud cluster database command lists, creates, and deletes databases within a cluster.
Use ccloud cluster database list to list all databases in a cluster:
ccloud cluster database create to create a new database:
ccloud cluster database delete to delete a database:
Manage cluster backups
Theccloud cluster backup commands lists backups and manages for a cluster.
Use ccloud cluster backup list to list backups for a cluster:
ccloud backup config get to retrieve the specified backup configuration:
ccloud cluster backup config update to update the specified backup configuration:
Restore from a backup
Theccloud cluster restore commands list and create restore operations from backups.
Use ccloud cluster restore list to list restores for a cluster:
ccloud cluster restore create to start a restore from a specific backup to a destination cluster:
--source-cluster-id flag:
CLUSTER, DATABASE, or TABLE) using the --type flag:
List available CockroachDB versions
Use theccloud cluster versions command to list the CockroachDB major versions available for new clusters or upgrades.
Manage upgrade deferrals
Theccloud cluster version-deferral commands get or set the version upgrade deferral policy for a CockroachDB Advanced cluster. Version deferral lets you delay automatic major version upgrades.
Use ccloud cluster version-deferral get to retrieve the current deferral policy:
ccloud cluster version-deferral set to set the deferral policy:
NOT_DEFERRED, DEFERRAL_30_DAYS, DEFERRAL_60_DAYS, and DEFERRAL_90_DAYS.
Manage blackout windows
This feature is in and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
ccloud cluster blackout-window commands manage blackout windows for a CockroachDB Advanced cluster. Blackout windows prevent automatic maintenance operations during specified time periods.
Use ccloud cluster blackout-window list to retrieve blackout windows:
--start and --end flags. The start time must be at least 7 days in the future, and the end time must be within 14 days of the start time.
ccloud cluster blackout-window delete to delete a blackout window:
Manage maintenance windows
Theccloud cluster maintenance commands configure the preferred maintenance window for a CockroachDB Advanced cluster. The maintenance window determines when automatic maintenance operations are performed. The window duration must be at least 6 hours and less than 1 week.
Use ccloud cluster maintenance get to retrieve the current maintenance window:
ccloud cluster maintenance set to set a maintenance window using the --day, --hour, and --duration flags:
--offset flag:
ccloud cluster maintenance delete to delete the maintenance window, resetting to default:
Simulate cluster disruptions
This feature is in and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
ccloud cluster disruption commands simulate cluster disruptions for disaster recovery testing on a CockroachDB Advanced cluster. Disruptions allow you to test how your applications behave when parts of your cluster become unavailable.
Use ccloud cluster disruption get to retrieve the current disruption status:
ccloud cluster disruption set to disrupt a whole region as specified with the --region and --whole-region flags:
--azs flag to disrupt specific availability zones within the specified region:
ccloud cluster disruption clear to clear all disruptions and restore normal operation:
View CMEK configuration
Use theccloud cluster cmek get command to view the configuration for a CockroachDB Advanced cluster.
Configure log export
Theccloud cluster log-export commands configure log export for a CockroachDB Advanced cluster. You can export logs to AWS CloudWatch, GCP Cloud Logging, or Azure Log Analytics.
Use ccloud cluster log-export get to retrieve the current log export configuration:
ccloud cluster log-export enable to enable log export. The following example configuration enables log export to AWS CloudWatch:
ccloud cluster log-export disable command to disable log export:
Configure metric export
Theccloud cluster metric-export commands configure metric exporting for a CockroachDB Advanced cluster. You can export metrics to AWS CloudWatch, Datadog, or Prometheus as described in the following sections.
Export metrics to AWS CloudWatch
Useccloud cluster metric-export cloudwatch enable to enable metric export to AWS CloudWatch:
ccloud cluster metric-export cloudwatch get to retrieve the current CloudWatch metric export configuration:
ccloud cluster metric-export cloudwatch disable to disable CloudWatch metric export:
Export metrics to Datadog
Useccloud cluster metric-export datadob enable to enable metric export to Datadog:
ccloud cluster metric-export datadog get to retrieve the current Datadog metric export configuration:
ccloud cluster metric-export datadog disable to disable Datadog metric export:
Export metrics to Prometheus
Useccloud cluster metric-export prometheus enable to enable metric export to Prometheus:
ccloud cluster metric-export prometheus get to retrieve the Prometheus scrape endpoint:
ccloud cluster metric-export prometheus disable to disable the Prometheus endpoint:
Create and manage IP allowlists
Theccloud cluster networking allowlist commands create or manage an , 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 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.
Use the ccloud cluster networking allowlist create command to create an allowlist. 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 list command to list the IP allowlists for your cluster:
ccloud cluster networking allowlist update command. The following command adds a descriptive name to the previously created entry:
allowlist list command shows the updated entry:
ccloud cluster networking allowlist delete command to delete an entry:
Manage egress networking rules
Theccloud cluster networking egress-rule commands manage egress traffic rules for a CockroachDB Advanced cluster. Egress rules control which external destinations your cluster can connect to.
Use ccloud cluster networking egress-rule list to retrieve egress rules:
ccloud cluster networking egress-rule create to create an egress rule:
ccloud cluster networking egress-rule delete to delete an egress rule:
Manage client CA certificates
Theccloud cluster networking client-ca-cert commands for a CockroachDB Advanced cluster. Client CA certificates allow clients to authenticate using TLS certificates signed by your own certificate authority.
Use ccloud cluster networking client-ca-cert get to retrieve the current client CA certificate:
ccloud cluster networking client-ca-cert set to create a client CA certificate from a PEM-encoded file specified with the --cert-file flag:
ccloud cluster networking client-ca-cert update to update the client CA certificate:
ccloud cluster networking client-ca-cert delete to delete the client CA certificate:
Manage private endpoints
Theccloud cluster networking private-endpoint commands manage for a CockroachDB Advanced cluster. Private endpoints provide private connectivity using AWS PrivateLink, GCP Private Service Connect, or Azure Private Link.
Manage private endpoint services
Useccloud cluster networking private-endpoint service list to retrieve available private endpoint services for a cluster:
ccloud cluster networking private-endpoint service create to create private endpoint services for all regions in a cluster:
Manage private endpoint connections
Useccloud cluster networking private-endpoint connection list to retrieve private endpoint connections:
ccloud cluster networking private-endpoint connection add to add a connection using your cloud provider’s private endpoint identifier:
ccloud cluster networking private-endpoint connection remove to remove a connection:
Manage trusted owners
Trusted owners control which cloud provider accounts are allowed to establish private endpoint connections to your cluster. Useccloud cluster networking private-endpoint trusted-owner list to retrieve trusted owners:
ccloud cluster networking private-endpoint trusted-owner add to add a trusted owner:
ccloud cluster networking private-endpoint trusted-owner remove to remove a trusted owner:
Manage egress private endpoints
This feature is in and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
ccloud cluster networking egress-private-endpoint commands manage from a CockroachDB Advanced cluster. Egress private endpoints allow your cluster to connect to external services using private network connectivity.
Use ccloud cluster networking egress-private-endpoint list to retrieve egress private endpoints:
ccloud cluster networking egress-private-endpoint get to retrieve details about the specified egress private endpoint:
ccloud cluster networking egress-private-endpoint create to create an egress private endpoint:
--target-service-type flag are PRIVATE_SERVICE, MSK_SASL_SCRAM, MSK_SASL_IAM, and MSK_TLS.
Use ccloud cluster networking egress-private-endpoint delete to delete an egress private endpoint:
View organization information
Use theccloud organization get command (or its alias ccloud org get) to view information about your CockroachDB Cloud organization.
View audit logs
Use theccloud audit list command to view audit log entries for your organization. Audit logs record actions taken on your CockroachDB Cloud resources, including who performed the action, when, and what was changed.
--limit flag to control the number of entries returned, and --starting-from to filter by start time:
Manage billing
Theccloud billing invoice commands display invoices and billing information for your organization.
Use ccloud billing invoice list to retrieve a list of invoices:
ccloud billing invoice get to retrieve the details of a specific invoice:
Manage folders
Theccloud folder commands manage folders for organizing clusters within your organization.
Use ccloud folder list to retrieve a list of folders:
ccloud folder get to retrieve the details of a specific folder:
ccloud folder create to create a folder:
--parent-id flag with a folder ID to create a subfolder:
ccloud folder update to update a folder name:
ccloud folder delete to delete a folder:
ccloud folder contents to retrieve the contents of a folder:
Manage service accounts
Theccloud service-account commands manage service accounts for programmatic access to CockroachDB Cloud.
Use ccloud service-account list to retrieve a list of service accounts:
ccloud service-account get to retrieve details for a specific service account:
ccloud service-account create to create a service account with a description specified by the --description flag:
ccloud service-account delete to delete a service account:
Manage API keys for service accounts
Theccloud service-account api-key commands manage API keys for a service account.
Use ccloud service-account api-key list to list API keys for the service account ID specified by the --service-account-id flag:
ccloud service-account api-key create to create an API key:
ccloud service-account api-key delete to delete an API key:
Manage JWT issuers
This feature is in and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
ccloud jwt-issuer commands manage JWT/OIDC identity providers for cluster authentication. JWT issuers allow your clusters to authenticate users via external identity providers.
Use ccloud jwt-issuer list to retrieve a list of JWT issuers:
ccloud jwt-issuer get to retrieve the details of a JWT issuer:
ccloud jwt-issuer create to create a JWT issuer with the specified --issuer-url, --audience, and --claim flag values:
ccloud jwt-issuer update to update a JWT issuer with the values of the specified flags:
ccloud jwt-issuer delete to delete a JWT issuer:
Manage physical cluster replication
This feature is in and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
ccloud replication commands manage between CockroachDB Cloud clusters.
Use ccloud replication list to retrieve a list of replication streams for a cluster:
ccloud replication get to retrieve the details of a replication stream:
ccloud replication create to create a replication stream between the clusters specified in the --primary-cluster and --standby-cluster flags:
ccloud replication update with the --status FAILING_OVER flag to initiate a failover to the standby cluster:
--failover-at flag to schedule a failover for a specific time:
ccloud replication update with the --status CANCELED flag to cancel a replication stream:
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.