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 allows the same server to manage multiple databases. 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 need to be executing 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.

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

2 rows

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

true

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

Try this query live.  none 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.  none 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.  none SHOW DEFAULT DATABASE

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

3 rows

"customers"

"localhost:7687"

"standalone"

"online"

"online"

""

false

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

true

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

Try this query live.  none 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.  none 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.  none 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.  none STOP DATABASE customers

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

Query. 

SHOW DATABASE customers

Table 5.5. Result
name address role requestedStatus currentStatus error default

1 row

"customers"

"localhost:7687"

"standalone"

"offline"

"offline"

""

false

Try this query live.  none 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.  none START DATABASE customers

The status of the started 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"

"online"

"online"

""

false

Try this query live.  none 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.  none 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.7. Result
name address role requestedStatus currentStatus error default

2 rows

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

true

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

Try this query live.  none 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.  none DROP DATABASE customers IF EXISTS