12.3. Defining Users and Roles


VoltDB Home » Documentation » Using VoltDB

12.3. Defining Users and Roles

The key to security for VoltDB applications is the users and roles defined in the schema and configuration. You define users in the configuration file and roles in the schema.

This split is deliberate because it allows you to define the overall security structure globally in the schema, assigning permissions to generic roles (such as operator, dbuser, apps, and so on). You then define specific users and assign them to the generic roles as part of the database configuration. This way you can create one configuration (including cluster information and users) for development and testing, then move the database to a different configuration and a different set of users for production by changing only one file: the configuration file.

You define users within the <users> ... </users> tag set in the configuration file. The syntax for defining users is as follows.

      <user name="user-name" 
            [ expires="expiration-date" ]
        [ ... ]


If you do not want to distribute the account passwords in plain text, you can use the voltdb mask command to hash the passwords in the configuration file.

Include a <user> tag for every username/password pair you want to define. You specify which roles a user belongs to as part of the user definition in the configuration file using the roles attribute to the <user> tag. You can assign users built-in roles, user-defined roles, or both. For user-defined roles, you define the roles in the database schema using the CREATE ROLE statement.

CREATE ROLE role-name;

You can optionally add an expiration date for the account using the expires attribute and specifying a date in ISO 8601 format (i.e. yyyy-MM-dd). If an expiration date is included, the account loses access to the database after midnight of the specified date, until an administrator resets the account attributes in the configuration using the voltadmin update command.

Note that, since the user can no longer access the database once their password expires, it is strongly suggested you do not set an expiration date on accounts with the ADMINISTRATOR role. If the passwords expire on all accounts with the ADMINISTRATOR role, there will be no way to access the database for administrative functions and you may have to reinitialize the database from scratch to regain access.

At least one user must be assigned the built-in ADMINISTRATOR role. For example, the following code defines three users, assigning operator the built-in ADMINISTRATOR role and the user-defined OPS role, assigning developer the user-defined roles OPS and DBUSER, and assigning the user clientapp DBUSER. When a user is assigned more than one role, you specify the role names as a comma-delimited list.

      <user name="operator" password="mech" 
            roles="administrator, ops" />
      <user name="developer" password="tech" 
            roles="ops,dbuser" expires="2026-02-17"/>
      <user name="clientapp" password="xyzzy" 
            roles="dbuser" "expires="2025-01-29"/>


Four important notes concerning the assignment of users and roles:

  • Users must be assigned at least one role, or else they have no permissions. (Permissions are assigned by role.)

  • At least one user must be assigned the built-in ADMINISTRATOR role.

  • At least one user with the ADMINISTRATOR role should be defined without an expiration date to avoid losing access to the database.

  • There must be a corresponding role defined in the schema for any user-defined roles listed in the configuration file.