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
cockroachcommands, 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
cockroachcommands 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
cockroachcommands 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. | ✗ |
Note:
You can specify the URL for 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.Note:
The <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).
Warning:
Some client drivers and the 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_HOSTDefault: localhost |
--port-p | The server port to connect to. Env Variable: COCKROACH_PORTDefault: 26257 |
--user-u | The SQL user that will own the client session. Env Variable: COCKROACH_USERDefault: root |
--insecure | Use an insecure connection. Env Variable: COCKROACH_INSECUREDefault: false |
--certs-dir | The path to the certificate directory containing the CA and client certificates and client key. Env Variable: COCKROACH_CERTS_DIRDefault: ${HOME}/.cockroach-certs/ |
--url | A connection URL to use instead of the other arguments. Env Variable: COCKROACH_URLDefault: no URL |
Note:
The command-line flag --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.crtwith--user root) - Client key
path/to/client.<user>.key(path/to/certs/client.root.keywith--user root)
- Root CA certificate
Note:
When using discrete connection parameters, the file names of the CA and client certificates and client key are derived automatically from the value of --certs-dir, and cannot be customized. To use customized file names, use a connection URL instead.