Skip to main content
This feature is in and subject to change. To share feedback and/or issues, contact Support.
Virtual clusters let agents and application developers instantly spin up isolated CockroachDB clusters without requiring newly-provisioned hardware. Virtual clusters are run on top of a host cluster, which serves as the deployed hardware that hosts virtual clusters of varying size and usage. To learn more about virtual clusters, read about Virtualization in Cockroach Continuum. In this tutorial you will create a virtual CockroachDB cluster, connect to it, and interface with a SQL shell.

​
Before you begin

This tutorial assumes that you have access to a Cockroach Continuum organization with a running host cluster. You should have:
  • A Cockroach Continuum organization. Refer to Create a Continuum Organization to create a new organization if needed, or confirm if your existing CockroachDB deployment is running Continuum.
  • A deployed host cluster in the organization. Refer to Create a Cluster if you are creating a host cluster yourself.
  • Permission to create clusters in the organization.

​
Steps

In these instructions, you’ll use the ccloud CLI tool to connect to your organization, create a virtual cluster, and access a SQL shell:
  1. Install the ccloud CLI. To install using Homebrew, run the following command:
  2. Log in to your Cockroach Continuum organization by running the following command:
    Press Enter to open a browser window and complete login. To log in on a headless machine, use the --no-redirect flag. If you are a member of more than one Cockroach organization, use the --org flag to specify the organization label:
  3. Virtual clusters are created inside of a workspace, which sets default configurations for other virtual clusters on that host. Run the following command to list workspaces in the organization:
  4. Select a workspace to create your virtual cluster in, then run the following command to create the cluster with a name you specify:
  5. By default, CockroachDB clusters are locked down to disallow all remote network access. Create an IP allowlist that will allow incoming SQL connections from an IP address or subnet. Run the following command to create an initial entry that allows SQL access for your specific IP address:
    Read the Connect to a Cluster documentation for more information on secure network connectivity options to your virtual cluster.
  6. Now, you can connect to your virtual cluster with a SQL shell using the following command:
    This will prompt you to create the first SQL user for your cluster. Specify a username and password to create the user, then access the SQL shell:
Now that you have created a virtual cluster and SQL user, you can establish connections to the cluster with the SQL client or database application of your choice. You can run the following command to get a PostgreSQL connection URL to your virtual cluster:

​
What’s next