Databases

This section explains how to use Cypher to manage Neo4j databases: creating, deleting, starting and stopping individual databases within a single server.

1. Introduction

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.

Note that database names are an exception to the standard Cypher restrictions on valid identifiers. Database names may also include dots without the need to escape the name with backticks. For example, foo.bar.baz is a valid database name.

2. Listing databases

There are three different commands for listing databases. Listing all databases, listing a particular database or listing the default database.

Command syntax
SHOW { DATABASE db | DATABASES | DEFAULT DATABASE }
    [YIELD field1[, field2] [ORDER BY field1 [, field2]] [SKIP n] [LIMIT n]]
    [WHERE expression]

All available databases can be seen using the command SHOW DATABASES.

Query
SHOW DATABASES
Table 1. Result
name address role requestedStatus currentStatus error default

"movies"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

true

"northwind-graph"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

4 rows

A particular database can be seen using the command SHOW DATABASE name.

Query
SHOW DATABASE system
Table 2. Result
name address role requestedStatus currentStatus error default

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

1 row

The default database can be seen using the command SHOW DEFAULT DATABASE.

Query
SHOW DEFAULT DATABASE
Table 3. Result
name address role requestedStatus currentStatus error

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

1 row

It is also possible to filter and sort the results by using YIELD, ORDER BY and WHERE.

Query
SHOW DATABASES YIELD name, currentStatus, requestedStatus
ORDER BY currentStatus
WHERE name CONTAINS 'e'

In this example:

  • The number of columns returned has been reduced with the YIELD clause.

  • The order of the returned columns has been changed.

  • The results have been filtered to only show database names containing 'e'.

  • The results are ordered by the 'currentStatus' column using ORDER BY.

It is also possible to use SKIP and LIMIT to paginate the results.

Table 4. Result
name currentStatus requestedStatus

"neo4j"

"online"

"online"

"system"

"online"

"online"

"movies"

"online"

"online"

3 rows

Note that for failed databases, the currentStatus and requestedStatus are different. This often implies an error, but does not always. For example, a database may take a while to transition from offline to online due to performing recovery. Or, during normal operation a database’s currentStatus may be transiently different from its requestedStatus due to a necessary automatic process, such as one Neo4j instance copying store files from another. The possible statuses are initial, online, offline, store copying and unknown.

3. Creating databases

Databases can be created using CREATE DATABASE.

Query
CREATE DATABASE customers

0 rows, System updates: 1

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

Query
SHOW DATABASES
Table 5. Result
name address role requestedStatus currentStatus error default

"customers"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"movies"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

true

"northwind-graph"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

5 rows

This command is optionally idempotent, with the default behavior to throw an exception if the database already exists. Appending IF NOT EXISTS to the command will ensure that no exception is thrown and nothing happens should the database already exist. Adding OR REPLACE to the command will result in any existing database being deleted and a new one created.

Query
CREATE DATABASE customers IF NOT EXISTS
Query
CREATE OR REPLACE DATABASE customers

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

The IF NOT EXISTS and OR REPLACE parts of this command cannot be used together.

4. Stopping databases

Databases can be stopped using the command STOP DATABASE.

Query
STOP DATABASE customers

0 rows, System updates: 1

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

Query
SHOW DATABASE customers
Table 6. Result
name address role requestedStatus currentStatus error default

"customers"

"localhost:7687"

"standalone"

"offline"

"offline"

""

false

1 row

5. Starting databases

Databases can be started using the command START DATABASE.

Query
START DATABASE customers

0 rows, System updates: 1

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

Query
SHOW DATABASE customers
Table 7. Result
name address role requestedStatus currentStatus error default

"customers"

"localhost:7687"

"standalone"

"online"

"online"

""

false

1 row

6. Deleting databases

Databases can be deleted using the command DROP DATABASE.

Query
DROP DATABASE customers

0 rows, System updates: 1

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

Query
SHOW DATABASES
Table 8. Result
name address role requestedStatus currentStatus error default

"movies"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

true

"northwind-graph"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

4 rows

This command is optionally idempotent, with the default behavior to throw an exception if the database does not exists. Appending IF EXISTS to the command will ensure that no exception is thrown and nothing happens should the database not exist.

Query
DROP DATABASE customers IF EXISTS

The DROP DATABASE command will remove a database entirely. However, you can request that a dump of the store files is produced first, and stored in the path configured using the dbms.directories.dumps.root setting (by default <neo4j-home>/data/dumps). This can be achieved by appending DUMP DATA to the command (or DESTROY DATA to explicitly request the default behaviour). These dumps are equivalent to those produced by neo4j-admin dump and can be similarly restored using neo4j-admin load.

Query
DROP DATABASE customers DUMP DATA

The options IF EXISTS and DUMP DATA/ DESTROY DATA can also be combined. An example could look like this:

Query
DROP DATABASE customers IF EXISTS DUMP DATA