Client Connection Parameters

On this page

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

Most client apps, including cockroach client commands, determine which CockroachDB server to connect to using a PostgreSQL connection URL. When using a URL, a client can also specify additional SQL-level parameters. This mode provides the most configuration flexibility.

In addition, all cockroach client commands also accept discrete connection parameters that can specify 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 during experimentation, as it facilitates copy-pasting the connection parameters (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 the components of the configuration are filled in separately from different 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>

cockroach client commands also support UNIX domain socket URIs of the following form:

postgres://<username>:<password>@?host=<directory-path>&port=<port>&<parameters>

Additional connection parameters

The following additional parameters can be passed after the ? character in the URL. After the first parameter is specified, any additional parameters must be separated by an ampersand (&).

Supported options parameters

CockroachDB supports the following options parameters. After the first options parameter is specified, any additional parameters in the same connection string must be separated by a space.

Secure connections with URLs

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

Convert a URL for different drivers

New in v21.2: The subcommand cockroach convert-url converts a connection URL, such as those printed out by cockroach start or included in the online documentation, to the syntax recognized by various client drivers. For example:

$ ./cockroach convert-url --url "postgres://foo/bar"

# Connection URL for libpq (C/C++), psycopg (Python), lib/pq & pgx (Go),node-postgres (JS)
and most pq-compatible drivers:
  postgresql://root@foo:26257/bar
# Connection DSN (Data Source Name) for PostgreSQL drivers that accept DSNs - most drivers
and also ODBC:
  database=bar user=root host=foo port=26257
# Connection URL for JDBC (Java and JVM-based languages):
  jdbc:postgresql://foo:26257/bar?user=root

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.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, see Create Security Certificates and Rotate Certificates.

Example URI for a Unix domain socket

The following URI is suitable to connect to a CockroachDB cluster listening for Unix domain socket connections at /path/to/client:

postgres://root@?host=/path/to/client&port=26257

This specifies a connection for the root user to an insecure cluster listening for a socket connection (e.g., a cluster started with the --socket-dir flag) at /path/to/client, and on port 26257.

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

Most cockroach commands accept both a URL and client parameters. The information contained therein is combined in the order it appears in the command line.

This combination is useful so that discrete command-line flags can override 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 helpful?