Connect to a CockroachDB Standard Cluster

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 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 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:
  • Amazon Web Services (AWS) 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. 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 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.

Establish AWS PrivateLink

AWS PrivateLink allows 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.

To configure PrivateLink, you create the private connection in your cloud provider, then configure your cluster to allow connections from your private endpoint. For more information, refer to Network Authorization for CockroachDB Standard 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.

Connect to your cluster

1. Select your cluster to navigate to its Overview page.

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

   The Connect to cluster dialog displays.

3. (Optional) If you have multiple SQL users or databases, you can:

   • Select the SQL user you want to connect with from the SQL user dropdown.
   • Select the database you want to connect to from the Database dropdown.

4. Select a connection method from the Select option / Language dropdown (the instructions below will adjust accordingly):

   Command line General connection string Connection parameters

1. In the Download CA Cert (Required only once) 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. Copy the connection string provided in the General connection string section of the dialog, which will be used to connect your application to CockroachDB Standard.
3. Add your copied connection string to your application code. For information about connecting to CockroachDB Standard with a supported client, refer to Connect to a CockroachDB Cluster.

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 connection examples and code snippets in your language, see the following:

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

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

   Parameter	Description
   {username}	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.

Additionally, you will need the SQL user's password. 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.

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 Standard cluster, follow these steps.

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

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

   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.

What's next

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