Skip to main content
This page shows you how to connect to your CockroachDB Cloud cluster, including configuring network authorization and using connection strings with SQL clients and applications.

​
Before You Start

Before connecting to your cluster, you need to:

​
Authorize Your Network

By default, CockroachDB Cloud clusters restrict network access for security. You must authorize networks before connecting.

​
Add IP Allowlist Entry

1

Navigate to Networking

  1. Select your cluster from the Clusters page
  2. Click Networking in the left navigation
  3. Click IP Allowlist tab
2

Add Network

Click Add Network and choose:
  • Current Network: Automatically adds your current IP
  • Custom: Specify an IP address or CIDR range
3

Configure Access

  1. Give the entry a descriptive name
  2. Select what this network can access:
    • CockroachDB Client: Allow SQL connections
    • DB Console: Allow DB Console access (Advanced only)
  3. Click Apply
Development: You can use 0.0.0.0/0 to allow all networks, but this is not recommended for production.

​
IP Allowlist Limits

Cluster TypeMaximum Rules
Basic50
Standard50
Advanced (AWS)20
Advanced (GCP/Azure)200
Contact Support if you need more allowlist rules.

​
Establish Private Connectivity

For enhanced security and performance, use private connectivity to connect your cluster without exposing it to the public internet. Available for Standard and Advanced clusters on AWS.
1

Navigate to Private Endpoints

Go to Networking > Private endpoint tab
2

Add Private Endpoint

Click Add a private endpoint and copy the Service Name
3

Create AWS Endpoint

In AWS Console:
  1. Navigate to VPC > Endpoints
  2. Create endpoint with the Service Name
  3. Select your VPC and subnets
  4. Copy the Endpoint ID
4

Validate in Cloud Console

Return to CockroachDB Cloud Console:
  1. Click Validate
  2. Enter the Endpoint ID
  3. Click Validate to complete setup

​
GCP Private Service Connect

Available for Standard and Advanced clusters on GCP.
1

Get Target Service

Navigate to Networking > Private endpoint and copy the Target Service ID
2

Create GCP Endpoint

In Google Cloud Console:
  1. Go to Private Service Connect
  2. Create endpoint in the same VPC as your application
  3. Set Target to Published service
  4. Enter the Target Service ID
  5. Enable global access if multi-region
3

Complete Connection

Return to Cloud Console and click Validate to confirm the connection

​
GCP VPC Peering

Legacy option for GCP clusters. PSC is recommended for new deployments.
VPC Peering requires configuration during cluster creation. Contact Support to set up VPC Peering for existing clusters.

​
Connect to Your Cluster

Once you’ve authorized your network, you can connect to your cluster.

​
Get Connection Information

1

Open Connect Dialog

Click Connect in the top right corner of your cluster’s page
2

Select Connection Type

Choose how you want to connect:
  • CockroachDB Client: Command-line SQL client
  • Connection string: For application code
  • Connection parameters: Individual parameters
3

Select SQL User

Select the SQL user you’ll connect as (or create a new one)
4

Select Network

Choose your connection method:
  • IP Allowlist: Public internet connection
  • Private endpoint: Private connectivity (if configured)

​
Using CockroachDB SQL Client

1

Download the Client

Follow the instructions in the Connect dialog to download the CockroachDB binary for your OS.
2

Download CA Certificate

Download the cluster’s CA certificate to verify the server identity:
curl --create-dirs -o ~/.postgresql/root.crt \
'https://cockroachlabs.cloud/clusters/{cluster-id}/cert'
3

Connect

Copy and run the cockroach sql command from the Connect dialog:
cockroach sql --url "postgresql://user@host:26257/defaultdb?sslmode=verify-full&sslrootcert=$HOME/.postgresql/root.crt"

​
Using a Connection String

For application connections, use the connection string provided: 
import psycopg2
import os

# Connection string format:
# postgresql://user:password@host:26257/database?sslmode=verify-full

conn = psycopg2.connect(
    os.environ['DATABASE_URL']
)

cursor = conn.cursor()
cursor.execute('SELECT version()')
print(cursor.fetchone())

​
Using Connection Parameters

For tools that require individual parameters:
ParameterDescriptionExample
HostCluster hostnamecluster-name.cloud.cockroachlabs.cloud
PortAlways 2625726257
DatabaseDatabase namedefaultdb
UsernameSQL usermyuser
PasswordSQL user password(from SQL user creation)
SSL Modeverify-full (required)verify-full
CA CertificatePath to root cert~/.postgresql/root.crt

​
Connection String Components

Understanding the connection string format: 
postgresql://user:password@host:26257/database?sslmode=verify-full&sslrootcert=path/to/cert
  • postgresql:// - Protocol
  • user:password - Credentials
  • host:26257 - Cluster address and port
  • /database - Target database
  • sslmode=verify-full - Encryption and verification mode
  • sslrootcert=... - CA certificate path
Security Best Practices:
  • Always use sslmode=verify-full to prevent MITM attacks
  • Never commit passwords to version control
  • Use environment variables for connection strings
  • Rotate SQL user passwords regularly

​
SSL Mode Settings

SSL ModeEncryptionServer VerificationRecommended
requireYesNoNo (testing only)
verify-fullYesYesYes (production)
CockroachDB Cloud requires verify-full for production use to:
  • Encrypt data in transit
  • Verify server identity
  • Prevent man-in-the-middle attacks

​
Special Characters in Passwords

If your SQL user password contains special characters, you must URL-encode them:
CharacterEncoded
@%40
#%23
$%24
%%25
&%26
/%2F
Example: 
Password: p@ss#word
Encoded: p%40ss%23word

​
Troubleshooting

​
Connection Refused

Cause: Your IP address is not in the allowlist. Solution: Add your IP address to the allowlist under Networking > IP Allowlist.

​
Certificate Verification Failed

Cause: Missing or incorrect CA certificate. Solution: Download the CA certificate from the Connect dialog and verify the path in your connection string.

​
Authentication Failed

Cause: Incorrect username or password. Solution: Verify credentials. A Cluster Admin can reset passwords on the SQL Users page.

​
Connection Timeout

Causes:
  • Firewall blocking port 26257
  • Incorrect hostname
  • Network connectivity issues
Solutions:
  • Check firewall rules
  • Verify hostname from Connect dialog
  • Test network connectivity

​
Connection Pooling

For production applications, use connection pooling to:
  • Reduce connection overhead
  • Improve performance
  • Handle connection failures
Most drivers and frameworks include built-in connection pooling: 
from sqlalchemy import create_engine
from sqlalchemy.pool import QueuePool

engine = create_engine(
    os.environ['DATABASE_URL'],
    poolclass=QueuePool,
    pool_size=5,
    max_overflow=10
)
Recommended Settings:
  • Pool size: 5-20 connections per application instance
  • Idle timeout: 30 seconds
  • Connection timeout: 2 seconds
  • Maximum lifetime: 30 minutes

​
Next Steps

Build an Application

Build a sample app with your preferred language

Learn SQL

Learn CockroachDB SQL syntax

Manage SQL Users

Create and manage SQL users

Network Security

Learn about network security

Build docs developers (and LLMs) love

Get started for freeTalk to us