Database administration

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

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

  • the command:

    • GRANT – gives privileges to roles.

    • DENY – denies privileges to roles.

    • REVOKE – removes granted or denied privilege from roles.

  • database-privilege

    • ACCESS - allows access to a specific database.

    • 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 future relationships can be created with these types.

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

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

    • 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 privileges assigned to the deleted database.

    • 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 database-privilege ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}} TO role[, ...]

Grant a privilege to one or multiple roles.

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

Deny a privilege to one or multiple roles.

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

Revoke a granted privilege from one or multiple roles.

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

Revoke a denied privilege from one or multiple roles.

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

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

DENY does NOT erase a granted privilege; they both exist. 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 ACCESS
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

Grant the specified roles the privilege to access the home database, specific database(s), or all databases.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Grant 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 ALL [[DATABASE] PRIVILEGES]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

Grant the specified roles all privileges for the home database, specific database(s), or all databases.

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

Grant 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 TRANSACTION [MANAGEMENT] [( {* | user[, ...]} )]
ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
TO role[, ...]

Grant 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

1. The database ACCESS privilege

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

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

For example, granting the ability to access the database neo4j to the role regularUsers is done using the following query.

GRANT ACCESS ON DATABASE neo4j TO regularUsers

The ACCESS privilege can also be denied.

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

For example, denying the ability to access to the database neo4j to the role regularUsers is done using the following query.

DENY ACCESS ON DATABASE neo4j 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 neo4j TO `regularUsers`"

"GRANT ACCESS ON DATABASE neo4j TO `regularUsers`"

Rows: 2

2. The database START/STOP privileges

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

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

For example, granting the ability to start the database neo4j to the role regularUsers is done using the following query.

GRANT START ON DATABASE neo4j TO regularUsers

The START privilege can also be denied.

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

For example, denying the ability to start to the database neo4j to the role regularUsers is done using the following query.

DENY START ON DATABASE system TO regularUsers

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

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

For example, granting the ability to stop the database neo4j to the role regularUsers is done using the following query.

GRANT STOP ON DATABASE neo4j TO regularUsers

The STOP privilege can also be denied.

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

For example, denying the ability to stop to the database neo4j to the role regularUsers is done using the following query.

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

3. 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 {CREATE | DROP | SHOW} INDEX[ES]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

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

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

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

For example, granting the ability to create indexes on the database neo4j to the role regularUsers is done using the following query.

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.

4. 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 {CREATE | DROP | SHOW} CONSTRAINT[S]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

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

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

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

For example, granting the ability to create constraints on the database neo4j to the role regularUsers is done using the following query.

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.

5. 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 CREATE NEW [NODE] LABEL[S]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

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

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

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

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

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

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

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

For example, granting the ability to create new properties on nodes or relationships in the database neo4j to the role regularUsers is done using the following query.

GRANT CREATE NEW PROPERTY NAME ON DATABASE neo4j TO regularUsers

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

7. Granting TRANSACTION MANAGEMENT privileges

The right to run the procedures dbms.listTransactions, dbms.listQueries, dbms.killQuery, dbms.killQueries, dbms.killTransaction and dbms.killTransactions are managed through the SHOW TRANSACTION and TERMINATE TRANSACTION privileges.

Table 9. Transaction management command syntax
Command Description
GRANT SHOW TRANSACTION[S] [( {* | user[, ...]} )]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

Enable 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 TERMINATE TRANSACTION[S] [( {* | user[, ...]} )]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

Enable 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 TRANSACTION [MANAGEMENT] [( {* | user[, ...]} )]
    ON {HOME DATABASE | DATABASE[S] {* | name[, ...]}}
    TO role[, ...]

Enable 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, granting the ability to list transactions for user jake in the database neo4j to the role regularUsers is done using the following query.

GRANT SHOW TRANSACTION (jake) ON DATABASE neo4j TO regularUsers