Client Connection Parameters

On this page

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:

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>

Additional Connection Parameters

The following additional parameters can be passed after the ? character in the URL:

Secure Connections With URLs

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

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.

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)

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

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

Was this helpful?