Connect to a CockroachDB Cloud Dedicated Cluster

On this page

This page shows you how to connect to your CockroachDB Dedicated 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 Dedicated 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. Dedicated 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) VPC Peering
- Amazon Web Services (AWS) Private link

Note:

Removing or adding an authorized network on your CockroachDB Dedicated cluster may take a few seconds to take effect.

Note:

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

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.
Check if the current network has been authorized. If not, proceed with the following steps.
Click the Add Network button.

The Add Network dialog displays.
(Optional) Enter a Network name.
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.
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.
Click Apply.

Establish GCP VPC Peering or AWS PrivateLink

GCP VPC Peering and AWS PrivateLink allow customers to establish SQL access to their clusters entirely through cloud provider private infrastructure, without exposure to the public internet, affording enhanced security and performance.

VPC peering is available only for GCP clusters, and AWS PrivateLink is available for AWS clusters.

To configure VPC Peering or PrivateLink, you create the private connection in your cloud provider, then configure your cluster to allow connections from your VPC or private endpoint. For more information, refer to Network Authorization for CockroachDB Dedicated clusters: GCP VPC Peering and Network Authorization for CockroachDB Dedicated clusters: AWS PrivateLink.

AWS PrivateLink can be configured only after the cluster is created. For detailed instructions, refer to Managing AWS PrivateLink for a cluster. To configure VPC Peering, continue to the VPC Peering section below.

Azure Private Link is not yet available for CockroachDB Dedicated on Azure.

Note:

VPC Peering and AWS PrivateLink in CockroachDB Dedicated clusters do not support connecting to a Kafka sink's internal IP addresses for changefeeds. To connect to a Kafka sink from CockroachDB Dedicated, it is necessary to expose the Kafka cluster's external IP address and open ports with firewall rules to allow access from a CockroachDB Dedicated cluster.

VPC Peering

Navigate to your cluster's Networking > VPC Peering tab.
Click Set up a VPC peering connection.
On the Request a VPC peering connection dialog, enter your GCP Project ID.
Enter your GCP VPC network name.
In the Connection name field, enter a descriptive name for the VPC connection.
Click Request Connection.
Run the command displayed on the Accept VPC peering connection request window using Google Cloud Shell or using the gcloud command-line tool.
On the Networking page, verify the connection status is Available.

Select a connection method

In the top right corner of the Console, click the Connect button.

The Connect dialog displays with IP Allowlist selected by default.
Select a Network Security option:

You can use the IP Allowlist option if you have already added an IP address to your allowlist.

For AWS clusters, you can select AWS PrivateLink if you have already established a PrivateLink connection.

For GCP clusters, you can select VPC Peering if you have already:
- Enabled VPC peering while creating your cluster
- Established a VPC Peering connection
From the User dropdown, select the SQL user you created.
From the Region dropdown, select the region closest to where your client or application is running.
From the Database dropdown, select the database you want to connect to.

The default database is defaultdb. For more information, see Default databases.
Click Next.
Select a connection method (the instructions below will adjust accordingly):

Connect to your cluster

To connect to your cluster with the built-in SQL client:

Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.
If you have not done so already, run the first command in the dialog to install the CockroachDB binary in /usr/local/bin, which is usually in the system PATH. To install it into a different location, replace /usr/local/bin/.
```
curl https://binaries.cockroachdb.com/cockroach-v23.1.13.darwin-10.9-amd64.tgz | tar -xJ && sudo cp -i cockroach-v23.1.13.darwin-10.9-amd64/cockroach /usr/local/bin/
```
If you have not done so already, run the first command in the dialog to install the CockroachDB binary in /usr/local/bin, which is usually in the system PATH. To install it into a different location, replace /usr/local/bin/.
```
curl https://binaries.cockroachdb.com/cockroach-v23.1.13.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v23.1.13.linux-amd64/cockroach /usr/local/bin/
```
If you have not done so already, use PowerShell to run the first command in the dialog, which is a PowerShell script that installs the CockroachDB binary and adds its location in the system PATH:
```
$ErrorActionPreference = "Stop"; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;$ProgressPreference = 'SilentlyContinue'; $null = New-Item -Type Directory -Force $env:appdata/cockroach; Invoke-WebRequest -Uri https://binaries.cockroachdb.com/cockroach-v23.1.13.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Force -Path cockroach.zip; Copy-Item -Force "cockroach/cockroach-v23.1.13.windows-6.2-amd64/cockroach.exe" -Destination $env:appdata/cockroach; $Env:PATH += ";$env:appdata/cockroach"
```
We recommend adding ;$env:appdata/cockroach to the PATH variable for your system environment so you can run cockroach commands from any shell. See Microsoft's environment variable documentation for more information.
In your terminal, run the second command from the dialog to create a new certs directory on your local machine and download the CA certificate to that directory:
```
curl --create-dirs -o ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
```
Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.
```
curl --create-dirs -o ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
```
Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.
```
mkdir -p $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt
```
Your cert file will be downloaded to %APPDATA%/CockroachCloud/certs/<cluster-name>-ca.crt.
If you established a private connection using VPC Peering or AWS PrivateLink, click VPC Peering or PrivateLink to connect privately.
Copy the cockroach sql command and connection string provided in the Console, which will be used in the next step (and to connect to your cluster in the future):
```
cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
```
```
cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
```
```
cockroach sql --url "postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert=$env:appdata\CockroachCloud\certs\$<cluster-name>-ca.crt"
```
Where:
- <user> is the SQL user. By default, this is your CockroachDB Cloud account username.
- <cluster-name>-<short-id> is the short name of your cluster plus the short ID. For example, funny-skunk-3ab.
- <cluster-id> is a unique string used to identify your cluster when downloading the CA certificate. For example, 12a3bcde-4fa5-6789-1234-56bc7890d123.
- <region> is the region in which your cluster is running. If you have a multi-region cluster, you can choose any of the regions in which your cluster is running. For example, aws-us-east-1.
- <database> is the name for your database. For example, defaultdb.
You can find these settings in the Connection parameters tab of the Connection info dialog.
In your terminal, enter the copied cockroach sql command and connection string to start the built-in SQL client.
Enter the SQL user's password and hit 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.

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. Refer to: Change a User's password.

You are now connected to the built-in SQL client, and can now run CockroachDB SQL statements.

To connect to your cluster with your application, use the connection string provided in the Console:

Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.
In your terminal, run the first command from the dialog to create a new certs directory on your local machine and download the CA certificate to that directory:
```
curl --create-dirs -o ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
```
Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.
```
curl --create-dirs -o ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
```
Your cert file will be downloaded to ~/Library/CockroachCloud/certs/<cluster-name>-ca.crt.
```
mkdir -p $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata/CockroachCloud/certs/<cluster-name>-ca.crt
```
Your cert file will be downloaded to %APPDATA%/CockroachCloud/certs/<cluster-name>-ca.crt.
If you established a private connection using VPC Peering or AWS PrivateLink, click VPC Peering or PrivateLink to connect privately.

Copy the connection string provided in the Console, which will be used to connect your application to CockroachDB Cloud:

'postgresql://<user>@<cluster-name>-<short-id>.<region>.<host>:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'

'postgresql://<user>@<cluster-name>-<short-id>.<region>.<host>:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'

"postgresql://<user>@<cluster-name>-<short-id>.<region>.<host>:26257/<database>?sslmode=verify-full&sslrootcert=$env:appdata\CockroachCloud\certs\$<cluster-name>-ca.crt"

Add your copied connection string to your application code.

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.

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.

For examples, see the following:

To connect to your cluster with a CockroachDB-compatible tool, use the connection parameters provided in the Console.

From the cluster's Details page, click Connect.
If you established a private connection using VPC Peering or AWS PrivateLink, click VPC Peering or PrivateLink to connect privately.
Copy the connection string and provide it to the CockroachDB-compatible tool.

What's next

Was this helpful?

Cockroach
University

Docs Hub

Connect to a CockroachDB Cloud Dedicated Cluster

Before you start

Authorize your network

Add IP addresses to the allowlist

Establish GCP VPC Peering or AWS PrivateLink

VPC Peering

Select a connection method

Connect to your cluster

What's next

Cockroach University

Docs Hub

Cockroach University

Docs Hub

Connect to a CockroachDB Cloud Dedicated Cluster

Before you start

Authorize your network

Add IP addresses to the allowlist

Establish GCP VPC Peering or AWS PrivateLink

VPC Peering

Select a connection method

Connect to your cluster

What's next

Cockroach
University

Cockroach
University