Connect to a CockroachDB Dedicated Cluster

On this page Carat arrow pointing down

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

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

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

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

  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.

Connect to your cluster

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

    The Setup page of the Connect to cluster dialog displays.

  2. If you set up a private connection, click AWS PrivateLink (for clusters deployed in AWS) or VPC Peering (for clusters deployed in GCP) 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 multiregion 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.

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

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 Dedicated.
  4. Add your copied connection string to your application code. For information about connecting to CockroachDB Serverless 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:

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


Yes No
On this page

Yes No