> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Your First Virtual Cluster

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

<Note>
  **This feature is in <InternalLink version="releases" path="cockroachdb-feature-availability">preview</InternalLink>** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).
</Note>

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](/docs/continuum/virtualization-overview).

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](/docs/continuum/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](/docs/continuum/workspaces) in the organization. Refer to [Create a Cluster](/docs/continuum/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](/docs/cockroachcloud/ccloud-get-started). To install using Homebrew, run the following command:
   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   brew install cockroachdb/tap/ccloud
   ```

2. Log in to your Cockroach Continuum organization by running the following command:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud auth login
   ```

   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:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud auth login --org {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:
   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud workspace list
   ```

4. Select a workspace to create your virtual cluster in, then run the following command to create the cluster with a name you specify:
   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud cluster create --workspace {workspace-name} {cluster-name}
   ```
   ```
   ∙∙∙ Creating cluster...
   Success! Created cluster
     name: {cluster-name}
     id: example-67dd-4d25-93b0-91ee7ece778d
   ```

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:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud cluster networking allowlist create {cluster-name} {your-ip-address}/32 --sql
   ```

   ```
   ∙∙∙ Creating IP allowlist entry...
   Success! Created IP allowlist entry for
   network: {your-ip-address}/32
   cluster: example-67dd-4d25-93b0-91ee7ece778d
   ```

   Read the [Connect to a Cluster](/docs/cockroachcloud/connect-to-your-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:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud cluster sql {cluster-name}
   ```

   This will prompt you to create the first [SQL user](/docs/stable/security-reference/authorization#sql-users) for your cluster. Specify a username and password to create the user, then access the SQL shell:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ∙∙∙ 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: example-67dd-4d25-93b0-91ee7ece778d
   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 vXX.2.5 (x86_64-apple-darwin19, built 2022/02/07 21:04:05, go1.16.6)
   # Server version: CockroachDB CCL vXX.2.4-1-g70835279ac (x86_64-unknown-linux-gnu, built 2022/02/03 22:31:25, go1.16.6)
   #
   # Cluster ID: example-67dd-4d25-93b0-91ee7ece778d
   #
   # Enter \? for a brief introduction.
   #
   ```

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](/docs/stable/connection-parameters) to your virtual cluster:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ccloud cluster sql --connection-url {cluster-name}
```

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
∙∙∙ Retrieving cluster info...
postgresql://cluster-name-5bct.gcp-us-east4.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=%2FUsers%2Fuser%2FLibrary%2FCockroachCloud%2Fcerts%2Fcluster-name-ca.crt
```

## What's next

* [Manage a cluster with the ccloud tool](/docs/cockroachcloud/ccloud-reference).
* [Use CockroachDB SQL](/docs/stable/sql-statements).
* [Learn more about virtual clusters](/docs/continuum/virtual-clusters).