Connect to a CockroachCloud Free (beta) 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.

   Mac Linux Windows

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:

   curl https://binaries.cockroachdb.com/cockroach-v21.1.7.darwin-10.9-amd64.tgz | tar -xJ && cp -i cockroach-v21.1.7.darwin-10.9-amd64/cockroach /usr/local/bin/
   

   curl https://binaries.cockroachdb.com/cockroach-v21.1.7.linux-amd64.tgz | tar -xz && sudo cp -i cockroach-v21.1.7.linux-amd64/cockroach /usr/local/bin/
   

   $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.7.windows-6.2-amd64.zip -OutFile cockroach.zip; Expand-Archive -Path cockroach.zip; Copy-Item cockroach/cockroach-v21.1.7.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.

   curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
   

   Your cert file will be downloaded to ~/.postgres/root.crt.

   curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
   

   Your cert file will be downloaded to ~/.postgres/root.crt.

   mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata\.postgresql\root.crt
   

   Your cert file will be downloaded to %APPDATA%/.postgres/root.crt.

4. Copy the cockroach sql command and connection string provided in the Connect modal, which will be used in the next step (and to connect to your cluster in the future).

   cockroach sql --url 'postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
   

   cockroach sql --url 'postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
   

   cockroach sql --url "postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=$env:appdata/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>"
   

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.

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

   Mac Linux Windows

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.

   curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
   

   Your cert file will be downloaded to ~/.postgres/root.crt.

   curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
   

   Your cert file will be downloaded to ~/.postgres/root.crt.

   mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata\.postgresql\root.crt
   

   Your cert file will be downloaded to %APPDATA%/.postgres/root.crt.

3. Copy the connection string provided in the Connect modal, which will be used to connect your application to CockroachCloud Free (beta).

   'postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
   

   'postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>'
   

   "postgresql://<user>@<free-tier-host>.<region>.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=$env:appdata/.postgresql/root.crt&options=--cluster=<cluster-name>-<tenant-id>"
   

4. Add your copied connection string to your application code.

   Note:

   If you forget your SQL user's password, a Console Admin 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
• Build a C++ App with CockroachDB

To connect to your cluster with a CockroachDB-compatible tool, use the connection parameters provided in the Console.