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

# Client Connection Parameters

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

Client applications, including <InternalLink path="cockroach-commands">`cockroach` client
commands</InternalLink>, work by establishing a network
connection to a CockroachDB cluster. The client connection parameters
determine which CockroachDB cluster they connect to, and how to
establish this network connection.

## Supported connection parameters

Most client apps, including `cockroach`  client commands, determine
which CockroachDB server to connect to using a [PostgreSQL connection
URL](#connect-using-a-url). When using a URL, a client can also
specify additional SQL-level parameters. This mode provides the most
configuration flexibility.

In addition, all `cockroach` client commands also accept [discrete
connection parameters](#connect-using-discrete-parameters) that can
specify the connection parameters separately from a URL.

## When to use a URL and when to use discrete parameters

Specifying client parameters using a URL may be more convenient during
experimentation, as it facilitates copy-pasting the connection
parameters (the URL) between different tools: the output of `cockroach
start`, other `cockroach` commands, GUI database visualizer,
programming tools, etc.

Discrete parameters may be more convenient in automation, where the
components of the configuration are filled in separately from
different variables in a script or a service manager.

## Connect using a URL

A connection URL has the following format:

```
postgres://<username:<password@<host:<port/<database?<parameters
```

`cockroach` client commands also support [UNIX domain socket URIs](https://wikipedia.org/wiki/Unix_domain_socket) of the following form:

```
postgres://<username:<password@?host=<directory-path&port=<port&<parameters
```

| Component         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Required                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `<username`       | The <InternalLink path="create-user">SQL user</InternalLink> that will own the client session.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | ✗                                                  |
| `<password`       | The user's password. It is not recommended to pass the password in the URL directly.<br /><br />Note that passwords with special characters must be passed as [query string parameters](#additional-connection-parameters) (e.g., `postgres://maxroach@localhost:26257/movr?password=<password`) and not as a component in the connection URL (e.g., `postgres://maxroach:<password@localhost:26257/movr`).<br /><br /><InternalLink path="authentication#client-authentication">Find more detail about how CockroachDB handles passwords.</InternalLink> | ✗                                                  |
| `<host`           | The host name or address of a CockroachDB node or load balancer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required by most client drivers.                   |
| `<port`           | The port number of the SQL interface of the CockroachDB node or load balancer. The default port number for CockroachDB is 26257. Use this value when in doubt.                                                                                                                                                                                                                                                                                                                                                                                            | Required by most client drivers.                   |
| `<database`       | A database name to use as <InternalLink path="sql-name-resolution#current-database">current database</InternalLink>. Defaults to `defaultdb` when using `cockroach` client commands. Drivers and ORMs may have different defaults.                                                                                                                                                                                                                                                                                                                        | ✗                                                  |
| `<directory-path` | The directory path to the client listening for a socket connection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Required when specifying a Unix domain socket URI. |
| `<parameters`     | [Additional connection parameters](#additional-connection-parameters), including SSL/TLS certificate settings.                                                                                                                                                                                                                                                                                                                                                                                                                                            | ✗                                                  |

<Note>
  For `cockroach` commands that accept a URL, you can specify the URL with the command-line flag `--url`.
  If `--url` is not specified but
  the environment variable `COCKROACH_URL` is defined, the environment
  variable is used. Otherwise, the `cockroach` command will use
  [discrete connection parameters](#connect-using-discrete-parameters)
  as described below.
</Note>

The `<database` part is not used for <InternalLink path="cockroach-commands">`cockroach`
commands</InternalLink> other than <InternalLink path="cockroach-sql">`cockroach
sql`</InternalLink>. A warning
is currently printed if it is mistakenly specified, and
future versions of CockroachDB may return an error in that case.

### Additional connection parameters

The following additional parameters can be passed after the `?` character in the URL. After the first parameter is specified, any additional parameters must be separated by an ampersand (`&`).

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                                                                                     | Default value |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `application_name`    | An initial value for the <InternalLink path="set-vars">`application_name` session variable</InternalLink>.<br /><br />Note: For <InternalLink path="build-a-java-app-with-cockroachdb">Java JDBC</InternalLink>, use `ApplicationName`.                                                                                                                                                                         | Empty string. |
| `sslmode`             | Which type of secure connection to use: `disable`, `allow`, `prefer`, `require`, `verify-ca` or `verify-full`. See [Secure Connections With URLs](#secure-connections-with-urls) for details.                                                                                                                                                                                                                   | `disable`     |
| `sslrootcert`         | Path to the <InternalLink path="cockroach-cert">CA certificate</InternalLink>, when `sslmode` is not `disable`.                                                                                                                                                                                                                                                                                                 | Empty string. |
| `sslcert`             | Path to the <InternalLink path="cockroach-cert">client certificate</InternalLink>, when `sslmode` is not `disable`.                                                                                                                                                                                                                                                                                             | Empty string. |
| `sslkey`              | Path to the <InternalLink path="cockroach-cert">client private key</InternalLink>, when `sslmode` is not `disable`.                                                                                                                                                                                                                                                                                             | Empty string. |
| `password`            | The SQL user's password. It is not recommended to pass the password in the URL directly.<br /><br />Note that passwords with special characters must be passed as [query string parameters](#additional-connection-parameters) (e.g., `postgres://maxroach@localhost:26257/movr?password=<password`) and not as a component in the connection URL (e.g., `postgres://maxroach:<password@localhost:26257/movr`). | Empty string  |
| `options`             | [Additional options](#supported-options-parameters) to be passed to the server.                                                                                                                                                                                                                                                                                                                                 | Empty string  |
| `results_buffer_size` | Default size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. Can also be set using the <InternalLink path="cluster-settings">`sql.defaults.results_buffer.size` cluster setting</InternalLink>. Can be set as a top-level query parameter or as an `options` parameter.                                                                     |               |

#### Supported `options` parameters

CockroachDB supports the following `options` parameters. After the first `options` parameter is specified, any additional parameters in the same connection string must be separated by a space.

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cluster=<routing-id`        | Identifies your tenant cluster on a multi-tenant host. For example, `funny-skunk-123`. This option is deprecated. The `host` in the connection string now includes the tenant information.                                                                                                                                                  |
| `-c <session_variable>=<value` | Sets a <InternalLink path="set-vars">session variable</InternalLink> for the SQL session.                                                                                                                                                                                                                                                   |
| `results_buffer_size`          | Default size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. Can also be set using the <InternalLink path="cluster-settings">`sql.defaults.results_buffer.size` cluster setting</InternalLink>. Can be set as a top-level query parameter or as an `options` parameter. |

<Note>
  Note that some drivers require certain characters to be properly encoded in URL connection strings. For example, spaces in [a JDBC connection string](https://jdbc.postgresql.org/documentation/use/#connection-parameters) must be specified as `%20`.
</Note>

### Secure connections with URLs

The following values are supported for `sslmode`, although only the first and the last are recommended for use.

| Parameter             | Description                                                                                                                                                             | Recommended for use                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `sslmode=disable`     | Do not use an encrypted, secure connection at all.                                                                                                                      | Use during development.                                                          |
| `sslmode=allow`       | Enable a secure connection only if the server requires it.<br /><br />**Not supported in all clients.**                                                                 |                                                                                  |
| `sslmode=prefer`      | Try to establish a secure connection, but accept an insecure connection if the server does not support secure connections.<br /><br />**Not supported in all clients.** |                                                                                  |
| `sslmode=require`     | Force a secure connection. An error occurs if the secure connection cannot be established.                                                                              |                                                                                  |
| `sslmode=verify-ca`   | Force a secure connection and verify that the server certificate is signed by a known CA.                                                                               |                                                                                  |
| `sslmode=verify-full` | Force a secure connection, verify that the server certificate is signed by a known CA, and verify that the server address matches that specified in the certificate.    | Use for <InternalLink path="secure-a-cluster">secure deployments</InternalLink>. |

<Danger>
  Some client drivers and the `cockroach` commands do not support
  `sslmode=allow` and `sslmode=prefer`. Check the documentation of your
  SQL driver to determine whether these options are supported.
</Danger>

### Convert a URL for different drivers

The subcommand `cockroach convert-url` converts a connection URL, such as those printed out by <InternalLink path="cockroach-start">`cockroach start`</InternalLink> or included in the online documentation, to the syntax recognized by various <InternalLink path="third-party-database-tools#drivers">client drivers</InternalLink>. For example:

```
$ ./cockroach convert-url --url "postgres://foo/bar"
```

```
# Connection URL for libpq (C/C++), psycopg (Python), lib/pq & pgx (Go),node-postgres (JS)
and most pq-compatible drivers:
  postgresql://root@foo:26257/bar
# Connection DSN (Data Source Name) for Postgres drivers that accept DSNs - most drivers
and also ODBC:
  database=bar user=root host=foo port=26257
# Connection URL for JDBC (Java and JVM-based languages):
  jdbc:postgresql://foo:26257/bar?user=root
```

### Example URL for an insecure connection

The following URL is suitable to connect to a CockroachDB node using an insecure connection:

```
postgres://root@servername:26257/mydb?sslmode=disable
```

This specifies a connection for the `root` user to server `servername`
on port 26257 (the default CockroachDB SQL port), with `mydb` set as
current database. `sslmode=disable` makes the connection insecure.

### Example URL for a secure connection

The following URL is suitable to connect to a CockroachDB node using a secure connection:

```
postgres://root@servername:26257/mydb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.username.crt&sslkey=path/to/client.username.key
```

This uses the following components:

* User `root`
* Host name `servername`, port number 26257 (the default CockroachDB SQL port)
* Current database `mydb`
* SSL/TLS mode `verify-full`:
  * Root CA certificate `path/to/ca.crt`
  * Client certificate `path/to/client.username.crt`
  * Client key `path/to/client.username.key`

For details about how to create and manage SSL/TLS certificates, see
<InternalLink path="cockroach-cert">Create Security Certificates</InternalLink> and
<InternalLink path="rotate-certificates">Rotate Certificates</InternalLink>.

### Example URI for a Unix domain socket

The following URI is suitable to connect to a CockroachDB cluster listening for Unix domain socket connections at `/path/to/client`:

```
postgres://root@?host=/path/to/client&port=26257
```

This specifies a connection for the `root` user to an insecure cluster listening for a socket connection (e.g., a cluster started with the <InternalLink path="cockroach-start#networking">`--socket-dir` flag</InternalLink>) at `/path/to/client`, and on port 26257.

### Example URI for connecting to a database with a user-defined schema

The following URI connects to a CockroachDB cluster with a user-defined schema named `max_schema` in the `movr` database using the [`options` parameter](#supported-options-parameters).

```
postgres://maxroach@db.example.com:26257/movr?sslmode=verify-full&options%3D-c%20search_path%3Dmax_schema
```

<Note>
  The `options=-c search_path=max_schema` parameter is URL-encoded in the example above.
</Note>

## Connect using discrete parameters

Most <InternalLink path="cockroach-commands">`cockroach` commands</InternalLink> accept connection
parameters as separate, discrete command-line flags, in addition (or
in replacement) to `--url` which [specifies all parameters as a
URL](#connect-using-a-url).

For each command-line flag that directs a connection parameter,
CockroachDB also recognizes an environment variable. The environment
variable is used when the command-line flag is not specified.

| Flag                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--url`                  | A <InternalLink path="connection-parameters#connect-using-a-url">connection URL</InternalLink> to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run <InternalLink path="connection-parameters#convert-a-url-for-different-drivers">`cockroach convert-url`</InternalLink>.<br /><br />**Env Variable:** `COCKROACH_URL`<br />**Default:** no URL                                                                                                                                                                                                                                                                                                                                                                                 |
| `--host`                 | The server host and port number to connect to. This can be the address of any node in the cluster. <br /><br />**Env Variable:** `COCKROACH_HOST`<br />**Default:** `localhost:26257`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--port`<br /><br />`-p` | The server port to connect to. Note: The port number can also be specified via `--host`. <br /><br />**Env Variable:** `COCKROACH_PORT`<br />**Default:** `26257`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--user`<br /><br />`-u` | The <InternalLink path="create-user">SQL user</InternalLink> that will own the client session.<br /><br />**Env Variable:** `COCKROACH_USER`<br />**Default:** `root`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--insecure`             | Use an insecure connection.<br /><br />**Env Variable:** `COCKROACH_INSECURE`<br />**Default:** `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--cert-principal-map`   | A comma-separated list of `<cert-principal:<db-principal` mappings. This allows mapping the principal in a cert to a DB principal such as `node` or `root` or any SQL user. This is intended for use in situations where the certificate management system places restrictions on the `Subject.CommonName` or `SubjectAlternateName` fields in the certificate (e.g., disallowing a `CommonName` like `node` or `root`). If multiple mappings are provided for the same `<cert-principal`, the last one specified in the list takes precedence. A principal not specified in the map is passed through as-is via the identity function. A cert is allowed to authenticate a DB principal if the DB principal name is contained in the mapped `CommonName` or DNS-type `SubjectAlternateName` fields. |
| `--certs-dir`            | The path to the <InternalLink path="cockroach-cert">certificate directory</InternalLink> containing the CA and client certificates and client key.<br /><br />**Env Variable:** `COCKROACH_CERTS_DIR`<br />**Default:** `${HOME}/.cockroach-certs/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### Example command-line flags for an insecure connection

The following command-line flags establish an insecure connection:

```
--user=root \
--host=<servername
--insecure
```

This specifies a connection for the `root` user to server `servername`
on port 26257 (the default CockroachDB SQL port). `--insecure` makes
the connection insecure.

### Example command-line flags for a secure connection

The following command-line flags establish a secure connection:

```
--user=root \
--host=<servername
--certs-dir=path/to/certs
```

This uses the following components:

* User `root`
* Host name `servername`, port number 26257 (the default CockroachDB SQL port)
* SSL/TLS enabled, with settings:
  * Root CA certificate `path/to/certs/ca.crt`
  * Client certificate `path/to/client.<user.crt` (`path/to/certs/client.root.crt` with `--user root`)
  * Client key `path/to/client.<user.key` (`path/to/certs/client.root.key` with `--user root`)

<Note>
  When using discrete connection parameters, the file names of the CA
  and client certificates and client key are derived automatically from
  the value of `--certs-dir`.
</Note>

## Using both URL and client parameters

Most `cockroach` commands accept both a URL and client parameters.
The information contained therein is combined in the order it appears
in the command line.

This combination is useful so that discrete command-line flags can
override settings not otherwise set in the URL.

### Example override of the current database

The `cockroach start` command prints out the following connection URL, which connects to the `defaultdb` database:

```
postgres://root@servername:26257/?sslmode=disable
```

To specify `mydb` as the current database using <InternalLink path="cockroach-sql">`cockroach sql`</InternalLink>, run the following command:

```
cockroach sql \
--url "postgres://root@servername:26257/?sslmode=disable" \
--database mydb
```

This is equivalent to:

```
cockroach sql --url "postgres://root@servername:26257/mydb?sslmode=disable"
```

## See also

* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>
* <InternalLink path="cockroach-cert">Create Security Certificates</InternalLink>
* <InternalLink path="secure-a-cluster">Secure a Cluster</InternalLink>
* <InternalLink path="security-reference/authorization#create-and-manage-users">Create and Manage Users</InternalLink>