Connect to Your CockroachDB Cloud Cluster

On this page Carat arrow pointing down

This page shows you how to connect to your CockroachDB Dedicated cluster.

Before you start

Step 1. Authorize your network

CockroachDB Dedicated 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.
  • You should use PrivateLink or VPC peering if you need to allowlist more than 20 IP addresses, if your servers’ IP addresses are not static, or if you want to limit your cluster's exposure to the public internet.

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.

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

  3. From the User dropdown, select the SQL user you created.

  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):

Step 3. Connect to your cluster

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

  1. Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.

  2. If you have not done so already, run the first command in the dialog to install the CockroachDB binary and copy it into the PATH:

    icon/buttons/copy 
    curl https://binaries.cockroachdb.com/cockroach-v22.2.8.darwin-10.9-amd64.tgz | tar -xJ && cp -i cockroach-v22.2.8.darwin-10.9-amd64/cockroach /usr/local/bin/

    icon/buttons/copy 
    curl https://binaries.cockroachdb.com/cockroach-v22.2.8.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v22.2.8.linux-amd64/cockroach /usr/local/bin/
    icon/buttons/copy 
    $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-v22.2.8.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Force -Path cockroach.zip; Copy-Item -Force "cockroach/cockroach-v22.2.8.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.

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

    icon/buttons/copy 
    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.

    icon/buttons/copy 
    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.

    icon/buttons/copy 
    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.

  4. 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):

    icon/buttons/copy 
    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'

    icon/buttons/copy 
    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'
    icon/buttons/copy 
    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.

  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.

    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:

  1. Select Mac, Linux, or Windows to adjust the commands used in the next steps accordingly.

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

    icon/buttons/copy 
    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.

    icon/buttons/copy 
    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.

    icon/buttons/copy 
    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.

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

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

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

What's next


Yes No
On this page

Yes No

Product

Resources

Learn

Support Channels

Company

Get developer news