Skip to main content
This page shows you how to connect to your CockroachDB Standard 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 .

​
Before you start

  • .
  • .
  • Understand

​
Authorize your network

By default, CockroachDB Standard 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. Standard clusters can accept connections via two types of authorized network:
  • Allowed IP address ranges on the internet.
  • Cloud-provider-specific peer networking options:
    • Google Cloud Platform (GCP) Private Service Connect (Preview)
    • Amazon Web Services (AWS) Privatelink
Removing or adding an authorized network on your CockroachDB Standard cluster may take a few seconds to take effect.
IPv6 addresses are currently not supported.
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 .
  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.
CockroachDB Standard is not yet available on Azure. For more information, refer to .
Private connectivity cannot be configured during cluster creation.
and in CockroachDB Advanced clusters do not support connecting to a sink’s internal IP addresses for . 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 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. After the connection is established, you can use it to connect to your cluster.
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 with VPC peering enabled, then 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’s default IP range (172.28.0.0/14) unless you explicitly configured a different IP range during cluster creation.

​
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.
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.
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. To establish an AWS PrivateLink connection, refer to . After the connection is established, you can use it to connect to your cluster.
  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.
Copy the resource ID for the private endpoint you just created, not for the Private Link resource itself.
Do not close this browser window.
  1. Return to the CockroachDB Cloud Console browser tab and click Next.
  2. 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.
  3. 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.
  4. 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.
  5. Return to the CockroachDB Cloud Console browser tab and click Complete.
  6. On the Networking page, verify the connection status is Available.

​
Connect to your cluster

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.
If you forget your SQL user’s password, an or a Cluster Admin on the cluster can change the password on the SQL Users page.
  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 have 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.
  1. If you need to download the CA certificate, first set Select option/language to General Connection String and expand the Download CA Cert section. In the Download CA Cert section of the dialog, select your operating system, and use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. Select the Parameters only option of the Select option/language dropdown.
  3. Use the connection parameters provided in the dialog to connect to your cluster using a .
ParameterDescription
The connecting to the cluster.
The host on which the CockroachDB node is running.
The port at which the CockroachDB node is listening.
The name of the (existing) database.
Additionally, you will need the SQL user’s . If you forget your SQL user’s password, an or a Cluster Admin on the cluster can change the password on the SQL Users page. You can connect to your cluster with any of the full CockroachDB binary or the .
  1. Select CockroachDB Client from the Select option/language dropdown.
  2. In the Download the latest CockroachDB Client section of the dialog, select your operating system, and use the command provided to install the latest downloadable version of CockroachDB on your local system.
  3. Copy the command and connection string provided in the Connect dialog, which will be used in the next step (and to connect to your cluster in the future).
  4. In your terminal, enter the copied cockroach sql command and connection string to start the .
  5. Enter the SQL user’s password and hit enter. 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:
    You are now connected to the built-in SQL client, and can now run .
After the connection is established, you can use it to connect to your cluster. 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 with VPC peering enabled, then 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’s default IP range (172.28.0.0/14) unless you explicitly configured a different IP range during cluster creation.

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

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. If you forget your SQL user’s password, an or a Cluster Admin on the cluster can change the password on the SQL Users page.
  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 have 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.
  1. If you need to download the CA certificate, first set Select option/language to General Connection String and expand the Download CA Cert section. In the Download CA Cert section of the dialog, select your operating system, and use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. Select the Parameters only option of the Select option/language dropdown.
  3. Use the connection parameters provided in the dialog to connect to your cluster using a .
ParameterDescription
The connecting to the cluster.
The host on which the CockroachDB node is running.
The port at which the CockroachDB node is listening.
The name of the (existing) database.
Additionally, you will need the SQL user’s . If you forget your SQL user’s password, an or a Cluster Admin on the cluster can change the password on the SQL Users page. You can connect to your cluster with any of the full CockroachDB binary or the .
  1. Select CockroachDB Client from the Select option/language dropdown.
  2. In the Download the latest CockroachDB Client section of the dialog, select your operating system, and use the command provided to install the latest downloadable version of CockroachDB on your local system.
  3. Copy the command and connection string provided in the Connect dialog, which will be used in the next step (and to connect to your cluster in the future).
  4. In your terminal, enter the copied cockroach sql command and connection string to start the .
  5. Enter the SQL user’s password and hit enter. 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:
    You are now connected to the built-in SQL client, and can now run .
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. Refer to .
  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 them (e.g., password! should be entered as password%21) to connect to your cluster. For examples, see the following:
After the connection is established, you can use it to connect to your cluster. 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 with VPC peering enabled, then 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’s default IP range (172.28.0.0/14) unless you explicitly configured a different IP range during cluster creation.

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

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. If you forget your SQL user’s password, an or a Cluster Admin on the cluster can change the password on the SQL Users page.
  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 have 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.
  1. If you need to download the CA certificate, first set Select option/language to General Connection String and expand the Download CA Cert section. In the Download CA Cert section of the dialog, select your operating system, and use the command provided to download the CA certificate to the default PostgreSQL certificate directory on your machine.
  2. Select the Parameters only option of the Select option/language dropdown.
  3. Use the connection parameters provided in the dialog to connect to your cluster using a .
ParameterDescription
The connecting to the cluster.
The host on which the CockroachDB node is running.
The port at which the CockroachDB node is listening.
The name of the (existing) database.
Additionally, you will need the SQL user’s . If you forget your SQL user’s password, an or a Cluster Admin on the cluster can change the password on the SQL Users page. You can connect to your cluster with any of the full CockroachDB binary or the .
  1. Select CockroachDB Client from the Select option/language dropdown.
  2. In the Download the latest CockroachDB Client section of the dialog, select your operating system, and use the command provided to install the latest downloadable version of CockroachDB on your local system.
  3. Copy the command and connection string provided in the Connect dialog, which will be used in the next step (and to connect to your cluster in the future).
  4. In your terminal, enter the copied cockroach sql command and connection string to start the .
  5. Enter the SQL user’s password and hit enter. 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:
    You are now connected to the built-in SQL client, and can now run .
To connect to your cluster with a :
  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 .
ParameterDescription
The connecting to the cluster.
The password for the SQL user connecting to the cluster.
The host on which the CockroachDB node is running.
The port at which the CockroachDB node is listening.
The name of the (existing) database.
  1. Click Close.

​
What’s next