Database administration

This section explains how to use Cypher to manage Neo4j database administrative privileges.

Administrators can use the following Cypher commands to manage Neo4j database administrative rights. The components of the database privilege commands are:

  • the commands:

    • 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 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 labels to be created so that future nodes can be assigned them.

    • CREATE NEW [RELATIONSHIP] TYPE - allows relationship types to be created, so that relationships can be assigned to them.

    • 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.

Table 1. General database privilege command syntax
Command Description
GRANT [IMMUTABLE] database-privilege ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}} TO role[, ...]

Grants a privilege to one or multiple roles.

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

Denies a privilege to one or multiple roles.

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

Revokes a granted privilege from one or multiple roles.

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

Revokes a denied privilege from one or multiple roles.

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

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.

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

privilege hierarchy database
Figure 1. Database privileges hierarchy
Table 2. Database privilege command syntax
Command Description
GRANT [IMMUTABLE] ACCESS
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

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

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

Grants the specified roles the privilege to start and stop the home database, specific database(s), or all databases.

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

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

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

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

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

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

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

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

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

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

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

Grants the specified roles the privilege to create new relationships types in the home database, specific database(s), or all databases.

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

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

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

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.

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

Grants the specified roles all privileges for the home, a specific, or all databases and remote database aliases.

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

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.

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

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.

grant privileges database
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 3. 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 4. 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 5. Index management command syntax
Command Description
GRANT [IMMUTABLE] {CREATE | DROP | SHOW} INDEX[ES]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

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

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

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 SHOW INDEXES privilege only affects the SHOW INDEXES command, and not the older procedures for listing indexes, such as db.indexes.

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 6. Constraint management command syntax
Command Description
GRANT [IMMUTABLE] {CREATE | DROP | SHOW} CONSTRAINT[S]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

Enables the specified roles to create, delete, or show constraints on the home database, specific database(s), or all databases.

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

Enables 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 SHOW CONSTRAINTS privilege only affects the SHOW CONSTRAINTS command, and not the older procedures for listing constraints, such as db.constraints.

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 7. Label, relationship type and property name management command syntax
Command Description
GRANT [IMMUTABLE] CREATE NEW [NODE] LABEL[S]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

Enables the specified roles to create new node labels in the home database, specific database(s), or all databases.

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

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

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

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

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

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

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

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

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 8. 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 9. Transaction management command syntax
Command Description
GRANT [IMMUTABLE] SHOW TRANSACTION[S] [( {* | user[, ...]} )]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

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.

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

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.

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

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