Users & Roles

Role Permissions documentation below for HarperDB version 2.2.0 and above.


HarperDB utilizes a Role-Based Access Control (RBAC) framework to manage access to HarperDB instances.  A user is assigned a role that determines the user’s permissions to access database resources and run core operations.

Roles in HarperDB

Role permissions in HarperDB are broken into two categories – permissions around database manipulation and permissions around database definition.


Database Manipulation:  A role defines CRUD permissions against database resources (i.e. data) in a HarperDB instance.

  1. At the table-level access, permissions must be explicitly defined when adding or altering a role – i.e. HarperDB will assume CRUD access to be FALSE if not explicitly provided in the permissions JSON passed to the add_role and/or alter_role API operations.
  2. At the attribute-level, permissions for attributes in all tables included in the permissions set will be assigned based on either the specific attribute-level permissions defined in the table’s permission set or, if there are no attribute-level permissions defined, permissions will be based on the table’s CRUD set.


Database Definition:  Permissions related to managing schemas, tables, roles, users, and other system settings and operations are restricted to the built-in super_user role.


Built-In Roles
There are two built-in roles within HarperDB. See full breakdown of operations restricted to only super_user roles here.

  • super_user – this role provides full access to all operations and methods within a HarperDB instance, this can be considered the admin role.

    • This role provides full access to all Database Definition operations and the ability to run Database Manipulation operations across the entire database schema with no restrictions.

  • cluster_user – this role is an internal system role type that is managed internally to allow clustered instances to communicate with one another.
    • This role is an internally managed role to facilitate communication between clustered instances. 


User-Defined Roles
In addition to built-in roles, admins (i.e. users assigned to the super_user role) can create customized roles for other users to interact with and manipulate the data within explicitly defined tables and attributes.

  • Unless the user-defined role is given super_user permissions, permissions must be defined explicitly within the request body JSON.
  • Describe operations will return metadata for all schemas, tables, and attributes that a user-defined role has CRUD permissions for.


Role Permissions
When creating a new, user-defined role in a HarperDB instance, you must provide a role name and the permissions to assign to that role.  Reminder, only super users can create and manage roles.

  • role name used for easily identify the role assigned to individual users.
    Important: roles are assigned to users and altered/dropped based on the id from the response metadata returned from a successful add_role , alter_role, or list_roles operation.
  • permissions used to explicitly defined CRUD access to existing table data.


Example JSON for add_role request

          "tables": {
             "table_name1": {
             "table_name2": {


Setting Role Permissions
There are two parts to a permissions set:

  • super_user – boolean value indicating if role should be provided super_user access.
    If super_user is set to true, there should be no additional schema-specific permissions values included since the role will have access to the entire database schema. If permissions are passed, they will stored but will be ignored.
  • permissions: Schema tables that a role should have specific CRUD access to should be included in the final, schema-specific permissions JSON.
    For user-defined roles (i.e. non-super_user roles, blank permissions will result in the user being restricted from accessing any of the database schema.


Table Permissions JSON
Each table that a role should be given some level of CRUD permissions to must be included in the tables array for its schema in the roles permissions JSON passed to the API (see example above).

    table_name: { // the name of the table to define CRUD perms for
        "read": boolean, // access to read from this table
        "insert": boolean, // access to insert data to table
        "update": boolean, // access to update data in table
        "delete": boolean, // access to delete row data in table
        "attribute_permissions": [ // permissions for specific table attributes
             "attribute_name": "attribute_name", // attribute to assign permissions to
             "read": boolean, // access to read this attribute from table
             "insert": boolean, // access to insert this attribute into the table
             "update": boolean // access to update this attribute in the table


Important Notes About Table Permissions

  1. If a schema and/or any of its tables are not included in the permissions JSON, the role will not have any CRUD access to the schema and/or tables.
  2. If a table-level CRUD permission is set to false, any attribute-level with that same CRUD permission set to true will return an error.


Important Notes About Attribute Permissions

  1. If there are attribute-specific CRUD permissions that need to be enforced on a table, those need to be explicitly described in the attribute_permissions array.
  2. If a non-hash attribute is given some level of CRUD access, that same access will be assigned to the table’s hash_attribute, even if it is not explicitly defined in the permissions JSON.
    See table_name1’s permission set for an example of this – even though the table’s hash attribute is not specifically defined in the attribute_permissions array, because the role has CRUD access to ‘attribute1’, the role will have the same access to the table’s hash attribute.
  3. If attribute-level permissions are set – i.e. attribute_permissions.length > 0 – any table attribute not explicitly included will be assumed to have not CRUD access (with the exception of the hash_attribute described in #2).
    See table_name1’s permission set for an example of this – in this scenario, the role will have the ability to create, insert and update ‘attribute1’ and the table’s hash attribute but no other attributes on that table.
  4. If an attribute_permissions array is empty, the role’s access to a table’s attributes will be based on the table-level CRUD permissions.
    See table_name2’s permission set for an example of this.
  5. The __createdtime__ and __updatedtime__ attributes that HarperDB manages internally can have read perms set but, if set, all other attribute-level permissions will be ignored.
  6. Please note that DELETE permissions are not included as a part of an individual attribute-level permission set.  That is because it is not possible to delete individual attributes from a row, rows must be deleted in full.
    • If a role needs the ability to delete rows from a table, that permission should be set on the table-level.
    • The practical approach to deleting an individual attribute of a row would be to set that attribute to null via an update statement.

Role-Based Operation Restrictions

The table below includes all API operations available in HarperDB and indicates whether or not the operation is restricted to super_user roles.

Keep in mind that non-super_user roles will also be restricted within the operations they do have access to by the schema-level CRUD permissions set for the roles.

Schemas and TablesRestricted to Super_Users
NoSQL OperationsRestricted to Super_Users
SQL OperationsRestricted to Super_Users
Bulk OperationsRestricted to Super_Users
Users and RolesRestricted to Super_Users
ClusteringRestricted to Super_Users
RegistrationRestricted to Super_Users
UtilitiesRestricted to Super_Users
JobsRestricted to Super_Users
Auditing DataRestricted to Super_Users

Error: Must execute as User

You may have gotten an error like,  Error: Must execute as <<username>>?  

This means that you installed HarperDB as <<user>>.  Because HarperDB stores files natively on the operating system, we only allow the HarperDB executable to be run by a single user.  This prevents permissions issues on files.


For example if you installed as user_a, but later wanted to run as user_b.   User_b may not have access to the hdb files HarperDB needs.  This also keeps HarperDB more secure as it allows you to lock files down to a specific user and prevents other users from accessing your files.