To create and manage your cluster’s users (which lets you control SQL-level privileges), use the cockroach user command with appropriate flags.

When creating users, it’s also important to note:

You can also create users through the CREATE USER statement.

Subcommands

Subcommand Usage
get Retrieve a table containing a user and their hashed password.
ls List all users.
rm Remove a user.
set Create or update a user.

Synopsis

# Create a user:
$ cockroach user set <username> <flags>

# List all users:
$ cockroach user ls <flags>

# Display a specific user:
$ cockroach user get <username> <flags>

# View help:
$ cockroach user --help
$ cockroach user get --help
$ cockroach user ls --help
$ cockroach user rm --help
$ cockroach user set --help

Flags

The user command and subcommands support the following flags, as well as logging flags.

Flag Description
--ca-cert The path to the CA certificate. This flag is required if the cluster is secure.

Env Variable: COCKROACH_CA_CERT
--cert The path to the client certificate of the user issuing the command (not the user you’re creating). This flag is required if the cluster is secure.

Env Variable: COCKROACH_CERT
-d, --database Deprecated: Users are created for the entire cluster. However, you can control a user’s privileges per database when granting them privileges.

Env Variable: COCKROACH_DATABASE
--host Database server host to connect to.

Env Variable: COCKROACH_HOST
--insecure Set this only if the cluster is insecure and running on multiple machines.

If the cluster is insecure and local, leave this out. If the cluster is secure, leave this out and set the --ca-cert, --cert, and --key flags.

Env Variable: COCKROACH_INSECURE
--key Path to the client key protecting the client certificate of the user issuing the command (not the user you’re creating). This flag is required if the cluster is secure.

Env Variable: COCKROACH_KEY
--password Enable password authentication for the user; you will be prompted to enter the password on the command line.

You cannot set a password for the root user.

Find more detail about how CockroachDB handles passwords.
-p, --port Connect to the cluster on the specified port.

Env Variable: COCKROACH_PORT
Default: 26257
--pretty Format table rows printed to the standard output using ASCII art and disable escaping of special characters.

When disabled with --pretty=false, or when the standard output is not a terminal, table rows are printed as tab-separated values, and special characters are escaped. This makes the output easy to parse by other programs.

Default: true when output is a terminal, false otherwise
--url Connect to the cluster on the provided URL, e.g., postgresql:[email protected]:26257/mydb. If left blank, the connection flags are used (host, port, user, database, insecure, certs).

Env Variable: COCKROACH_URL
-u, --user Deprecated: Only the root user can create users, so you cannot pass any other usernames into this flag.

Env Variable: COCKROACH_USER
Default: root

User Authentication

Secure clusters require users to authenticate their access to databases and tables. CockroachDB offers two methods for this:

  • Client certificate and key authentication, which is available to all users. To ensure the highest level of security, we recommend only using client certificate and key authentication.
  • Password authentication, which is available only to users who you’ve created passwords for. To set a password for a user, include the --password flag in the cockroach user set command. However, you cannot add password authentication to the root user.

    You can use this password to authenticate users without supplying their client certificate and key; however, we recommend instead using client certificate and key authentication whenever possible.
Insecure clusters do not support user authentication, but you can still create passwords for users (besides root) through the --password flag.

Examples

Create a User

Insecure Cluster

$ cockroach user set jpointsman

After creating users, you must grant them privileges to databases.

Secure Cluster

$ cockroach user set jpointsman \
--ca-cert=certs/ca.cert --cert=certs/root.cert --key=certs/root.key --password
If you want to allow password authentication for the user, include the --password flag and then enter and confirm the password at the command prompt.

After creating users, you must grant them privileges to databases.

Authenticate as a Specific User

Insecure Clusters

$ cockroach sql --user=jpointsman

Secure Clusters with Client Certificates

All users can authenticate their access to a secure cluster using a client certificate issued to their username.

$ cockroach sql --user=jpointsman --ca-cert=certs/ca.cert --cert=jpointsman.cert --key=jpointsman.key

Secure Clusters with Passwords

Users with passwords can authenticate their access by entering their password at the command prompt instead of using their client certificate and key.

$ cockroach sql --user=jpointsman --ca-cert=certs/ca.cert

After issuing this command, you must enter the password for jpointsman twice.

Update a User’s Password

$ cockroach user set jpointsman \
--password \
--ca-cert=certs/ca.cert --cert=certs/root.cert --key=certs/root.key

After issuing this command, enter and confirm the user’s new password at the command prompt.

You cannot add password authentication to the root user.

List All Users

$ cockroach user ls
+------------+
|  username  |
+------------+
| jpointsman |
+------------+

Find a Specific User

$ cockroach user get jpointsman
+------------+--------------------------------------------------------------+
|  username  |                        hashedPassword                        |
+------------+--------------------------------------------------------------+
| jpointsman | $2a$108tm5lYjES9RSXSKtQFLhNO.e/ysTXCBIRe7XeTgBrR6ubXfp6dDczS |
+------------+--------------------------------------------------------------+

Remove a User

$ cockroach user rm jpointsman

See Also



Yes No