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>

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.

--user root \
 --host servername \
 --port 26257 \
 --database mydb \
 --insecure

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. --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 \
 --database mydb \
 --certs-dir path/to/certs

This uses the following components:

• User root
• Host name servername, port number 26257 (the default CockroachDB SQL port)
• Current database mydb
• 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)

See Also

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