Manage roles

AuraDB Business CriticalAuraDB Virtual Dedicated CloudEnterprise Edition

Roles can be created and managed using a set of Cypher administration commands executed against the system database.

When connected to the DBMS over bolt, administration commands are automatically routed to the system database.

You can view all available roles using the Cypher command SHOW ROLES, which returns a single column by default. Optionally, you can also use SHOW ROLES YIELD * to see if the role is immutable. See Immutable roles for more information.

When first starting a Neo4j DBMS, there are a number of built-in roles:

• PUBLIC - a role that all users have granted. By default it gives access to the home database and to execute privileges for procedures and functions.

• reader - can perform traverse and read operations in all databases except system.

• editor - can perform traverse, read, and write operations in all databases except system, but cannot create new labels or relationship types.

• publisher - can do the same as editor, but also create new labels and relationship types.

• architect - can do the same as publisher as well as create and manage indexes and constraints.

• admin - can do the same as all the above, as well as manage databases, aliases, users, roles, and privileges.

More information about the built-in roles and their privileges can be found in Built-in roles and privileges.

There are multiple versions of this command, the default being SHOW ALL ROLES. To only show roles that are assigned to users, the command is SHOW POPULATED ROLES. To see which users are assigned to which roles, WITH USERS can be added to the command. The command produces a row per role per user and yields the following column in addition to the one output by SHOW ROLES:

Since this gives a result with one row for each user, it shows up twice if a role is assigned to two users.

It is also possible to filter and sort the results by using YIELD, ORDER BY and WHERE.

Roles can be created using CREATE [IMMUTABLE] ROLE:

Roles can be created or replaced by using CREATE OR REPLACE [IMMUTABLE] ROLE:

A role can be copied, keeping its privileges, using CREATE [IMMUTABLE] ROLE name AS COPY OF otherName.

Created roles will appear on the list provided by SHOW ROLES.

The CREATE ROLE command is optionally idempotent, with the default behavior to throw an exception if the role already exists. Adding IF NOT EXISTS to the CREATE ROLE command will ensure that no exception is thrown and nothing happens should the role already exist.

The CREATE OR REPLACE ROLE command will result in any existing role being deleted and a new one created.

Immutable roles are those that cannot be modified in the usual way. This means they cannot be created, renamed, dropped, or have privileges granted to or revoked from them under normal operating conditions. See Immutable roles and privileges for details of when and how the IMMUTABLE keyword may be used.

They are useful in cases where you need a permanent built-in system role that cannot be modified even by users who have ROLE MANAGEMENT privileges but yet can be granted to and revoked from users in the same way as an ordinary role.

Roles can be renamed using RENAME ROLE command:

Users can be given access rights by assigning them roles using GRANT ROLE:

The roles assigned to each user can be seen on the list provided by SHOW USERS:

It is possible to assign multiple roles to multiple users in one command:

Common errors, such as attempts to grant roles to users who have already been granted those roles, will lead to notifications. Some of these notifications may be replaced with errors in a future major version of Neo4j. See Status Codes → Notification codes for details on notifications.

Users can lose access rights by revoking their role using REVOKE ROLE:

The roles revoked from users can no longer be seen on the list provided by SHOW USERS:

It is possible to revoke multiple roles from multiple users in one command:

Common errors, such as misspellings or attempts to revoke roles from users who have not been granted those roles, will lead to notifications. In Cypher 25, notifications for impossible REVOKE commands, where a user, a role, or a database does not exist, have been replaced with errors. See Status Codes → Notification codes for details on notifications.

Roles can be deleted using DROP ROLE command:

When a role has been deleted, it will no longer appear on the list provided by SHOW ROLES:

This command is optionally idempotent, with the default behavior to throw an exception if the role does not exist. Adding IF EXISTS to the command will ensure that no exception is thrown and nothing happens should the role not exist: