Client Connection Parameters

Client applications, including cockroach clientcommands, work by establishing a networkconnection to a CockroachDB cluster. The client connection parametersdetermine which CockroachDB cluster they connect to, and how toestablish this network connection.

Supported connection parameters

Most client apps, including cockroach client commands, determinewhich CockroachDB server to connect to using a PostgreSQL connectionURL. When using a URL, a client can alsospecify additional SQL-level parameters. This mode provides the mostconfiguration flexibility.

In addition, all cockroach client commands also accept discreteconnection parameters that canspecify 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 duringexperimentation, as it facilitates copy-pasting the connectionparameters (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 thecomponents of the configuration are filled in separately fromdifferent 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>

Note:

For cockroach commands that accept a URL, you can specify the URL with the command-line flag —url.If —url is not specified butthe environment variable COCKROACH_URL is defined, the environmentvariable is used. Otherwise, the cockroach command will usediscrete connection parametersas described below.

Note:

The <database> part is not used for cockroachcommands other than cockroach
sql. A warningis currently printed if it is mistakenly specified, andfuture 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:

Secure connections with URLs

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

Warning:

Some client drivers and the cockroach commands do not supportsslmode=allow and sslmode=prefer. Check the documentation of yourSQL 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 servernameon port 26257 (the default CockroachDB SQL port), with mydb set ascurrent 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, seeCreate Security Certificates andRotate Certificates.

Connect using discrete parameters

Most cockroach commands accept connectionparameters as separate, discrete command-line flags, in addition (orin replacement) to —url which specifies all parameters as aURL.

For each command-line flag that directs a connection parameter,CockroachDB also recognizes an environment variable. The environmentvariable 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>
--insecure

This specifies a connection for the root user to server servernameon port 26257 (the default CockroachDB SQL port). —insecure makesthe 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 CAand client certificates and client key are derived automatically fromthe value of —certs-dir.

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 appearsin the command line.

This combination is useful so that discrete command-line flags canoverride 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 cockroach sql, 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

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

Was this page helpful?
YesNo