Warning:
This version of CockroachDB is no longer supported. Cockroach Labs supports the current stable release and two releases prior. Please use one of these supported versions.

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:

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. Empty string.
sslmode Which type of secure connection to use: disable, allow, prefer, require, verify-ca or verify-full. See Secure Connections With URLs for details. disable
sslrootcert Path to the CA certificate, when sslmode is not disable. Empty string.
sslcert Path to the client certificate, when sslmode is not disable. Empty string.
sslkey Path to the client private key, 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.
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:

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

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

--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 support both a connection URL with --url (or COCKROACH_URL) and discrete connection 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:

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:

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



Yes No