Default database in a cluster

Introduction

The default database, as defined by initial.dbms.default_database, is automatically created when the DBMS starts for the first time. This provides a user database to experiment with immediately. However, this creation is 'best effort' for reasons explained below, and users are encouraged to create their own default database for production use. If you create your own default database, even if you just DROP DATABASE neo4j and CREATE DATABASE neo4j, you do not have to be aware of the complexities below.

Automatic default database creation

The initial default database is created when the DBMS starts for the first time. It uses the following settings:

However, it uses the default primary and secondary counts (topology) as maximums, not as hard requirements. This is different to normal database creation, where if the requested topology cannot be satisfied, creation fails. For the automatic creation of the default database alone, if the requested topology cannot be satisfied, you get as many of each hosting type as can be satisfied by the current cluster. This means you may end up with a default database with as few as one primary and no secondaries, despite the default values being higher. It is also possible to configure a cluster where automatic creation of the default database is not possible when the DBMS starts up. In this case, creation fails, a warning is logged, and creation is not be re-attempted.

Automatic creation of the initial default database works as follows:

  • As the cluster starts for the first time, there is a configured threshold for how many servers are required to create the DBMS - dbms.cluster.minimum_initial_system_primaries_count.

  • Once a minimum of this many servers have discovered each other, the system database bootstraps, allowing creation of the DBMS.

  • The initial default database is created with those servers as the possible hosts.

  • If any of the servers block hosting the default database (see initial.server.denied_databases), they are not used.

  • If any of the servers restrict the mode they can host a database in, that is obeyed (see initial.server.mode_constraint).

  • If there are too few servers to allocate the requested number of primaries, whichever ones available are used. If there are zero available primaries, automatic creation fails.

  • If there are too few servers remaining after the primary allocation to satisfy the requested number of secondaries, whicever ones available are used.

Some possible behaviours that may be observed as a result of the above approach:

  • If initial.dbms.default_primaries_count is larger than dbms.cluster.minimum_initial_system_primaries_count, you are likely to get an initial default database with fewer primaries than the default. This is because DBMS initialisation only waits for the minimum system primaries.

  • If initial.dbms.default_secondaries_count plus initial.dbms.default_primaries_count is larger than dbms.cluster.minimum_initial_system_primaries_count, you are likely to get an initial default database with fewer secondaries than the default. This is because DBMS initialisation only waits for the minimum number of system primaries.

  • If you use initial.server.denied_databases to prevent the allocation of your default database to any of your initial servers, you may end up with fewer copies of the database than the default request, and possibly even no default database.

  • If you use initial.server.mode_constraint=SECONDARY for any of your initial servers, you may end up with fewer primary copies of the database than the default request, and possibly even no default database.

Changing default database topology

If the default database is initially created for you with a topology different to what you want, you can update it in the same way as any database, see Alter topology.

Creating your own default database

Once the DBMS has started, you can create your own database with your specified topology, and make it the default. See Change the default database. This can replace the existing default database, or have a different name.