> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to a CockroachDB Cluster

This page documents the required connection configuration for [fully-supported third-party tools](https://docs.cockroachlabs.com/docs/stable/third-party-database-tools.md).

For a list of all supported cluster connection parameters, see the [`cockroach` Connection Parameters](https://docs.cockroachlabs.com/docs/stable/connection-parameters).

For a list of community-supported third-party tools, see [Third-Party Tools Supported by the Community](https://docs.cockroachlabs.com/docs/stable/community-tooling.md). 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**

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](https://cockroachlabs.cloud) and select either **General connection string** or **Parameters only** as the option.

**CockroachDB Advanced**

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](https://cockroachlabs.cloud) and select either **General connection string** or **Parameters only** as the option.

**CockroachDB self-hosted**

To connect to a CockroachDB self-hosted cluster, you need the [general connection string](https://docs.cockroachlabs.com/docs/stable/connection-parameters.md#connect-using-a-url) or [connection parameters](https://docs.cockroachlabs.com/docs/stable/connection-parameters.md#connect-using-discrete-parameters) for your cluster.

The connection strings and parameters for your cluster are output when you [start the cluster](https://docs.cockroachlabs.com/docs/stable/cockroach-start.md#standard-output).

## Step 2. Select your language and driver

**JavaScript/TypeScript**

**node-postgres**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$env:DATABASE_URL = "{connection string}"
```

### Connect to the cluster

To connect to CockroachDB with [node-postgres](https://node-postgres.com), create a new [`Client`](https://node-postgres.com/apis/client) object with a connection string.

For example:

```js theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://node-postgres.com/features/connecting).

**Sequelize**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$env:DATABASE_URL = "{connection string}"
```

### Connect to the cluster

To connect to CockroachDB with [Sequelize](https://sequelize.org), create a `Sequelize` object with the [CockroachDB Sequelize adapter](https://github.com/cockroachdb/sequelize-cockroachdb).

For example:

```js theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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.

> [!NOTE]
>
> To connect to CockroachDB with Sequelize, you must install the [CockroachDB Sequelize adapter](https://github.com/cockroachdb/sequelize-cockroachdb).
>
> For more information about connecting with Sequelize, see the [official Sequelize documentation](https://sequelize.org/docs/v6/).

**TypeORM**

### Connection string format

**CockroachDB Basic/Standard**

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

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

**CockroachDB Advanced**

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

TypeORM configures SSL separately in the DataSource object:

```ts theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ssl: {
  ca: process.env.CA_CERT
}
```

Where `CA_CERT` is an environment variable set to the root certificate [downloaded from the CockroachDB Cloud Console](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification).

**CockroachDB self-hosted**

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

TypeORM configures SSL separately in the DataSource object:

```ts theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ssl: {
  ca: process.env.CA_CERT,
  key: process.env.CLIENT_KEY,
  cert: process.env.CLIENT_CERT
}
```

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$env:DATABASE_URL = "{connection string}"
```

### Connect to the cluster

To connect to CockroachDB with [TypeORM](https://typeorm.io), update your project's [`DataSource`](https://typeorm.io/data-source) 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**

```ts theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export const AppDataSource = new DataSource({
    type: "cockroachdb",
    url: process.env.DATABASE_URL,
    ssl: true,
    ...
});
```

**CockroachDB Advanced**

```ts theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification).

**CockroachDB self-hosted**

```ts theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md).
* `CLIENT_KEY` is an environment variable set to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands).
* `CLIENT_CERT` is an environment variable set to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands).

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

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

```ts theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
AppDataSource.initialize()
  .then(async () => {
    // Execute operations
  });
```

For more information about connecting with TypeORM, see the [official TypeORM documentation](https://typeorm.io/#/).

**Prisma**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$env:DATABASE_URL = "{connection string}"
```

### Connect to the cluster

To connect to CockroachDB with [Prisma](https://prisma.io/), set the `url` field of the `datasource` block in your Prisma schema to your database connection URL:

```js theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://www.prisma.io/cockroachdb).

**Python**

> [!NOTE]
>
> 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](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-a-basic-cluster) or [Connect to a CockroachDB Standard Cluster](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-your-cluster).

**Psycopg2**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with [Psycopg2](https://www.psycopg.org), pass a connection string to the [`psycopg2.connect` function](https://www.psycopg.org/docs/connection.html).

For example:

```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://www.psycopg.org/docs).

**Psycopg3**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with [Psycopg3](https://www.psycopg.org), pass a connection string to the [`psycopg.connect` function](https://www.psycopg.org/psycopg3/docs/basic/usage.html).

For example:

```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://www.psycopg.org/psycopg3/docs/basic/index.html).

**SQLAlchemy**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with [SQLAlchemy](http://docs.sqlalchemy.org/), [create an `Engine` object](https://docs.sqlalchemy.org/core/engines.html) by passing the connection string to the `create_engine` function.

For example:

```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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.

> [!NOTE]
>
> To connect to CockroachDB with SQLAlchemy, you must install the [CockroachDB SQLAlchemy adapter](https://github.com/cockroachdb/sqlalchemy-cockroachdb).
>
> For more information about connecting with SQLAlchemy, see the [official SQLAlchemy documentation](https://docs.sqlalchemy.org/core/engines_connections.html).
>
> 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:
>
> ```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> engine = create_engine(os.environ['DATABASE_URL'].replace("postgresql://", "cockroachdb://"))
> engine.connect()
> ```

**Django**

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

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Connect to the cluster

To connect to CockroachDB from a [Django](https://www.djangoproject.com) application, update the `DATABASES` property in the project's `settings.py` file.

**CockroachDB Basic/Standard**

```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
## settings.py

...

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

...
```

**CockroachDB Advanced**

```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
## 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}'),
        },
    },
}

...
```

**CockroachDB self-hosted**

```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
## 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}'),
        },
    },
}

...
```

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

> [!NOTE]
>
> To connect to CockroachDB with Django, you must install the [CockroachDB Django adapter](https://github.com/cockroachdb/django-cockroachdb).
>
> For more information about connecting with Django, see the [official Django documentation](https://docs.djangoproject.com/en/4.0/).

**Go**

**pgx**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with [pgx](https://github.com/jackc/pgx), use the `pgx.Connect` function.

For example:

```go theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://pkg.go.dev/github.com/jackc/pgx).

**pq**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with [pq](https://godoc.org/github.com/lib/pq), use the [`sql.Open` function](https://go.dev/doc/tutorial/database-access).

For example:

```go theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://pkg.go.dev/github.com/lib/pq).

**GORM**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with [GORM](http://gorm.io), use the `gorm.Open` function, with the GORM `postgres` driver.

For example:

```go theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://gorm.io/docs).

**Java**

**JDBC**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://wikipedia.org/wiki/Percent-encoding) path to the root certificate that you [downloaded from the CockroachDB Cloud Console](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://wikipedia.org/wiki/Percent-encoding) path to the root certificate. You can generate this certificate with [`cockroach cert create-ca`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the [PKCS#8](https://tools.ietf.org/html/rfc5208)-formatted [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client --also-generate-pkcs8-key`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `JDBC_DATABASE_URL` environment variable to your JDBC connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export JDBC_DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$env:JDBC_DATABASE_URL = "{connection string}"
```

### Connect to the cluster

To connect to CockroachDB with the [JDBC](https://jdbc.postgresql.org) driver, create a `DataSource` object ([`PGSimpleDataSource` or `PGPoolingDataSource`](https://jdbc.postgresql.org/documentation/datasource/#applications-datasource)), and set the connection string with the `setUrl` class method.

For example:

```java theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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](https://jdbc.postgresql.org/documentation/).

**Hibernate**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://wikipedia.org/wiki/Percent-encoding) path to the root certificate that you [downloaded from the CockroachDB Cloud Console](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://wikipedia.org/wiki/Percent-encoding) path to the root certificate. You can generate this certificate with [`cockroach cert create-ca`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The [URL-encoded](https://wikipedia.org/wiki/Percent-encoding) path to the [PKCS#8](https://tools.ietf.org/html/rfc5208)-formatted [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client --also-generate-pkcs8-key`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `JDBC_DATABASE_URL` environment variable to your JDBC connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export JDBC_DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$env:JDBC_DATABASE_URL = "{connection string}"
```

### Connect to the cluster

To connect to CockroachDB with [Hibernate](https://hibernate.org/orm) 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`](https://docs.jboss.org/hibernate/orm/current/userguide/html_single/Hibernate_User_Guide.html#bootstrap-native-registry) object, first read from the Hibernate configuration file, and then set the `hibernate.connection.url` with the `applySetting` class method:

```java theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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.

> [!NOTE]
>
> To connect to CockroachDB with Hibernate, you must specify the [CockroachDB Hibernate dialect](https://docs.cockroachlabs.com/docs/stable/install-client-drivers.md?filters=java#hibernate) in your `hibernate.cfg.xml` configuration file.
>
> For more information about connecting with Hibernate, see the [official Hibernate documentation](https://hibernate.org/orm/documentation).

**Ruby**

> [!NOTE]
>
> 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](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-a-basic-cluster) or [Connect to a CockroachDB Standard Cluster](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-your-cluster).

**pg**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with the [Ruby pg](https://rubygems.org/gems/pg) driver, use the `PG.connect` function.

For example:

```ruby theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
#!/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](https://www.rubydoc.info/gems/pg).

**Active Record**

### Connection string format

**CockroachDB Basic/Standard**

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

**CockroachDB Advanced**

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

**CockroachDB self-hosted**

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

> [!NOTE]
>
> The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).
>
> For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/stable/secure-a-cluster.md).

**Connection parameters**

**CockroachDB Basic/Standard**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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. |

**CockroachDB Advanced**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md#node-identity-verification). |

**CockroachDB Core**

| Parameter | Description |
| - | - |
| `{username}` | The [SQL user](https://docs.cockroachlabs.com/docs/stable/security-reference/authorization.md#sql-users) 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`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands), or you can use a [custom CA cert](https://docs.cockroachlabs.com/docs/stable/create-security-certificates-custom-ca.md). |
| `{client-cert}` | The path to the [client certificate](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this certificate with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |
| `{client-key}` | The path to the [client key](https://docs.cockroachlabs.com/docs/stable/cockroach-cert.md#client-key-and-certificates) for the user connecting to the cluster. You can generate this key with [`cockroach cert create-client`](https://docs.cockroachlabs.com/docs/stable/cockroach-cert#subcommands). |

The connection information shown on this page uses [client certificate and key authentication](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md) 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](https://docs.cockroachlabs.com/docs/cockroachcloud/authentication.md).

For instructions on starting a secure cluster, see [Start a Local Cluster (Secure)](https://docs.cockroachlabs.com/docs/v26.2/secure-a-cluster.md).

### Set environment variable

Set a `DATABASE_URL` environment variable to your connection string:

```shell Mac or Linux theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export DATABASE_URL="{connection string}"
```

```shell Windows theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
set DATABASE_URL={connection string}
```

### Connect to the cluster

To connect to CockroachDB with [Active Record](https://github.com/rails/rails/tree/main/activerecord) from a Rails app, update the database configuration in `config/database.yml`:

```yaml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
default: &default
  adapter: cockroachdb
  url: <%= ENV['DATABASE_URL'] %>

...
```

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

> [!NOTE]
>
> To connect to CockroachDB with Active Record, you must install the [Active Record CockroachDB adapter](https://rubygems.org/gems/activerecord-cockroachdb-adapter).
>
> For more information about connecting with Active Record, see the [official Active Record documentation](https://guides.rubyonrails.org/active_record_querying.html).

## See also

* [Install a Driver or ORM Framework](https://docs.cockroachlabs.com/docs/stable/install-client-drivers.md)
* [Connection Pooling](https://docs.cockroachlabs.com/docs/stable/connection-pooling.md)
* [`cockroach` Connection Parameters](https://docs.cockroachlabs.com/docs/stable/connection-parameters)