Administration and configuration

Administrative commands

Administrative commands should not be used during a rolling upgrade. For more information, see Upgrade and Migration Guide → Upgrade a cluster.

For detailed information on Cypher administrative commands, see Cypher Manual → Database management.

Before using administrative commands, it is important to understand the difference between stopped databases, and dropped databases:

  • Databases that are stopped with the STOP command are completely shutdown, and may be started again through the START command. In a cluster, as long as a database is in a shutdown state, it can not be considered available to other members of the cluster. It is not possible to do online backups against shutdown databases and they need to be taken into special consideration during disaster recovery, as they do not have a running Raft machine while shutdown.

  • Dropped databases are completely removed and are not intended to be used again at all.

The following Cypher commands are used on the system database to manage multiple databases:

Command Description

CREATE DATABASE name

Create and start a new database. Enterprise Edition

DROP DATABASE name

Drop (remove) an existing database. Enterprise Edition

ALTER DATABASE name

Alter (modify) an existing database. Enterprise Edition

START DATABASE name

Start a database that has been stopped.

STOP DATABASE name

Shut down a database.

SHOW DATABASE name

Show the status of a specific database.

SHOW DATABASES

Show the name and status of all the databases.

SHOW DEFAULT DATABASE

Show the name and status of the default database.

SHOW HOME DATABASE

Show the name and status of the home database for the current user.

Naming rules for databases are as follows:

  • Length must be between 3 and 63 characters.

  • The first character of a name must be an ASCII alphabetic character.

  • Subsequent characters must be ASCII alphabetic or numeric characters, dots or dashes; [a..z][0..9].-

  • Names are case-insensitive and normalized to lowercase.

  • Names that begin with an underscore and with the prefix system are reserved for internal use.

All of the above commands are executed as Cypher commands, and the database name is subject to the standard Cypher restrictions on valid identifiers. In particular, the - (dash) and . (dot) characters are not legal in Cypher variables, and therefore names with dashes must be enclosed within back-ticks. For example, CREATE DATABASE `main-db`. Database names are the only identifier for which dots don’t need to be escaped. For example, main.db is a valid database name.

It is possible to create an alias to refer to an existing database to avoid these restrictions. For more information, see Cypher Manual → Creating database aliases.

For detailed information on Cypher administrative commands, see Cypher Manual → Access Control.

For examples of using the Cypher administrative commands to manage multiple active databases, see Queries.

Configuration parameters

Configuration parameters are defined in the neo4j.conf file.

The following configuration parameters are applicable for managing databases:

Parameter name Description

initial.dbms.default_database

Name of the default database for the Neo4j instance. The database is created if it does not exist when the instance starts.

Default value: neo4j

In a clustered setup, the value of initial.dbms.default_database is only used to set the initial default database. To change the default database at a later point, see Change the default database.

Be aware that the automatically created initial default database may have a different topology to the default configuration values. See Default database in a cluster for more information.

dbms.max_databases

Maximum number of databases that can be used in a Neo4j single instance or cluster. The number includes all the online and offline databases. The value is an integer with a minimum value of 2. Enterprise Edition

Default value: 100

Once the limit has been reached, it is not possible to create any additional databases. Similarly, if the limit is changed to a number lower than the total number of existing databases, no additional databases can be created.

server.databases.default_to_read_only

Default mode of all databases. If this setting is set to true all existing and new databases will be in read only mode, and so will prevent write queries.

Default value: false

server.databases.read_only

List of database names for which to prevent write queries. This set can contain also not yet existing databases, but not the system database.

Regardless of settings of server.databases.default_to_read_only, server.databases.read_only and dbms.databases.writable the system database will never be read-only and will always accept write queries.

Another way of preventing writes is to set the database access to read-only using the ALTER DATABASE command.

Example configuration:

server.databases.read_only=["foo", "bar"]

dbms.databases.writable

List of database names for which to accept write queries. This set can contain also not yet existing databases.
The value of this setting is ignored if server.databases.default_to_read_only is set to false.
If a database name is present in both sets, the database will be read-only and prevent write queries.

If most of your databases would read-only with a few exceptions, it can be easier to set config_server.databases.default_to_read_only to true, and then put the names of the non read-only databases into dbms.databases.writeable.

Example configuration:

dbms.databases.writable=["foo", "bar"]

Although it is possible to achieve the same goal, i.e. set a database to read-only, both by using the Cypher command ALTER DATABASE and by using configuration parameters in neo4j.conf, it is important to understand the difference between the two. ALTER DATABASE foo SET ACCESS READ ONLY effectively sets the database foo to read-only across the entire DBMS.

Using configuration parameters is more subtle and allows you to configure access on each instance separately, in case of a cluster for example. If you use server.databases.default_to_read_only all databases on that instance are set to read-only.

If both the Cypher command and the configuration parameters are used and they contain conflicting information, the database in question is set to read-only.