Connect to Your CockroachCloud Cluster

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

Before you start

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.
  • 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-v21.1.9.darwin-10.9-amd64.tgz | tar -xJ && cp -i cockroach-v21.1.9.darwin-10.9-amd64/cockroach /usr/local/bin/
    

    icon/buttons/copy
    curl https://binaries.cockroachdb.com/cockroach-v21.1.9.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v21.1.9.linux-amd64/cockroach /usr/local/bin/
    
    icon/buttons/copy
    $ErrorActionPreference = "Stop"; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; $ProgressPreference = 'SilentlyContinue'; mkdir -p $env:appdata/cockroach; Invoke-WebRequest -Uri https://binaries.cockroachdb.com/cockroach-v21.1.9.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Path cockroach.zip; Copy-Item cockroach/cockroach-v21.1.9.windows-6.2-amd64/cockroach.exe -Destination $env:appdata/cockroach; $Env:PATH += ";$env:appdata/cockroach"
    
  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>.<host>: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>.<host>: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>.<host>:26257/<database>?sslmode=verify-full&sslrootcert=$env:appdata\CockroachCloud\certs\$<cluster-name>-ca.crt"
    
  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, 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. 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 CockroachCloud.

    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, a Console Admin 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.

Note:

For most tools, the full name of your database should be in the format <cluster-name>-<tenant-id>.<database>.

What's next

YesYes NoNo