Client Connection Parameters

On this page Carat arrow pointing down
Warning:
CockroachDB v2.0 is no longer supported as of October 4, 2019. For more details, refer to the Release Support Policy.

Client applications, including client cockroach commands, 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

There are two principal ways a client can connect to CockroachDB:

  • Most client apps, including most cockroach commands, use a SQL connection established via a PostgreSQL connection URL. When using a URL, a client can also specify SSL/TLS settings and additional SQL-level parameters. This mode provides the most configuration flexibility.
  • Most cockroach commands also provide discrete connection parameters that can specify the connection parameters separately from a URL. This mode is somewhat less flexible than using a URL.
  • Some cockroach commands support connections using either a URL connection string or discrete parameters, whereas some only support discrete connection parameters.

The following table summarizes which client supports which connection parameters:

Client Supports connection by URL Supports discrete connection parameters
Client apps using a PostgreSQL driver ✓ Application-dependent
cockroach init ✗ ✓
cockroach quit ✗ ✓
cockroach sql ✓ ✓
cockroach user ✓ ✓
cockroach zone ✓ ✓
cockroach node ✓ ✓
cockroach dump ✓ ✓
cockroach debug zip ✗ ✓

Connect Using a URL

SQL clients, including some cockroach commands can connect using a URL.

A connection URL has the following format:

icon/buttons/copy
postgres://<username>:<password>@<host>:<port>/<database>?<parameters>
Component Description Required
<username> The SQL user that will own the client session. ✗
<password> The user's password. It is not recommended to pass the password in the URL directly.

Find more detail about how CockroachDB handles passwords.
✗
<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. Required by most client drivers.
<database> A database name to use as current database. ✗
<parameters> Additional connection parameters, including SSL/TLS certificate settings. ✗
Note:
You can specify the URL for cockroach commands that accept a 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 as described below.
Note:
The <database> part should not be specified for any cockroach command other than cockroach sql.
### Additional Connection Parameters The following additional parameters can be passed after the `?` character in the URL: Parameter | Description | Default value ----------|-------------|--------------- `application_name` | An initial value for the [`application_name` session variable](set-vars.html). | 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 [CA certificate](create-security-certificates.html), when `sslmode` is not `disable`. | Empty string. `sslcert` | Path to the [client certificate](create-security-certificates.html), when `sslmode` is not `disable`. | Empty string. `sslkey` | Path to the [client private key](create-security-certificates.html), when `sslmode` is not `disable`. | Empty string. ### 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.

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

**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 [secure deployments](secure-a-cluster.html).
Warning:
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.
### Example URL for an Insecure Connection The following URL is suitable to connect to a CockroachDB node using an insecure connection:
icon/buttons/copy
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:

icon/buttons/copy
postgres://root@servername:26257/mydb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.crt&sslkey=path/to/client.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.crt
    • Client key path/to/client.key

For details about how to create and manage SSL/TLS certificates, see Create Security Certificates and Rotate Certificates.

Connect Using Discrete Parameters

Most cockroach commands accept connection parameters as separate, discrete command-line flags, in addition (or in replacement) to --url which specifies all parameters as 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
--host The server host to connect to. This can be the address of any node in the cluster.

Env Variable: COCKROACH_HOST
Default:localhost
--port
-p
The server port to connect to.

Env Variable: COCKROACH_PORT
Default: 26257
--user
-u
The SQL user that will own the client session.

Env Variable: COCKROACH_USER
Default: root
--insecure Use an insecure connection.

Env Variable: COCKROACH_INSECURE
Default: false
--certs-dir The path to the certificate directory containing the CA and client certificates and client key.

Env Variable: COCKROACH_CERTS_DIR
Default: ${HOME}/.cockroach-certs/
--url A connection URL to use instead of the other arguments.

Env Variable: COCKROACH_URL
Default: no URL
Note:
The command-line flag --url is only supported for cockroach commands that use a SQL connection. See Supported Connection Parameters for details.
### Example Command-Line Flags for an Insecure Connection The following command-line flags establish an insecure connection:
icon/buttons/copy
--user root \
 --host servername \
 --port 26257 \
 --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:

icon/buttons/copy
--user root \
 --host servername \
 --port 26257 \
 --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, and cannot be customized. To use customized file names, use a connection URL instead.
## Using Both URL and Client Parameters Changed in v2.0 Several [`cockroach` commands](cockroach-commands.html) support both a [connection URL](#connect-using-a-url) with `--url` (or `COCKROACH_URL`) and [discrete connection parameters](#connect-using-discrete-parameters). They can be combined as follows: the URL has highest priority, then the discrete parameters. This combination is useful so that discrete command-line flags can override settings not otherwise set in the URL. In other words: - If a URL is specified: - For any URL component that is specified, that information is used and the corresponding discrete parameter is ignored. - For any URL component that is missing, if a corresponding discrete parameter is specified (either via command-line flag or as environment variable), the discrete parameter is used. - If a component is missing in the URL and no corresponding discrete parameter is specified, the default value is used. - If no URL is specified, the discrete parameters are used. For every component not specified, the default value is used. ### Example Override of the Current Database For example, the `cockroach start` command prints out the following connection URL:
icon/buttons/copy
postgres://root@servername:26257/?sslmode=disable

It is possible to connect cockroach sql to this server and also specify mydb as the current database, using the following command:

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

This is equivalent to:

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

See Also


Yes No
On this page

Yes No