Client Connection Parameters

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:

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

### 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). ### Example URL for an Insecure Connection The following URL is suitable to connect to a CockroachDB node using an insecure connection:

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:

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

### Example Command-Line Flags for an Insecure Connection The following command-line flags establish an insecure connection:

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:

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)

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

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

This is equivalent to:

See Also

• cockroach commands
• Create Security Certificates
• Secure a Cluster
• Create and Manage Users