Create, start, and stop databases

Neo4j supports the management of multiple databases within the same DBMS. The metadata for these databases, including the associated security model, is maintained in a special database called the system database. All multi-database administrative commands must be run against the system database. These administrative commands are automatically routed to the system database when connected to the DBMS over Bolt.

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

Create databases

You can create a database using the Cypher command CREATE DATABASE.

Database names are subject to the rules specified in Database names section. Having dots (.) in the database names is not recommended. This is due to the difficulty of determining if a dot is part of the database name or a delimiter for a database alias in a composite database.
Query
CREATE DATABASE customers

In Neo4j, the default store format for all new databases is aligned. If you want to change it, you can set a new value for the db.format configuration in the neo4j.conf file.

See Store formats, for more details about available database store formats in Neo4j.

When a database has been created, it will show up in the listing provided by the command SHOW DATABASES.

Query
SHOW DATABASES YIELD name
Result
+-------------+
| name        |
+-------------+
| "customers" |
| "movies"    |
| "neo4j"     |
| "system"    |
+-------------+

Use IF NOT EXISTS or OR REPLACE when creating databases

The CREATE DATABASE command is optionally idempotent, with the default behavior to fail with an error if the database already exists. There are two ways to circumvent this behavior.

First, appending IF NOT EXISTS to the command ensures that no error is returned and nothing happens should the database already exist.

Query
CREATE DATABASE customers IF NOT EXISTS

Second, adding OR REPLACE to the command results in any existing database being deleted and a new one being created.

Query
CREATE OR REPLACE DATABASE customers

This is equivalent to running DROP DATABASE customers IF EXISTS followed by CREATE DATABASE customers.

The behavior of IF NOT EXISTS and OR REPLACE apply to both standard and composite databases (e.g. a composite database may replace a standard database or another composite database).

The IF NOT EXISTS and OR REPLACE parts of these commands cannot be used together.

Create database options

The CREATE DATABASE command can have a map of options, e.g. OPTIONS {key: 'value'}.

Key Value Description

existingData

use

Controls how the system handles existing data on disk when creating the database. Currently this is only supported with existingDataSeedInstance and must be set to use which indicates the existing data files should be used for the new database.

existingDataSeedInstance

ID of the cluster server

Defines which server is used for seeding the data of the created database. The server ID can be found in the serverId column after running SHOW SERVERS.

seedURI

URI to a backup or a dump from an existing database.

Defines an identical seed from an external source which will be used to seed all servers.

seedConfig

comma separated list of configuration values.

Defines additional configuration specified by comma separated name=value pairs that might be required by certain seed providers.

seedCredentials

credentials

Defines credentials that need to be passed into certain seed providers.

txLogEnrichment

FULL | DIFF | NONE

Defines level of enrichment applied to transaction logs for Change Data Capture (CDC) purposes.

For details about enrichment mode, see Change Data Capture Manual → Enable CDC on self-managed instances → Set the enrichment mode.

The existingData, existingDataSeedInstance, seedURI, seedConfig, and seedCredentials options cannot be combined with the OR REPLACE part of this command. More details about seeding options can be found in Seed a cluster.

Start databases

Databases can be started using the command START DATABASE.

Query
START DATABASE customers

Both standard databases and composite databases can be started using this command.

The status of the started database can be seen using the command SHOW DATABASE name.

Query
SHOW DATABASE customers YIELD name, requestedStatus, currentStatus
Result
+-----------------------------------------------+
| name        | requestedStatus | currentStatus |
+-----------------------------------------------+
| "customers" | "online"        | "online"      |
+-----------------------------------------------+

Stop databases

Databases can be stopped using the command STOP DATABASE.

Query
STOP DATABASE customers

Both standard databases and composite databases can be stopped using this command.

The status of the stopped database can be seen using the command SHOW DATABASE name.

Query
SHOW DATABASE customers YIELD name, requestedStatus, currentStatus
Result
+-----------------------------------------------+
| name        | requestedStatus | currentStatus |
+-----------------------------------------------+
| "customers" | "offline"       | "offline"     |
+-----------------------------------------------+

Databases that are stopped with the STOP command are completely shut down 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. Unlike stopped databases, dropped databases are completely removed and are not intended to be used again at all.