Database privileges

Administrators can use the following Cypher commands to manage Neo4j database administrative rights.

The components of the database privilege commands are:

  • command:

    • GRANT – gives privileges to roles.

    • DENY – denies privileges to roles.

    • REVOKE – removes granted or denied privileges from roles.

  • mutability:

    • IMMUTABLE - When used in conjunction with GRANT or DENY, specifies that a privilege cannot subsequently be removed unless auth is disabled. Contrastingly, when IMMUTABLE is specified in conjunction with a REVOKE command, it will act as a filter and only remove matching immutable privileges. See also Immutable roles and privileges.

  • database-privilege

    • ACCESS - allows access to a specific database or remote database alias.

    • START - allows the specified database to be started.

    • STOP - allows the specified database to be stopped.

    • CREATE INDEX - allows indexes to be created on the specified database.

    • DROP INDEX - allows indexes to be deleted on the specified database.

    • SHOW INDEX - allows indexes to be listed on the specified database.

    • INDEX [MANAGEMENT] - allows indexes to be created, deleted, and listed on the specified database.

    • CREATE CONSTRAINT - allows constraints to be created on the specified database.

    • DROP CONSTRAINT - allows constraints to be deleted on the specified database.

    • SHOW CONSTRAINT - allows constraints to be listed on the specified database.

    • CONSTRAINT [MANAGEMENT] - allows constraints to be created, deleted, and listed on the specified database.

    • CREATE NEW [NODE] LABEL - allows new node labels to be created.

    • CREATE NEW [RELATIONSHIP] TYPE - allows new relationship types to be created.

    • CREATE NEW [PROPERTY] NAME - allows property names to be created, so that nodes and relationships can have properties assigned with these names.

    • NAME [MANAGEMENT] - allows all of the name management capabilities: node labels, relationship types, and property names.

    • ALL [[DATABASE] PRIVILEGES] - allows access, index, constraint, and name management for the specified database or remote database alias.

    • SHOW TRANSACTION - allows listing transactions and queries for the specified users on the specified database.

    • TERMINATE TRANSACTION - allows ending transactions and queries for the specified users on the specified database.

    • TRANSACTION [MANAGEMENT] - allows listing and ending transactions and queries for the specified users on the specified database.

  • name

    • The database to associate the privilege with.

      If you delete a database and create a new one with the same name, the new one will NOT have the same privileges previously assigned to the deleted one.

    • The name component can be *, which means all databases. Databases created after this command execution will also be associated with these privileges.

    • The DATABASE[S] name part of the command can be replaced by HOME DATABASE. This refers to the home database configured for a user or, if that user does not have a home database configured, the default database. If the user’s home database changes for any reason after this command execution, the new one will be associated with these privileges. This can be quite powerful as it allows permissions to be switched from one database to another simply by changing a user’s home database.

  • role[, …​]

    • The role or roles to associate the privilege with, comma-separated.

For more details about the syntax descriptions, see Cypher syntax for administration commands.
Table 1. General grant ON DATABASE privilege syntax

Command

GRANT ... ON ... TO ...

Syntax

 
GRANT [IMMUTABLE] database-privilege ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } TO role[, ...]

Description

Grants a privilege to one or multiple roles.
Table 2. General deny ON DATABASE privilege syntax

Command

DENY ... ON ... TO ...

Syntax

 
DENY [IMMUTABLE] database-privilege ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } TO role[, ...]

Description

Denies a privilege to one or multiple roles.
Table 3. General revoke ON DATABASE privilege syntax

Command

REVOKE GRANT ... ON ... FROM ...

Syntax

 
REVOKE [IMMUTABLE] GRANT database-privilege ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } FROM role[, ...]

Description

Revoke a granted privilege from one or multiple roles.
Table 4. General revoke ON DATABASE privilege syntax

Command

REVOKE DENY ... ON ... FROM ...

Syntax

 
REVOKE [IMMUTABLE] DENY database-privilege ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } FROM role[, ...]

Description

Revokes a denied privilege from one or multiple roles.
Table 5. General revoke ON DATABASE privilege syntax

Command

REVOKE ... ON ... FROM ...

Syntax

 
REVOKE [IMMUTABLE] database-privilege ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } FROM role[, ...]

Description

Revokes a granted or denied privilege from one or multiple roles.

DENY does not erase a granted privilege. Use REVOKE if you want to remove a privilege.

Common errors, such as misspellings or attempts to revoke privileges that have not been granted or denied, 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.

The hierarchy between the different database privileges is shown in the image below.

privileges hierarchy database
Figure 1. Database privileges hierarchy
Table 6. Database privilege syntax

Command

GRANT ACCESS

Syntax

 
GRANT [IMMUTABLE] ACCESS
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to access:

  • The home database.

  • Specific database(s) or remote database alias(es).

  • All databases and remote database aliases.
Table 7. Database privilege syntax

Command

GRANT { START | STOP }

Syntax

 
GRANT [IMMUTABLE] { START | STOP }
  ON { HOME DATABASE | DATABASE[S] {* | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to start or stop the home database, specific database(s), or all databases.
Table 8. Database privilege syntax

Command

GRANT { CREATE | DROP | SHOW } INDEX

Syntax

 
GRANT [IMMUTABLE] { CREATE | DROP | SHOW } INDEX[ES]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to create, delete, or show indexes on the home database, specific database(s), or all databases.
Table 9. Database privilege syntax

Command

GRANT INDEX

Syntax

 
GRANT [IMMUTABLE] INDEX[ES] [MANAGEMENT]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to manage indexes on the home database, specific database(s), or all databases.
Table 10. Database privilege syntax

Command

GRANT { CREATE | DROP | SHOW } CONSTRAINT

Syntax

 
GRANT [IMMUTABLE] { CREATE | DROP | SHOW } CONSTRAINT[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to create, delete, or show constraints on the home database, specific database(s), or all databases.
Table 11. Database privilege syntax

Command

GRANT CONSTRAINT

Syntax

 
GRANT [IMMUTABLE] CONSTRAINT[S] [MANAGEMENT]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to manage constraints on the home database, specific database(s), or all databases.
Table 12. Database privilege syntax

Command

GRANT CREATE NEW LABEL

Syntax

 
GRANT [IMMUTABLE] CREATE NEW [NODE] LABEL[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to create new node labels in the home database, specific database(s), or all databases.
Table 13. Database privilege syntax

Command

GRANT CREATE NEW TYPE

Syntax

 
GRANT [IMMUTABLE] CREATE NEW [RELATIONSHIP] TYPE[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to create new relationship types in the home database, specific database(s), or all databases.
Table 14. Database privilege syntax

Command

GRANT CREATE NEW NAME

Syntax

 
GRANT [IMMUTABLE] CREATE NEW [PROPERTY] NAME[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to create new property names in the home database, specific database(s), or all databases.
Table 15. Database privilege syntax

Command

GRANT NAME

Syntax

 
GRANT [IMMUTABLE] NAME [MANAGEMENT]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to manage new labels, relationship types, and property names in the home database, specific database(s), or all databases.
Table 16. Database privilege syntax

Command

GRANT ALL

Syntax

 
GRANT [IMMUTABLE] ALL [[DATABASE] PRIVILEGES]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles all privileges for the home, a specific, or all databases and remote database aliases.
Table 17. Database privilege syntax

Command

GRANT { SHOW | TERMINATE } TRANSACTION

Syntax

 
GRANT [IMMUTABLE] { SHOW | TERMINATE } TRANSACTION[S] [( { * | user[, ...] } )]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to list and end the transactions and queries of all users or a particular user(s) in the home database, specific database(s), or all databases.
Table 18. Database privilege syntax

Command

GRANT TRANSACTION

Syntax

 
GRANT [IMMUTABLE] TRANSACTION [MANAGEMENT] [( { * | user[, ...] } )]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Grants the specified roles the privilege to manage the transactions and queries of all users or a particular user(s) in the home database, specific database(s), or all databases.
privileges grant and deny syntax database privileges
Figure 2. Syntax of GRANT and DENY Database Privileges

The database ACCESS privilege

The ACCESS privilege enables users to connect to a database or a remote database alias. With ACCESS you can run calculations, for example, RETURN 2 * 5 AS answer or call functions RETURN timestamp() AS time.

GRANT [IMMUTABLE] ACCESS
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

For example, to grant the role regularUsers the ability to access the database neo4j, use:

GRANT ACCESS ON DATABASE neo4j TO regularUsers

The ACCESS privilege can also be denied:

DENY [IMMUTABLE] ACCESS
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

For example, to deny the role regularUsers the ability to access to the remote database alias remote-db, use:

DENY ACCESS ON DATABASE `remote-db` TO regularUsers

The privileges granted can be seen using the SHOW PRIVILEGES command:

SHOW ROLE regularUsers PRIVILEGES AS COMMANDS
Table 19. Result
command

"DENY ACCESS ON DATABASE remote-db TO `regularUsers`"

"GRANT ACCESS ON DATABASE neo4j TO `regularUsers`"

Rows: 2

The database START/STOP privileges

The START privilege can be used to enable the ability to start a database:

GRANT [IMMUTABLE] START
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

For example, to grant the role regularUsers the ability to start the database neo4j, use:

GRANT START ON DATABASE neo4j TO regularUsers

The START privilege can also be denied:

DENY [IMMUTABLE] START
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

For example, to deny the role regularUsers the ability to start to the database neo4j, use:

DENY START ON DATABASE system TO regularUsers

The STOP privilege can be used to enable the ability to stop a database:

GRANT [IMMUTABLE] STOP
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

For example, to grant the role regularUsers the ability to stop the database neo4j, use:

GRANT STOP ON DATABASE neo4j TO regularUsers

The STOP privilege can also be denied:

DENY [IMMUTABLE] STOP
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

For example, to deny the role regularUsers the ability to stop the database neo4j, use:

DENY STOP ON DATABASE system TO regularUsers

The privileges granted can be seen using the SHOW PRIVILEGES command:

SHOW ROLE regularUsers PRIVILEGES AS COMMANDS
Table 20. Result
command

"DENY ACCESS ON DATABASE remote-db TO `regularUsers`"

"DENY START ON DATABASE system TO `regularUsers`"

"DENY STOP ON DATABASE system TO `regularUsers`"

"GRANT ACCESS ON DATABASE neo4j TO `regularUsers`"

"GRANT START ON DATABASE neo4j TO `regularUsers`"

"GRANT STOP ON DATABASE neo4j TO `regularUsers`"

Rows: 6

Note that START and STOP privileges are not included in the ALL DATABASE PRIVILEGES.

The INDEX MANAGEMENT privileges

Indexes can be created, deleted, or listed with the CREATE INDEX, DROP INDEX, and SHOW INDEXES commands. The privilege to do this can be granted with GRANT CREATE INDEX, GRANT DROP INDEX, and GRANT SHOW INDEX commands. The privilege to do all three can be granted with GRANT INDEX MANAGEMENT command.

Table 21. Index management privilege syntax

Command

GRANT { CREATE | DROP | SHOW } INDEX

Syntax

 
GRANT [IMMUTABLE] { CREATE | DROP | SHOW } INDEX[ES]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to create, delete, or show indexes in the home database, specific database(s), or all databases.
Table 22. Index management privilege syntax

Command

GRANT INDEX

Syntax

 
GRANT [IMMUTABLE] INDEX[ES] [MANAGEMENT]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to manage indexes in the home database, specific database(s), or all databases.

For example, to grant the role regularUsers the ability to create indexes on the database neo4j, use:

GRANT CREATE INDEX ON DATABASE neo4j TO regularUsers

The CONSTRAINT MANAGEMENT privileges

Constraints can be created, deleted, or listed with the CREATE CONSTRAINT, DROP CONSTRAINT and SHOW CONSTRAINTS commands. The privilege to do this can be granted with GRANT CREATE CONSTRAINT, GRANT DROP CONSTRAINT, GRANT SHOW CONSTRAINT commands. The privilege to do all three can be granted with GRANT CONSTRAINT MANAGEMENT command.

Table 23. Constraint management privilege syntax

Command

GRANT { CREATE | DROP | SHOW } CONSTRAINT

Syntax

 
GRANT [IMMUTABLE] { CREATE | DROP | SHOW } CONSTRAINT[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to create, delete, or show constraints on the home database, specific database(s), or all databases.
Table 24. Constraint management privilege syntax

Command

GRANT CONSTRAINT

Syntax

 
GRANT [IMMUTABLE] CONSTRAINT[S] [MANAGEMENT]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enable the specified roles to manage constraints on the home database, specific database(s), or all databases.

For example, to grant the role regularUsers the ability to create constraints on the database neo4j, use:

GRANT CREATE CONSTRAINT ON DATABASE neo4j TO regularUsers

The NAME MANAGEMENT privileges

The right to create new labels, relationship types, and property names is different from the right to create nodes, relationships, and properties. The latter is managed using database WRITE privileges, while the former is managed using specific GRANT/DENY CREATE NEW ... commands for each type.

Table 25. Node label management privileges syntax

Command

GRANT CREATE NEW LABEL

Syntax

 
GRANT [IMMUTABLE] CREATE NEW [NODE] LABEL[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to create new node labels in the home database, specific database(s), or all databases.
Table 26. Relationship type management privileges syntax

Command

GRANT CREATE NEW TYPE

Syntax

 
GRANT [IMMUTABLE] CREATE NEW [RELATIONSHIP] TYPE[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to create new relationship types in the home database, specific database(s), or all databases.
Table 27. Property name management privileges syntax

Command

GRANT CREATE NEW NAME

Syntax

 
GRANT [IMMUTABLE] CREATE NEW [PROPERTY] NAME[S]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to create new property names in the home database, specific database(s), or all databases.
Table 28. Node label, relationship type, and property name privileges management syntax

Command

GRANT NAME

Syntax

 
GRANT [IMMUTABLE] NAME [MANAGEMENT]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to create new labels, relationship types, and property names in the home database, specific database(s), or all databases.

The SHOW PRIVILEGES commands return the NAME MANAGEMENT privilege as the action token, when not using AS COMMANDS.

For example, to grant the role regularUsers the ability to create new properties on nodes or relationships on the database neo4j, use:

GRANT CREATE NEW PROPERTY NAME ON DATABASE neo4j TO regularUsers

Granting ALL DATABASE PRIVILEGES

The right to access a database, create and drop indexes and constraints and create new labels, relationship types or property names can be achieved with a single command:

GRANT [IMMUTABLE] ALL [[DATABASE] PRIVILEGES]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Note that the privileges for starting and stopping all databases, and transaction management, are not included in the ALL DATABASE PRIVILEGES grant. These privileges are associated with administrators while other database privileges are of use to domain and application developers.

For example, granting the abilities above on the database neo4j to the role databaseAdminUsers is done using the following query.

GRANT ALL DATABASE PRIVILEGES ON DATABASE neo4j TO databaseAdminUsers

The privileges granted can be seen using the SHOW PRIVILEGES command:

SHOW ROLE databaseAdminUsers PRIVILEGES AS COMMANDS
Table 29. Result
command

"GRANT ALL DATABASE PRIVILEGES ON DATABASE neo4j TO `databaseAdminUsers`"

Rows: 1

Granting TRANSACTION MANAGEMENT privileges

The right to run the commands SHOW TRANSACTIONS, TERMINATE TRANSACTIONS, and the deprecated procedures dbms.listTransactions, dbms.listQueries, dbms.killQuery, dbms.killQueries, dbms.killTransaction and dbms.killTransactions is now managed through the SHOW TRANSACTION and TERMINATE TRANSACTION privileges.

Table 30. Database privilege syntax

Command

GRANT SHOW TRANSACTION

Syntax

 
GRANT [IMMUTABLE] SHOW TRANSACTION[S] [( { * | user[, ...] } )]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to list transactions and queries for user(s) or all users in the home database, specific database(s), or all databases.
Table 31. Database privilege syntax

Command

GRANT TERMINATE TRANSACTION

Syntax

 
GRANT [IMMUTABLE] TERMINATE TRANSACTION[S] [( { * | user[, ...] } )]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to end running transactions and queries for user(s) or all users in the home database, specific database(s), or all databases.
Table 32. Database privilege syntax

Command

GRANT TRANSACTION

Syntax

 
GRANT [IMMUTABLE] TRANSACTION [MANAGEMENT] [( { * | user[, ...] } )]
  ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } }
  TO role[, ...]

Description

Enables the specified roles to manage transactions and queries for user(s) or all users in the home database, specific database(s), or all databases.

Note that the TRANSACTION MANAGEMENT privileges are not included in the ALL DATABASE PRIVILEGES.

For example, to grant the role regularUsers the ability to list transactions for user jake on the database neo4j, use:

GRANT SHOW TRANSACTION (jake) ON DATABASE neo4j TO regularUsers