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

# Connect to a CockroachDB Advanced 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>;
};

This page shows you how to connect to your CockroachDB Advanced cluster. This includes the administrative task of configuring allowed networks to support SQL client connections, as well as the steps for connecting to the cluster with CockroachDB's <InternalLink version="stable" path="cockroach-sql">built-in SQL client</InternalLink>.

## Before you start

* <InternalLink path="create-your-cluster">Create a cluster</InternalLink>.
* <InternalLink path="managing-access#create-a-sql-user">Create a SQL user</InternalLink>.
* Understand <InternalLink path="network-authorization">Network Authorization for CockroachDB Cloud Clusters</InternalLink>

## Authorize your network

By default, CockroachDB Advanced clusters are locked down to all network access. You must authorized certain network connections in order to allow SQL clients to connect to your clusters. Advanced clusters can accept connections via two types of authorized network:

* IP allowlisting: Selectively IP address ranges to connect to the cluster.
* Private connectivity: Cloud-provider-specific private networking options, including GCP Private Service Connect, GCP VPC Peering, AWS Privatelink, or Azure Private Link.

<Note>
  Removing or adding an authorized network on your CockroachDB Advanced cluster may take a few seconds to take effect.
</Note>

<Note>
  IPv6 addresses are currently not supported.
</Note>

To prevent denial-of-service attacks, brute force password attacks, and other forms of malicious activity, it is recommended to restrict your cluster network to allow access only from specific IP address ranges controlled by your organization, corresponding to, for example, your application deployments, hardened administrator access points, or disaster recovery pipelines.

### Add IP addresses to the allowlist

1. Navigate to your cluster's **Networking > IP Allowlist** tab.

   The **IP Allowlist** tab displays a list of authorized networks (i.e., an IP network allowlist) that can access the cluster.
2. If the network is not listed, authorize it:
   1. Click the **Add Network** button. The **Add Network** dialog displays.
   2. *(Optional)* Enter a **Network name**.
   3. From the **Network** dropdown, select:
      * **New Network** to authorize the network of your local machine or application deployment or another valid source. Enter the public IPv4 address of the source machine in the **Network** field. To add a range of source IP addresses, use the CIDR (Classless Inter-Domain Routing) notation. For a general introduction to IP routing, refer to [Digital Ocean—Understanding IP Addresses, Subnets, and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation).
      * **Current Network** to auto-populate your local machine's IP address.
      * **Public (Insecure)** to allow all networks, use `0.0.0.0/0`. Use this with caution as your cluster will be vulnerable to denial-of-service and brute force password attacks.
3. Select whether the network can connect to the cluster's **DB Console to monitor the cluster**, **CockroachDB Client to access databases**, or both.

   The DB Console is where you can observe your cluster's health and performance. For more information, see <InternalLink version="stable" path="ui-overview">DB Console Overview</InternalLink>.
4. Click **Apply**.

<a id="establish-gcp-vpc-peering-or-aws-privatelink" />

### Establish private connectivity

Private connectivity allows you to establish SQL access to a CockroachDB Advanced cluster entirely through cloud provider private infrastructure, without exposing the cluster to the public internet, affording enhanced security and performance.

* Clusters deployed on GCP can connect privately using [GCP Private Service Connect (PSC)](#gcp-private-service-connect) or [GCP VPC Peering](#vpc-peering). PSC allows you to connect your cluster directly to a VPC within your Google Cloud project, while VPC Peering allows you to peer your cluster's VPC in CockroachDB Cloud to a VPC within your Google Cloud project.
* Clusters deployed on AWS can connect privately using [AWS PrivateLink](#aws-privatelink), which allows you to connect your cluster to a VPC within your AWS account.
* Clusters deployed on Azure can connect privately using [Azure Private Link](#azure-private-link), which allows you to connect your cluster to a virtual network within your Azure tenant.

For more information, refer to <InternalLink path="network-authorization">Network authorization</InternalLink>.

<Tip>
  Private connectivity can be configured only after a cluster is created.
</Tip>

<InternalLink path="network-authorization">VPC Peering</InternalLink> and <InternalLink path="network-authorization">AWS PrivateLink</InternalLink> in CockroachDB Advanced clusters do **not** support connecting to a <InternalLink version="stable" path="changefeed-sinks#kafka">Kafka</InternalLink> sink's internal IP addresses for <InternalLink version="stable" path="change-data-capture-overview">changefeeds</InternalLink>. To connect to a Kafka sink from CockroachDB Advanced, it is necessary to expose the Kafka cluster's external IP address and open ports with firewall rules to allow access from the cluster.

#### GCP Private Service Connect

1. Navigate to your cluster's **Networking > Private endpoint** tab.
2. Click **Add a private endpoint**. Copy the value provided for **Target service**. Do not close this browser window.
3. In a new browser window, log in to Google Cloud Console, go to **Private Service Connect** section, and create a new endpoint in the same VPC as your application. For details, refer to [Create an endpoint](https://cloud.google.com/vpc/docs/configure-private-service-connect-services#create-endpoint) in the Google Cloud documentation.
   * Set **Target** to **Published service**.
   * Set **Target service** to the value you copied from CockroachDB Cloud Console. If the endpoint's configured target service does not match, validation will fail.
   * Provide a value for **Endpoint name**. You will need to provide this **Endpoint name** when connecting to the cluster using the command line, a connection string, or connection parameters.
   * If it is not enabled, enable the Service Directory API, click **Enable global access**, and create a namespace in each region where your cluster is deployed.
   * Click **Add endpoint**.
   * After the endpoint is created, copy the connection ID.
4. Return to the CockroachDB Cloud Console browser tab and click **Validate**.
5. Enter the endpoint's ID, then click **Validate**. CockroachDB Cloud attempts to connect to the endpoint's VPC and verifies that the target service matches the cluster. If validation fails, verify the endpoint's configuration, then try again. After validation succeeds, click **Complete** to finish creating the connection.
6. On the **Networking > Private endpoint** tab, verify that the connection status is **Available**.

<Tip>
  After validation succeeds for an endpoint, additional endpoints in the same VPC are automatically automatically accepted if they are configured with the cluster's target service ID. Additional VPCs must be added separately.
</Tip>

If you remove the endpoint from GCP or change its target service, the endpoint will be removed from the cluster automatically.

After the connection is established, you can use it to [connect to your cluster](#connect-to-your-cluster).

<a id="vpc-peering" />

#### GCP VPC Peering

For GKE, we recommend deploying your application to a VPC-native cluster that uses [alias IP addresses](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). If you are connecting from a [routes-based GKE cluster](https://cloud.google.com/kubernetes-engine/docs/how-to/routes-based-cluster) instead, you must [export custom routes](https://cloud.google.com/vpc/docs/vpc-peering#importing-exporting-routes). CockroachDB Cloud will import your custom routes by default.

1. Navigate to your cluster's **Networking > VPC Peering** tab.
2. Click **Set up a VPC peering connection**.
3. On the **Request a VPC peering connection** dialog, enter your [GCP Project ID](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
4. Enter your [GCP VPC network name](https://cloud.google.com/vpc/docs/using-vpc#viewing-networks).
5. In the **Connection name** field, enter a descriptive name for the VPC connection.
6. Click **Request Connection**.
7. Run the command displayed on the **Accept VPC peering connection request** window using [Google Cloud Shell](https://cloud.google.com/shell) or using the [gcloud command-line tool](https://cloud.google.com/sdk/gcloud).
8. On the **Networking** page, verify the connection status is **Available**.

After the connection is established, you can use it to [connect to your cluster](#connect-to-your-cluster).

<Note>
  Self-service VPC peering setup is not supported for CockroachDB Advanced clusters deployed before March 5, 2020. If your cluster was deployed before March 5, 2020, you will have to <InternalLink path="create-your-cluster">create a new cluster</InternalLink> with VPC peering enabled, then <InternalLink path="managed-backups">export your data</InternalLink> from the old cluster to the new cluster. If your cluster was deployed on or after March 5, 2020, it will be locked into CockroachDB Advanced's default IP range (`172.28.0.0/14`) unless you explicitly configured a different IP range during cluster creation.
</Note>

#### AWS PrivateLink

To establish an AWS PrivateLink connection, refer to <InternalLink path="aws-privatelink">Managing AWS PrivateLink for a cluster</InternalLink>. After the connection is established, you can use it to [connect to your cluster](#connect-to-your-cluster).

#### Azure Private Link

1. Navigate to your cluster's **Networking > Private endpoint** tab.
2. Click **Add a private endpoint**. Copy the value provided for **Alias**. Do not close this browser window.
3. In a new browser window, log in to Azure Console and create a new private endpoint for your cluster.
   * Set the connection method to “by resource ID or alias”.
   * Set the resource ID to the **Alias** you previously copied. For details, refer to [Create a private endpoint](https://learn.microsoft.com/azure/private-link/create-private-endpoint-portal?tabs=dynamic-ip) in the Azure documentation.

     After the private endpoint is created, view it, then click **Properties** and copy its Resource ID.

<Note>
  Copy the resource ID for the private endpoint you just created, not for the Private Link resource itself.
</Note>

Do not close this browser window.

4. Return to the CockroachDB Cloud Console browser tab and click **Next**.
5. Paste the resource ID for the Azure private endpoint, then click **Validate**. If validation fails, verify the resource ID and try again. If you encounter the error `This resource is invalid`, be sure that you are using the resource ID for the Azure private endpoint, rather than the resource ID for Azure Private Link itself.

   When validation succeeds, click **Next** to configure private DNS. Make a note of the Internal DNS Name. Do not close this browser window.
6. Return to the Azure Console. Go to the **Private DNS Zone** page and create private DNS records for your cluster in the\` region where you will connect privately.
   * Create a private DNS zone named with the Internal DNS Name you previously copied. Refer to [Quickstart: Create an Azure private DNS zone using the Azure portal](https://learn.microsoft.com/azure/dns/private-dns-getstarted-portal).
   * In the new DNS zone, create an `@` record with the Internal DNS Name you previously copied.
   * Click **Complete** to finish creating the DNS records.
7. Associate the new DNS zone with the private endpoint's virtual network. View the private endpoint's configuration, click **Virtual network links**, then click **Add**.
   * Name the link, then select the resource group and select the DNS zone you just created.
   * Enable auto-registration.
   * Click **OK**.

     For details, refer to [Link the virtual network](https://learn.microsoft.com/azure/dns/private-dns-getstarted-portal#link-the-virtual-network).
8. Return to the CockroachDB Cloud Console browser tab and click **Complete**.
9. On the **Networking** page, verify the connection status is **Available**.

## Connect to your cluster

1. In the top right corner of the CockroachDB Cloud Console, click **Connect**.

   The **Setup** page of the **Connect to cluster** dialog displays.
2. If you set up a private connection, select it to connect privately. Otherwise, click **IP Allowlist**.
3. Select the **SQL User**. If you have only one SQL user, it is automatically selected.

<Note>
  If you forget your SQL user's password, an <InternalLink path="authorization#organization-admin">Organization Admin</InternalLink> or a Cluster Admin on the cluster can change the password on the **SQL Users** page.
</Note>

4. Select the **Database**. If you have only one database, it is automatically selected.
5. For a multi-region cluster, select the **Region** to connect to. If you have only one region, it is automatically selected.
6. Click **Next**.

   The **Connect** page of the **Connection info** dialog displays.
7. In the dialog, select the tab for a connection method, then follow the instructions below for that method.

   You can connect to your cluster with any <InternalLink version="releases" path="release-support-policy#supported-versions">supported version</InternalLink> of the full CockroachDB binary or the <InternalLink version="stable" path="cockroach-sql">built-in SQL client</InternalLink>. To download the full binary and connect to a CockroachDB Advanced cluster, follow these steps.

<Tip>
  To download a supported version of the SQL shell instead of the full binary, visit [Releases](https://cockroachlabs.com/releases).
</Tip>

1. Select the **Command Line** tab.
2. If CockroachDB is not installed locally, copy the command to download and install it. In your terminal, run the command.
3. If the CA certificate for the cluster is not downloaded locally, copy the command to download it. In your terminal, run the command.
4. Copy the <InternalLink version="stable" path="cockroach-sql">`cockroach sql`</InternalLink> command, which will be used in the next step (and to connect to your cluster in the future). Click **Close**.
5. In your terminal, enter the copied `cockroach sql` command and connection string to start the <InternalLink version="stable" path="cockroach-sql">built-in SQL client</InternalLink>.
6. Enter the SQL user's password and enter.

<Danger>
  PostgreSQL connection URIs do not support special characters. If you have special characters in your password, you will have to [URL encode](https://www.w3schools.com/tags/ref_urlencode.ASP) them (e.g., `password!` should be entered as `password%21`) to connect to your cluster.
</Danger>

A welcome message displays:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
#

# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
```

You are now connected to the built-in SQL client, and can now run <InternalLink version="stable" path="sql-statements">CockroachDB SQL statements</InternalLink>.

To connect to your cluster from your application:

1. Select the **Connection string** tab.
2. If the CA certificate for the cluster is not downloaded locally, copy the command to download it. In your terminal, run the command.
3. Copy the connection string, which begins with `postgresql://`. This will be used to connect your application to CockroachDB Advanced.
4. Add your copied connection string to your application code. For information about connecting to CockroachDB Advanced with a <InternalLink version="stable" path="third-party-database-tools">supported client</InternalLink>, see <InternalLink version="stable" path="connect-to-the-database">Connect to a CockroachDB Cluster</InternalLink>.
5. Click **Close**.

PostgreSQL connection URIs do not support special characters. If you have special characters in your password, you will have to [URL encode](https://www.w3schools.com/tags/ref_urlencode.ASP) them (e.g., `password!` should be entered as `password%21`) to connect to your cluster.

For examples, see the following:

* <InternalLink version="stable" path="build-a-python-app-with-cockroachdb">Build a Python App with CockroachDB</InternalLink>
* <InternalLink version="stable" path="build-a-go-app-with-cockroachdb">Build a Go App with CockroachDB</InternalLink>
* <InternalLink version="stable" path="build-a-java-app-with-cockroachdb">Build a Java App with CockroachDB</InternalLink>

To connect to your cluster with a <InternalLink version="stable" path="third-party-database-tools">CockroachDB-compatible tool</InternalLink>:

1. If the CA certificate for the cluster is not downloaded locally, select the **Connection string** tab, then copy the command to download the CA certificate. In your terminal, run the command.
2. Select the **Connection parameters** tab.
3. Use the connection parameters provided in the dialog to connect to your cluster using a <InternalLink version="stable" path="third-party-database-tools">CockroachDB-compatible tool</InternalLink>.

| Parameter                   | Description                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| <code>{'{username}'}</code> | The <InternalLink path="managing-access#create-a-sql-user">SQL user</InternalLink> connecting to the cluster. |
| <code>{'{password}'}</code> | The password for the SQL user connecting to the cluster.                                                      |
| <code>{'{host}'}</code>     | The host on which the CockroachDB node is running.                                                            |
| <code>{'{port}'}</code>     | The port at which the CockroachDB node is listening.                                                          |
| <code>{'{database}'}</code> | The name of the (existing) database.                                                                          |

4. Click **Close**.

## What's next

* <InternalLink version="stable" path="build-a-python-app-with-cockroachdb-django">Build a "Hello, World" app</InternalLink>