5.1. Databases

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

5.1.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.

5.1.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 5.1. Result
name address role requestedStatus currentStatus error default

4 rows

"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

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DATABASES

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

Query. 

SHOW DATABASE system

Table 5.2. Result
name address role requestedStatus currentStatus error default

1 row

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DATABASE system

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

Query. 

SHOW DEFAULT DATABASE

Table 5.3. Result
name address role requestedStatus currentStatus error

1 row

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DEFAULT DATABASE

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 5.4. Result
name currentStatus requestedStatus

3 rows

"neo4j"

"online"

"online"

"system"

"online"

"online"

"movies"

"online"

"online"

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DATABASES YIELD name, currentStatus, requestedStatus ORDER BY currentStatus WHERE name CONTAINS 'e'

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.

5.1.3. Creating databases

Databases can be created using CREATE DATABASE.

Query. 

CREATE DATABASE customers

0 rows, System updates: 1

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` CREATE DATABASE customers

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

Query. 

SHOW DATABASES

Table 5.5. Result
name address role requestedStatus currentStatus error default

5 rows

"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

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DATABASES

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

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` 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.

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` CREATE OR REPLACE DATABASE customers

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

5.1.4. Stopping databases

Databases can be stopped using the command STOP DATABASE.

Query. 

STOP DATABASE customers

0 rows, System updates: 1

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` STOP DATABASE customers

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

Query. 

SHOW DATABASE customers

Table 5.6. Result
name address role requestedStatus currentStatus error default

1 row

"customers"

"localhost:7687"

"standalone"

"offline"

"offline"

""

false

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DATABASE customers

5.1.5. Starting databases

Databases can be started using the command START DATABASE.

Query. 

START DATABASE customers

0 rows, System updates: 1

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` START DATABASE customers

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

Query. 

SHOW DATABASE customers

Table 5.7. Result
name address role requestedStatus currentStatus error default

1 row

"customers"

"localhost:7687"

"standalone"

"online"

"online"

""

false

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DATABASE customers

5.1.6. Deleting databases

Databases can be deleted using the command DROP DATABASE.

Query. 

DROP DATABASE customers

0 rows, System updates: 1

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` DROP DATABASE customers

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 5.8. Result
name address role requestedStatus currentStatus error default

4 rows

"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

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` SHOW DATABASES

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

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` 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

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` 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

Try this query live.  CREATE DATABASE `movies` CREATE DATABASE `northwind-graph` DROP DATABASE customers IF EXISTS DUMP DATA