9. User management#

Use these statements to create, inspect, change, and delete QuasarDB users. You can run the statements in qdbsh while the cluster is online.

9.1. Overview#

Each user has a unique name.
A user can also have a unique UID.
The server stores the public key of the user.
The user stores the matching private key.
Default privileges apply to entries that do not have explicit grants.
USER_SECURITY_FILE is a path on the client.

9.2. Syntax summary#

CREATE USER '<name>'
  [ UID [ = ] <positive_integer> ]
  USER_SECURITY_FILE [ = ] '<path>'
  [ PRIVILEGES [ = ] <privilege> [, ... ] ]
  [ SUPERUSER ]
  [ DISABLED ]

ALTER USER '<name>' [, ... ]
  [ [ { SET | ADD | DROP } ] PRIVILEGES [ = ] <privilege> [, ... ] ]
  [ SUPERUSER = <boolean> ]
  [ DISABLED = <boolean> ]

DROP USER '<name>' [, ... ]

SHOW USER '<name>' [, ... ]
SHOW USERS

RELOAD USER CONFIG [ FROM FILE '<path>' ]

GRANT <privilege> [, ... ]
  ON { <entry_name> | <find_expression> } [, ... ]
  TO <user_name> [, ... ]

SET USER_PROPERTY <key> = '<value>' [, ... ]
SHOW USER_PROPERTY <key> [, ... ]
DROP USER_PROPERTY <key> [, ... ]

privilege ::= {
  DENIED | SELECT | INSERT | UPDATE | DELETE | INDEX | ALTER |
  CREATE | DROP | GRANT | USER_MANAGE | SYSTEM | SET_ACL |
  GET_ACL | SET_TRANSACTION | ALL
}

find_expression ::=
  FIND (
    { TAG = <tag_value> | NOT TAG = <tag_value>
      | PREFIX = 'prefix' | SUFFIX = 'suffix' | TYPE = TS }
    [ AND ... ] [ , RECURSIVE = { TRUE | FALSE } ]
  )

tag_value ::= { 'text' | $table } [ || ... ]

9.3. Create a user#

CREATE USER adds one user account.

UID: Sets a positive user identifier. The identifier must be unique in the cluster. This option is not required.
USER_SECURITY_FILE: Specifies the client path for the generated user security file.
PRIVILEGES: Sets the initial default privileges. Use a comma-separated list, ALL, or DENIED.
SUPERUSER: Gives the user all system privileges.
DISABLED: Prevents the user from logging in.

Create a user with a UID:

CREATE USER 'analyst' UID=2
  USER_SECURITY_FILE='analyst.key'
  PRIVILEGES=SELECT;

Let QuasarDB assign the UID:

CREATE USER 'operator'
  USER_SECURITY_FILE='operator.key'
  PRIVILEGES=SELECT, INSERT;

9.4. Alter users#

ALTER USER changes one or more user accounts.

SET PRIVILEGES: Replaces the default privilege set.
ADD PRIVILEGES: Adds privileges to the default privilege set.
DROP PRIVILEGES: Removes privileges from the default privilege set.
SUPERUSER: Enables or disables superuser access.
DISABLED: Enables or disables login access.

Add one privilege:

ALTER USER 'analyst' ADD PRIVILEGES=SET_TRANSACTION;

Disable two users:

ALTER USER 'analyst', 'intern' DISABLED=true;

9.5. Remove users#

DROP USER removes one or more accounts. It also removes their explicit grants.

DROP USER 'analyst', 'intern';

9.6. Show users#

SHOW USER returns the attributes of the specified users. SHOW USERS returns the attributes of all users.

SHOW USER 'analyst', 'operator';
SHOW USERS;

9.7. Reload the user configuration#

RELOAD USER CONFIG reloads the active user configuration. Use FROM FILE to load a specified configuration file.

RELOAD USER CONFIG;
RELOAD USER CONFIG FROM FILE 'users.json';

9.8. Grant privileges#

GRANT adds explicit privileges for one or more entries and users. The privileges override the default privileges for those entries.

entries: Specifies one or more table names.
find_expression: Selects tables by tag, name prefix, name suffix, or type. For more information, refer to key/value lookups.
grantees: Specifies one or more user names.

Grant INSERT on two tables:

GRANT INSERT ON trades, orders TO 'Bob';

Grant SELECT on tagged time-series tables:

GRANT SELECT ON FIND(TAG='stocks' AND TYPE=TS) TO 'Alice';

9.9. Manage user properties#

User properties are key/value metadata for the active connection. Use them to identify a client in server logs.

SET USER_PROPERTY: Creates or replaces one or more properties. A property value must not be empty.
SHOW USER_PROPERTY: Returns the specified properties.
DROP USER_PROPERTY: Removes the specified properties.

SET USER_PROPERTY department='research', region='us';
SHOW USER_PROPERTY department, region;
DROP USER_PROPERTY department, region;

9.10. End-to-end example#

CREATE USER 'admin' UID=1 USER_SECURITY_FILE='admin.key' SUPERUSER;

CREATE USER 'analyst' UID=2
  USER_SECURITY_FILE='analyst.key'
  PRIVILEGES=SELECT;

GRANT INSERT ON trades TO 'analyst';

ALTER USER 'analyst' ADD PRIVILEGES=SET_TRANSACTION;

SHOW USERS;

DROP USER 'analyst';