Connect to a CockroachDB Advanced Cluster

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 built-in SQL client.

Before you start

• Create a cluster.
• Create a SQL user.
• Understand Network Authorization for CockroachDB Cloud Clusters

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.

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.
      • 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 DB Console Overview.

4. Click Apply.

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) or GCP 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, 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, which allows you to connect your cluster to a virtual network within your Azure tenant.

For more information, refer to Network authorization.

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 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. This is not used by CockroachDB Cloud.
   • 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.

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.

GCP VPC Peering

For GKE, we recommend deploying your application to a VPC-native cluster that uses alias IP addresses. If you are connecting from a routes-based GKE cluster instead, you must export custom 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.
4. Enter your GCP VPC network name.
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 or using the gcloud command-line tool.
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.

AWS PrivateLink

To establish an AWS PrivateLink connection, refer to Managing AWS PrivateLink for a cluster. After the connection is established, you can use it to 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 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.

   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.
   • 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.

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 Org Administrator or a Cluster Admin on the cluster can change the password on the SQL Users page.

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.

   Command line Connection string Connection parameters

You can connect to your cluster with any supported version of the full CockroachDB binary or the built-in SQL client. 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.

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 cockroach sql 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 built-in SQL client.

6. Enter the SQL user's password and enter.

   Warning:

   PostgreSQL connection URIs do not support special characters. If you have special characters in your password, you will have to URL encode them (e.g., password! should be entered as password%21) to connect to your cluster.

   A welcome message displays:

   #
   # 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 CockroachDB SQL statements.

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 supported client, see Connect to a CockroachDB Cluster.
5. Click Close.

Warning:

PostgreSQL connection URIs do not support special characters. If you have special characters in your password, you will have to URL encode them (e.g., password! should be entered as password%21) to connect to your cluster.

For examples, see the following:

• Build a Python App with CockroachDB
• Build a Go App with CockroachDB
• Build a Java App with CockroachDB

To connect to your cluster with a CockroachDB-compatible tool:

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 CockroachDB-compatible tool.

   Parameter	Description
   {username}	The SQL user connecting to the cluster.
   {password}	The password for the SQL user connecting to the cluster.
   {host}	The host on which the CockroachDB node is running.
   {port}	The port at which the CockroachDB node is listening.
   {database}	The name of the (existing) database.

4. Click Close.

What's next

• Build a "Hello, World" app
• Deploy a Python To-Do App with Flask, Kubernetes, and CockroachDB Cloud