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.

In versions previous to Neo4j 5.22, the default store format for all new databases is aligned. From Neo4j 5.22, block is the default format for all newly-created databases as long as they do not have the db.format setting specified.
If you want to change it, you can set a new value for the db.format configuration in the neo4j.conf file.
Alternatively, you can set the store format of new databases using the CREATE DATABASE databasename OPTIONS {storeFormat: 'the-new-format'} command. However, if the store is seeded with seedURI or existingDataSeedInstance, or if the command is being used to mount pre-existing store files already present on the disk, they will use their current store format without any alterations.

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

Syntax

Command Syntax

CREATE DATABASE

 
CREATE DATABASE name [IF NOT EXISTS]
[TOPOLOGY n PRIMAR{Y|IES} [m SECONDAR{Y|IES}]]
[OPTIONS "{" option: value[, ...] "}"]
[WAIT [n [SEC[OND[S]]]]|NOWAIT]
CREATE OR REPLACE DATABASE name
[TOPOLOGY n PRIMAR{Y|IES} [m SECONDAR{Y|IES}]]
[OPTIONS "{" option: value[, ...] "}"]
[WAIT [n [SEC[OND[S]]]]|NOWAIT]

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 seedURI, 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 the 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.

storeFormat

aligned | standard | high_limit | block

Defines the store format if the database created is new. If the store is seeded with seedURI or existingDataSeedInstance, or if the command is being used to mount pre-existing store files already present on the disk, they will use their current store format without any alterations.

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.

Examples

Create a database

To create a database named customers, use the command CREATE DATABASE followed by the name of this database.

CREATE DATABASE customers

When you create a database, it shows up in the listing provided by the command SHOW DATABASES:

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

Create a database with WAIT

Sub-clause WAIT allows you to specify a time limit in which the command must complete and return.

CREATE DATABASE slow WAIT 5 SECONDS
Result
+-------------------------------------------------------+
| address          | state      | message     | success |
+-------------------------------------------------------+
| "localhost:7687" | "CaughtUp" | "caught up" | TRUE    |
+-------------------------------------------------------+

The success column provides an aggregate status of whether or not the command is considered successful. Thus, every row has the same value, determined on a successful completion without a timeout.

Create databases with IF NOT EXISTS or OR REPLACE

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 that nothing happens if the database already exists.

CREATE DATABASE customers IF NOT EXISTS

Second, adding OR REPLACE to the command deletes any existing database and creates a new one.

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.

Start databases

Databases can be started using the command START DATABASE.

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

Syntax

Command Syntax

START DATABASE

 
START DATABASE name [WAIT [n [SEC[OND[S]]]]|NOWAIT]

Examples

Start a database

Starting a database is a straightforward operation. Suppose you have a database named customers. To start it, use the following command:

START DATABASE customers

You can see the status of the started database by running the command SHOW DATABASE name.

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

Start a database with WAIT

You can start your database using WAIT sub-clause to ensure that the command waits for a specified amount of time until the database is started.

START DATABASE customers WAIT 5 SECONDS

Stop databases

Databases can be stopped using the command STOP DATABASE.

Syntax

Command Syntax

STOP DATABASE

 
STOP DATABASE name [WAIT [n [SEC[OND[S]]]]|NOWAIT]

Examples

Stop a database

To stop a database, use the following command:

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:

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

Stop a database with WAIT

You can also stop your database using the WAIT sub-clause, which allows you to specify the amount of time that the system should wait for the database to stop.

STOP DATABASE customers WAIT 10 SECONDS

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.