Connect to Your CockroachCloud Cluster

This page shows you how to connect to your CockroachCloud cluster.

Step 1. Authorize your network

CockroachCloud requires you to authorize the networks that can access the cluster to prevent denial-of-service and brute force password attacks:

• In a development environment, you need to authorize your application server’s network and your local machine’s network. If you change your location, you need to authorize the new location’s network, or else the connection from that network will be rejected.
• In a production environment, you need to authorize your application server’s network.
• If you have a GCP cluster, you can set up and authorize a VPC peered network.
• If you have an AWS cluster, you can set up an AWS PrivateLink connection.

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

3. Click the Add Network button.

   The Add Network dialog displays.

4. (Optional) Enter a Network name.

5. From the Network dropdown, select:

   • New Network to authorize your local machine's network or application server's network. Enter the public IPv4 address of the machine in the Network field.
   • 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.
   Note:

   IPv6 addresses are currently not supported.

   To add a range of IP addresses, use the CIDR (Classless Inter-Domain Routing) notation. The CIDR notation is constructed from an IP address (e.g., 192.168.15.161), a slash (/), and a number (e.g., 32). The number is the count of leading 1-bits in the network identifier. In the example above, the IP address is 32-bits and the number is 32, so the full IP address is also the network identifier. For more information, see Digital Ocean's Understanding IP Addresses, Subnets, and CIDR Notation for Networking.

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

7. Click Apply.

Establish VPC Peering or AWS PrivateLink

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

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 modal, 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 Active.

1. Navigate to your cluster's Networking > PrivateLink tab.
2. Click Set up a PrivateLink connection.
3. If you have a multi-region cluster, select the region to create a connection in. Skip this step if you have a single-region cluster.
4. Use the Service Name provided in the dialog to create an AWS endpoint in the AWS console.
5. Click Next.
6. Paste the Endpoint ID you created into the VPC Endpoint ID field.
7. Click Verify to verify the ID.
8. Click Next to continue to the third step.
9. Return to the AWS console to enable private DNS.
10. Click Complete.
11. On the Networking page, verify the connection status is Available.

Step 2. Create a SQL user

1. Navigate to your cluster's SQL Users page.

   

2. Click the Add User button in the top right corner.

   The Add User dialog displays.

3. Enter a Username and Password.

4. Click Save.

   Currently, all new users are created with full privileges. For more information and to change the default settings, see Granting privileges and Using roles.

Step 3. Select a connection method

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

   The Connect dialog displays with IP Allowlist selected by default.

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

3. From the User dropdown, select the SQL user you created in Step 2. Create a SQL user.

4. From the Region dropdown, select the region closest to where your client or application is running.

5. From the Database dropdown, select the database you want to connect to.

   The default database is defaultdb. For more information, see Default databases.

6. Click Next.

7. Select a connection method (the instructions below will adjust accordingly):

   Command line Connection string Connection parameters

Step 4. Connect to your cluster

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

1. Click the name of the <cluster_name>-ca.crt to download the CA certificate to your local machine.

   Alternatively, you can set sslmode=require. This is less secure than using a CA certificate and should not be used with sensitive data.

2. Create a certs directory on your local machine:

   $ mkdir certs
   

3. Move the downloaded <cluster_name>-ca.crt file to the certs directory:

   $ mv /path/to/cc-ca.crt /path/to/certs
   

   For example:

   $ mv /Users/maxroach/Downloads/<cluster_name>-ca.crt /Users/maxroach/certs
   

4. If you have not done so already, install the CockroachDB binary.

5. 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).

6. In your terminal, enter the copied cockroach sql command and connection string to start the built-in SQL client.

   Be sure to replace the <your_certs_ directory> placeholder with the path to the certs directory you created earlier.

7. Enter the SQL user's password and hit enter.

   Note:

   If you forget your SQL user's password, a Console Admin can change the password on the SQL Users page.

   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:

1. Click the name of the <cluster_name>-ca.crt to download the CA certificate to your local machine.

2. Create a certs directory on your local machine:

   $ mkdir certs
   

3. Move the downloaded <cluster_name>-ca.crt file to the certs directory:

   $ mv /path/to/cc-ca.crt /path/to/certs
   

   For example:

   $ mv /Users/maxroach/Downloads/<cluster_name>-ca.crt /Users/maxroach/certs
   

4. Copy the connection string provided in the Console, which will be used to connect your application to CockroachCloud.

5. Add your copied connection string to your application code.

   Be sure to replace the <your_certs_ directory> placeholder with the path to the certs directory you created earlier.

   Note:

   If you forget your SQL user's password, a Console Admin can change the password on the SQL Users page.

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, use the connection parameters provided in the Console.

What's next

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