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 in the new session. | ✗ |
<parameters> |
Additional connection parameters, including SSL/TLS certificate settings. | ✗ |
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.<database>
part should not be specified for any cockroach
command
other than cockroach
sql
.**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](secure-a-cluster.html).
cockroach
commands do not support
sslmode=allow
and sslmode=prefer
. Check the
documentation of your SQL driver to determine whether these options
are supported.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
- Root CA certificate
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 |
--url
is only supported for cockroach
commands that use a SQL connection. See Supported Connection
Parameters for details.--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
)
- Root CA certificate
--certs-dir
,
and cannot be customized. To use customized file names, use a connection URL
instead.