Introducing Neo4j 5: Unbounded Scale, Performance, and Agility | Learn More

Online Course Basic Neo4j 4.0 Administration Introduction to Neo4j Overview of Neo4j Administration Managing a Neo4j Instance Using cypher-shell to Manage Databases Copying Databases Changing the Database Location Checking Database Consistency Scripting to Manage Databases Configuring Plugins Managing HTTP Ports… Read more →

Using cypher-shell to Manage Databases

About this module

Next, you will learn how to perform some administrative tasks using the cypher-shell tool.

At the end of this module, you should be able to:

  • Create a Neo4j database.
  • Start a Neo4j database.
  • Use Cypher to load a Neo4j database.
  • Stop a Neo4j database.
  • Show the databases defined for the Neo4j instance.

Using cypher-shell

cypher-shell enables you to access the Neo4j database from a terminal window. You simply log into the database using cypher-shell with your credentials:

/usr/bin/cypher-shell -u <username> -p <password>

  • Once authenticated, you enter Cypher statements to execute just as you would in a Neo4j Browser session.
  • One caveat with cypher-shell, however is that all Cypher commands must end with ;.
  • You exit cypher-shell with the command :exit.
You can also manage databases using Neo4j Browser connected to the Neo4j instance. Since this training is intended for administrators, we use cypher-shell.

Example: Using cypher-shell

Here is an example showing that we can successfully log in to the database for the Neo4j instance, providing the default credentials neo4j/neo4j: Since this is the first login to the database, you must change the password from neo4j to a password you will remember.


In this example we changed the password to training-helps.

When you are done with cypher-shell, you enter :exit to exit.

If you set the environment variables NEO4J_USER and NEO4J_PASSWORD with their respective values, then you need not enter your credentials when logging into cypher-shell.

Example: Using cypher-shell providing credentials as arguments

You can also specify the username and password at the command level to use cypher-shell as arguments .


Accessing the system database

After you have successfully logged in to the Neo4j instance using cypher-shell, you can execute system commands against the Neo4j instance. By default, you are connected to the default Neo4j database, neo4j, which is a user database.

System commands use the system database and are primarily used to:

  • View the status of the databases being served by the Neo4j instance.
  • Create or drop a user database.
  • Start or stop a user database.

To access the system database, you enter :USE system.


Notice that the prompt neo4j@system tells us that all commands we enter will be against the system database.

Viewing databases for the Neo4j instance

Using the system database, you can view all of the databases served by this Neo4j instance by entering the command SHOW DATABASES;:


For all commands and cypher statements, you must end them with the ; character.

Here we see that this Neo4j instance that we have connected to has the system database and the neo4j database, which is the default name of the user database. A Neo4j instance has one system database and any number of user databases. After you have created more than one user database, you can configure any single user database as the default database.

Selecting the user database to access

In a client session, you can only access a single user database at a time, even though multiple databases may be online (started). You enter the :USE command to select the user database to connect to.

Here we switch back to the default, neo4j user database by specifying :USE neo4j. Then you can create or access the data in this user database. For example, we access the user database by creating a node with the label, Person and a name of “John Doe”, retrieving it, and then deleting it.


Sending Cypher statements to the cypher-shell session

When you log in to cypher-shell, you are connected to the default database, which is by default, neo4j.

You can use cypher-shell to populate the default database by sending pre-written Cypher statements to the database to execute.


Here we have download a file named movies.cypher that contains the Cypher statements to create the Movie graph. We simply use these Cypher statements as input when we start the cypher-shell session. They are automatically executed against the default database, neo4j.

Exercise #3: Using cypher-shell

In this Exercise, you will log in to the Neo4j instance with cypher-shell, change the password for the Neo4j instance, and use both the system and user database.

Before you begin

  1. Make sure you have a terminal window open where you have access to the Docker Neo4j instance for this course.
  2. Ensure that the Docker Neo4j instance is started.

Exercise steps:

  1. Log into the database with cypher-shell using the default credentials of neo4j/neo4j.
    [sudo] docker exec -it neo4j bin/cypher-shell
  2. Enter a new password that you will remember for the Neo4j instance. Note that this is not the same password as the user, neo4j.


  3. Exit out of cypher-shell.
  4. Start a cypher-shell session providing the -u and -p arguments.
  5. Use the system database to view all databases served by this Neo4j instance.


  6. Use the neo4j database and enter this Cypher statement:
    :use neo4j
    CREATE (:Person {name: '<your name'});


  1. Enter this Cypher statement to retrieve the node you just created:
MATCH (p:Person) RETURN p;


  1. Enter this Cypher statement to delete the node you just created:
MATCH (p:Person) DELETE p;


  1. Exit out of cypher-shell.
  2. Create the directory, files in your $HOME/docker-neo4j directory.
    cd ~/docker-neo4j
    mkdir files
  3. Download this file: to the files directory. This file contains the Cypher statements to load the database with movie data.

On OS X or Linux:

cd files
curl -O

On Windows, enter the above URL in a Web browser to download it. Then move it to the files folder.

  1. Invoke cypher-shell using movies.cypher as input.

On OS X or Linux:

cat ~/docker-neo4j/files/movies.cypher | docker exec --interactive neo4j bin/cypher-shell -u neo4j -p <passwordYouSpecified>

On Windows:

type files\movies.cypher | docker exec --interactive neo4j bin/cypher-shell -u neo4j -p <passwordYouSpecified>
  1. Start cypher-shell.
    [sudo] docker exec -it neo4j bin/cypher-shell -u neo4j -p <passwordYouSpecified>
  2. Execute these statements to confirm that the data was loaded into the user database:
CALL db.schema.visualization();
MATCH (p:Person) WHERE = 'Tom Hanks' RETURN p;

You should see something like this:


  1. Exit cypher-shell.

Exercise summary

You have now successfully started a cypher-shell client session that connects to the Neo4j instance. You typically use cypher-shell to execute Cypher against a user database, but you can also use it to perform some management tasks against the Neo4j instance by accessing the system database.

Creating databases

In Neo4j 4.0 Enterprise Edition, a Neo4j instance can host multiple user databases. To create a database, you connect to a started Neo4j instance with cypher-shell.

Here are the commands to create a database:

:USE system
CREATE DATABASE <database-name>

The database must not already exist (Check with the SHOW DATABASES command). This command creates the database and starts it.

Here are some database naming rules:

  • Length must be between 3 and 63 characters.
  • The first character of a name must be an ASCII alphabetic character.
  • Subsequent characters must be ASCII alphabetic or numeric characters, dots or dashes; [a..z][0..9].-
  • Names are case-insensitive and normalized to lowercase.
  • Names that begin with an underscore and with the prefix system are reserved for internal use.

All of the above commands are executed as Cypher commands, and the database name is subject to the standard Cypher restrictions on valid identifiers. In particular, the – (dash) character is not legal in Cypher variables, and therefore names with dashes need to be escaped by enclosing with back-ticks. For example,

Once a database is created, you cannot rename it.

Creating a database

Here we create a database named myfirstdatabase:


You can view the directory created for the database:


Starting and stopping a database

When a database is started, it uses VM resources. If the application is not actively using a database, you can stop it or restart it as needed.


Initial database configuration settings

The neo4j.conf file contains settings related to the name of the default database.

dbms.default_database specifies the default database clients will connect to when they do not specify a specific database.

dbms.max_databases specifies the maximum number of databases the Neo4j instance will allow.


Whenever you make a change to the neo4j.conf file, you must restart the Neo4j instance. ([sudo] systemctl restart neo4j) A best practice is to examine the log file for the Neo4j instance after you have made any configuration changes to ensure that the instance starts with no errors.

Deleting a database

You delete a database as shown here where we drop the database neo4j:


  • We can drop it because it is no longer the default database.
  • You need not stop the database before your drop it, but dropping it is a permanent deletion of the database.

Resetting a database

Suppose you have a database that has been populated with data, constraints, and/or indexes. You want to reuse the database and reset it to be empty with no data, constraints, or indexes. One way that you can achieve this is to drop the database and then create it again. Another way that you can do is is to use the following command:


Conditionally creating a database

If you are scripting the creation of databases, you can also create a database if it does not exist as follows:

You cannot use CREATE OR REPLACE together with IF NOT EXISTS.

Exercise #4: Creating and deleting a database

In this exercise you will gain some experience with creating and deleting a database.

Before you begin

  1. Make sure you have a terminal window open to your Neo4j Docker instance for this course.
  2. Ensure that the Docker Neo4j instance is started.

Exercise steps:

  1. Connect to the Neo4j instance with cypher-shell.
  2. Enter the command to show all databases.
    *Hint*: You must use the system database.


  1. Enter the command to create a database named databaseone.
  2. Enter the command to show all databases.


  3. Exit cypher-shell.
  4. View the directories where the databases are located for this instance.


Normally in Debian, you simply modify the conf/neo4j.conf file to make changes to the Neo4j instance when it starts. In a Docker Neo4j instance, it is a little different.

With the Docker Neo4j instance, it uses its own internal configuration, but you can override configuration settings in one of two ways.

  • One is with the settings you specify when you create the Docker instance (
  • The other way is to specify configuration values in a neo4j.conf file that is located in the shared volume used by the Docker Neo4j Docker instance. This is how you will add configuration changes to the Neo4j instance for this training.
  1. Create the neo4j.conf file in the $HOME/docker-neo4j/neo4j/conf directory created when you created the Docker Neo4j instance.
  2. Add the dbms.default_database property for databaseone to this file.

Your neo4j.conf file should be as follows:


  1. Restart the Docker Neo4j instance. Any change to the Neo4j configuration file requires a restart of the Neo4j instance.
    [sudo] docker stop neo4j
    [sudo] docker start neo4j
  2. Connect to the Neo4j instance with cypher-shell.
  3. Enter the command to show all databases to confirm that databaseone is now the default database.


  4. Drop the database neo4j.
  5. Enter the command to show all databases.


  6. Exit cypher-shell.

Taking it further

  • Try resetting a database that has data in it.
  • Try conditionally creating a database.

Exercise summary

You have now successfully added and dropped a database, as well as specifying a different database as the default database for clients.

Check your understanding

Question 1

By default, what are the names of the databases that are created when the Neo4j instance starts for the first time?

Select the correct answers.

  • graph
  • schema
  • neo4j
  • system

Question 2

Suppose you have started cypher-shell and have connected to the Neo4j instance. You want to create a database. What command must you enter before you create the database?

Select the correct answer.

  • :START neo4j
  • :START system
  • :USE neo4j
  • :USE system

Question 3

Suppose you have entered the following commands in cypher-shell to create the customers database and list all databases for the Neo4j instance. What is the next thing you should do to be able to create a node in the customers database from this session?

:USE system

Select the correct answer.

  • START DATABASE customers
  • ADD DATABASE customers
  • :USE neo4j
  • :USE customers


You should now be able to:

  • Create a Neo4j database.
  • Start a Neo4j database.
  • Use Cypher to load a Neo4j database.
  • Stop a Neo4j database.
  • Show the databases defined for the Neo4j instance.

Stay Connected

Sign up to find out more about Neo4j's upcoming events & meetups.