Connect to a CockroachDB Cluster

This page documents the required connection configuration for fully-supported third-party tools. For a list of all supported cluster connection parameters, see the cockroach Connection Parameters. For a list of community-supported third-party tools, see Third-Party Tools Supported by the Community. CockroachDB supports both native drivers and the PostgreSQL wire protocol. Most client drivers and ORM frameworks connect to CockroachDB like they connect to PostgreSQL.

Step 1. Select your deployment

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

To connect to a CockroachDB Cloud cluster, you need a general connection string or connection parameters, which include the username, host, database, and port. To find these, open the Connect dialog for your cluster in the CockroachDB Cloud Console and select either General connection string or Parameters only as the option.

Step 2. Select your language and driver

JavaScript/TypeScript
Python
Go
Java
Ruby

node-postgres
Sequelize
TypeORM
Prisma

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

The connection information shown on this page uses client certificate and key authentication to connect to a secure, CockroachDB self-hosted cluster.To connect to a CockroachDB self-hosted cluster with client certificate and key authentication, you must first generate server and client certificates.For instructions on starting a secure cluster, see Start a Local Cluster (Secure).

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

$env:DATABASE_URL = "{connection string}"

Connect to the cluster

To connect to CockroachDB with node-postgres, create a new Client object with a connection string.For example:

const { Client } = require('pg')

const client = new Client(process.env.DATABASE_URL)

client.connect()

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.For more information about connecting with node-postgres, see the official node-postgres documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

$env:DATABASE_URL = "{connection string}"

Connect to the cluster

To connect to CockroachDB with Sequelize, create a Sequelize object with the CockroachDB Sequelize adapter.For example:

const Sequelize = require("sequelize-cockroachdb");

const connectionString = process.env.DATABASE_URL
const sequelize = new Sequelize(connectionString)

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.

To connect to CockroachDB with Sequelize, you must install the CockroachDB Sequelize adapter.For more information about connecting with Sequelize, see the official Sequelize documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}

TypeORM configures SSL separately in the DataSource object (ssl: true).

postgresql://{username}:{password}@{host}:{port}/{database}

TypeORM configures SSL separately in the DataSource object:

ssl: {
  ca: process.env.CA_CERT
}

Where CA_CERT is an environment variable set to the root certificate downloaded from the CockroachDB Cloud Console.

postgresql://{username}@{host}:{port}/{database}

TypeORM configures SSL separately in the DataSource object:

ssl: {
  ca: process.env.CA_CERT,
  key: process.env.CLIENT_KEY,
  cert: process.env.CLIENT_CERT
}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

$env:DATABASE_URL = "{connection string}"

Connect to the cluster

To connect to CockroachDB with TypeORM, update your project’s DataSource with the required connection properties.For example, suppose that you are defining the DataSource for your application in a file named datasource.ts:

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

export const AppDataSource = new DataSource({
    type: "cockroachdb",
    url: process.env.DATABASE_URL,
    ssl: true,
    ...
});

export const AppDataSource = new DataSource({
    type: "cockroachdb",
    url: process.env.DATABASE_URL,
    ssl: {
      ca: process.env.CA_CERT
    },
    ...
});

Where CA_CERT is an environment variable set to the root certificate downloaded from the CockroachDB Cloud Console.

export const AppDataSource = new DataSource({
    type: "cockroachdb",
    url: process.env.DATABASE_URL,
    ssl: {
      ca: process.env.CA_CERT,
      key: process.env.CLIENT_KEY,
      cert: process.env.CLIENT_CERT
    },
  ...
});

Where:

CA_CERT is an environment variable set to the root certificate. You can generate this certificate with cockroach cert create-ca, or you can use a custom CA cert.
CLIENT_KEY is an environment variable set to the client key for the user connecting to the cluster. You can generate this key with cockroach cert create-client.
CLIENT_CERT is an environment variable set to the client certificate for the user connecting to the cluster. You can generate this certificate with cockroach cert create-client.

You can then import the AppDataSource into any file in your project and call AppDataSource.initialize() to connect to CockroachDB:

AppDataSource.initialize()
  .then(async () => {
    // Execute operations
  });

For more information about connecting with TypeORM, see the official TypeORM documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

$env:DATABASE_URL = "{connection string}"

Connect to the cluster

To connect to CockroachDB with Prisma, set the url field of the datasource block in your Prisma schema to your database connection URL:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "cockroachdb"
  url      = env("DATABASE_URL")
}

model Widget {
  id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
}

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.For more information about connecting with Prisma, see the official Prisma documentation.

To connect to a CockroachDB Basic or Standard cluster from a Python application, you must have a valid CA certificate located at ~/.postgresql/root.crt.For instructions on downloading a CA certificate from the CockroachDB Cloud Console, see Connect to a CockroachDB Basic Cluster or Connect to a CockroachDB Standard Cluster.

Psycopg2
Psycopg3
SQLAlchemy
Django

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with Psycopg2, pass a connection string to the psycopg2.connect function.For example:

import psycopg2
import os

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

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.For more information about connecting with Psycopg, see the official Psycopg documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with Psycopg3, pass a connection string to the psycopg.connect function.For example:

import psycopg
import os

with psycopg.connect(os.environ['DATABASE_URL']) as conn:
  # application logic here

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.For more information about connecting with Psycopg, see the official Psycopg documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

cockroachdb://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with SQLAlchemy, create an Engine object by passing the connection string to the create_engine function.For example:

from sqlalchemy import create_engine
import os

engine = create_engine(os.environ['DATABASE_URL'])
engine.connect()

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.

To connect to CockroachDB with SQLAlchemy, you must install the CockroachDB SQLAlchemy adapter.For more information about connecting with SQLAlchemy, see the official SQLAlchemy documentation.In order for SQLAlchemy to use the CockroachDB adapter, the connection string must begin with cockroachdb://. You can use the following code to modify the general connection string, which begins with postgresql://, to the format that works with SQLAlchemy and the CockroachDB adapter:

engine = create_engine(os.environ['DATABASE_URL'].replace("postgresql://", "cockroachdb://"))
engine.connect()

Connection string format

Django does not use a connection string. Instead, you configure connection parameters in the DATABASES property in your project’s settings.py file.

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Connect to the cluster

To connect to CockroachDB from a Django application, update the DATABASES property in the project’s settings.py file.

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

## settings.py

...

DATABASES = {
    'default': {
        'ENGINE': 'django_cockroachdb',
        'NAME': '{database}',
        'USER': '{username}',
        'PASSWORD': '{password}',
        'HOST': '{host}',
        'PORT': '{port}',
        'OPTIONS': {
            'sslmode': 'verify-full'
        },
    },
}

...

## settings.py

...

DATABASES = {
    'default': {
        'ENGINE': 'django_cockroachdb',
        'NAME': '{database}',
        'USER': '{username}',
        'PASSWORD': '{password}',
        'HOST': '{host}',
        'PORT': '{port}',
        'OPTIONS': {
            'sslmode': 'verify-full',
            'sslrootcert': os.path.expandvars('{root-cert}'),
        },
    },
}

...

## settings.py

...

DATABASES = {
    'default': {
        'ENGINE': 'django_cockroachdb',
        'NAME': '{database}',
        'USER': '{username}',
        'HOST': '{host}',
        'PORT': '{port}',
        'OPTIONS': {
            'sslmode': 'verify-full',
            'sslrootcert': os.path.expandvars('{root-cert}'),
            'sslcert': os.path.expandvars('{client-cert}'),
            'sslkey': os.path.expandvars('{client-key}'),
        },
    },
}

...

To connect to CockroachDB with Django, you must install the CockroachDB Django adapter.For more information about connecting with Django, see the official Django documentation.

pgx
pq
GORM

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with pgx, use the pgx.Connect function.For example:

package main

import (
	"context"
	"log"
	"os"

	"github.com/jackc/pgx/v4"
)

func main() {
	conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close(context.Background())
}

For more information about connecting with pgx, see the official pgx documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with pq, use the sql.Open function.For example:

package main

import (
	"database/sql"
	"log"
	"os"

	_ "github.com/lib/pq"
)

func main() {
	db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
}

For more information about connecting with pq, see the official pq documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with GORM, use the gorm.Open function, with the GORM postgres driver.For example:

package main

import (
	"log"
	"os"

	"gorm.io/driver/postgres"
	"gorm.io/gorm"
)

func main() {
	db, err := gorm.Open(postgres.Open(os.Getenv("DATABASE_URL")), &gorm.Config{})
	if err != nil {
		log.Fatal(err)
	}
}

For more information about connecting with GORM, see the official GORM documentation.

JDBC
Hibernate

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

jdbc:postgresql://{host}:{port}/{database}?password={password}&sslmode=verify-full&user={username}

jdbc:postgresql://{host}:{port}/{database}?user={username}&password={password}&sslmode=verify-full&sslrootcert={root-cert}

jdbc:postgresql://{host}:{port}/{database}?user={username}&sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The URL-encoded path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The URL-encoded path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The URL-encoded path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The URL-encoded path to the PKCS#8-formatted client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client --also-generate-pkcs8-key`.

Set environment variable

Set a JDBC_DATABASE_URL environment variable to your JDBC connection string:

export JDBC_DATABASE_URL="{connection string}"

$env:JDBC_DATABASE_URL = "{connection string}"

Connect to the cluster

To connect to CockroachDB with the JDBC driver, create a DataSource object (PGSimpleDataSource or PGPoolingDataSource), and set the connection string with the setUrl class method.For example:

PGSimpleDataSource ds = new PGSimpleDataSource();
ds.setUrl(System.getenv("JDBC_DATABASE_URL"));

Where JDBC_DATABASE_URL is an environment variable set to a valid JDBC-compatible CockroachDB connection string.For more information about connecting with JDBC, see the official JDBC documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

jdbc:postgresql://{host}:{port}/{database}?password={password}&sslmode=verify-full&user={username}

jdbc:postgresql://{host}:{port}/{database}?user={username}&password={password}&sslmode=verify-full&sslrootcert={root-cert}

jdbc:postgresql://{host}:{port}/{database}?user={username}&sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The URL-encoded path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The URL-encoded path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The URL-encoded path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The URL-encoded path to the PKCS#8-formatted client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client --also-generate-pkcs8-key`.

Set environment variable

Set a JDBC_DATABASE_URL environment variable to your JDBC connection string:

export JDBC_DATABASE_URL="{connection string}"

$env:JDBC_DATABASE_URL = "{connection string}"

Connect to the cluster

To connect to CockroachDB with Hibernate ORM, set the object’s hibernate.connection.url property to a valid CockroachDB connection string.For example, if you are bootstrapping your application with a ServiceRegistry object, first read from the Hibernate configuration file, and then set the hibernate.connection.url with the applySetting class method:

StandardServiceRegistry standardRegistry = new StandardServiceRegistryBuilder()
    .configure( "hibernate.cfg.xml" ).applySetting("hibernate.connection.url", System.getenv("JDBC_DATABASE_URL"))
    .build();

Metadata metadata = new MetadataSources( standardRegistry )
    .getMetadataBuilder()
    .build();

SessionFactory sessionFactory = metadata.getSessionFactoryBuilder()
    .build();

Where JDBC_DATABASE_URL is an environment variable set to a valid CockroachDB connection string.

To connect to CockroachDB with Hibernate, you must specify the CockroachDB Hibernate dialect in your hibernate.cfg.xml configuration file.For more information about connecting with Hibernate, see the official Hibernate documentation.

To connect to a CockroachDB Basic or Standard cluster from a Ruby application, you must have a valid CA certificate located at ~/.postgresql/root.crt.For instructions on downloading a CA certificate from the CockroachDB Cloud Console, see Connect to a CockroachDB Basic Cluster or Connect to a CockroachDB Standard Cluster.

pg
Active Record

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

postgresql://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

postgresql://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with the Ruby pg driver, use the PG.connect function.For example:

#!/usr/bin/env ruby

require 'pg'

conn = PG.connect(ENV['DATABASE_URL'])

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.For more information about connecting with pg, see the official pg documentation.

Connection string format

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB self-hosted

cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full

cockroachdb://{username}:{password}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}

cockroachdb://{username}@{host}:{port}/{database}?sslmode=verify-full&sslrootcert={root-cert}&sslcert={client-cert}&sslkey={client-key}

Show Connection parameters

CockroachDB Basic/Standard
CockroachDB Advanced
CockroachDB Core

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.

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.
`{root-cert}`	The path to the root certificate that you downloaded from the CockroachDB Cloud Console.

Parameter	Description
`{username}`	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.
`{root-cert}`	The path to the root certificate. You can generate this certificate with `cockroach cert create-ca`, or you can use a custom CA cert.
`{client-cert}`	The path to the client certificate for the user connecting to the cluster. You can generate this certificate with `cockroach cert create-client`.
`{client-key}`	The path to the client key for the user connecting to the cluster. You can generate this key with `cockroach cert create-client`.

Set environment variable

Set a DATABASE_URL environment variable to your connection string:

export DATABASE_URL="{connection string}"

set DATABASE_URL={connection string}

Connect to the cluster

To connect to CockroachDB with Active Record from a Rails app, update the database configuration in config/database.yml:

default: &default
  adapter: cockroachdb
  url: <%= ENV['DATABASE_URL'] %>

...

Where DATABASE_URL is an environment variable set to a valid CockroachDB connection string.

To connect to CockroachDB with Active Record, you must install the Active Record CockroachDB adapter.For more information about connecting with Active Record, see the official Active Record documentation.

​Step 1. Select your deployment

​Step 2. Select your language and driver

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​Connection string format

​Set environment variable

​Connect to the cluster

​See also

Step 1. Select your deployment

Step 2. Select your language and driver

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

Connection string format

Set environment variable

Connect to the cluster

See also