Tutorial: Back up and restore a single database in a single instance

This tutorial provides a detailed example of how to back up and restore a database, in this example version 3.5, into a running (already upgraded/migrated) 4.x standalone instance.

The following example assumes that your database has users and roles associated with it and describes how to back it up, migrate it, and then restore it on a running standalone instance.

Prepare to back up the database

Before you perform the backup, it is good to take a note of the data and metadata of the database that you want to restore. You can use this information later to verify that the restore is successful and to recreate the database users and roles. In this example, the database uses the Movie Graph dataset from the Neo4j Browser → Favorites → Example Graphs.

In the 3.5 Neo4j instance, where the database is running, navigate to the /bin folder and log in to the Cypher^® Shell command-line console with your credentials. For more information about the Cypher Shell command-line interface (CLI) and how to use it, see Operations Manual → Cypher Shell.
```
./cypher-shell -u neo4j -p <password>
```
```
Connected to Neo4j at neo4j://localhost:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.
```

Run a query to count the number of nodes in the database.

MATCH (n) RETURN count(n) AS countNode;

+-----------+
| countNode |
+-----------+
| 171       |
+-----------+

1 row available after 22 ms, consumed after another 1 ms

Run a query to count the number of relationships.

MATCH (n)-[r]->() RETURN count(r) AS countRelationships;

+--------------------+
| countRelationships |
+--------------------+
| 253                |
+--------------------+

1 row available after 29 ms, consumed after another 0 ms

Run the following two queries to see if there is a schema defined.

CALL db.constraints()

0 rows available after 2 ms, consumed after another 0 ms

The result shows that there are no constraints defined.

CALL db.indexes;

+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| description              | indexName | tokenNames | properties | state    | type                  | progress | provider                              | id | failureMessage |
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "INDEX ON :Movie(title)" | "index_1" | ["Movie"]  | ["title"]  | "ONLINE" | "node_label_property" | 100.0    | {version: "1.0", key: "native-btree"} | 1  | ""             |
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

The result shows that there is one index defined on the property title of the :Movie node.

Run a query to list all users associated with this database and their roles.

CALL dbms.security.listUsers;

+-----------------------------------------+
| username | roles                | flags |
+-----------------------------------------+
| "user1"  | ["editor", "reader"] | []    |
| "neo4j"  | ["admin"]            | []    |
+-----------------------------------------+

2 rows available after 2 ms, consumed after another 0 ms

The result shows two users - the default neo4j user, which has admin privileges, and a custom user user1, which has the combined privileges of the built-in roles editor and reader.

Exit the Cypher Shell command-line console.
```
:exit;

Bye!
```

Back up the database

Now you are ready to back up the database.

Navigate to the /bin folder, and run the following command to back up the database in your targeted folder. If the folder where you want to place your backup does not exist, you have to create it. In this example, it is called /tmp/3.5.24.

./neo4j-admin backup --backup-dir=/tmp/3.5.24 --name=graphdbbackup

For details on performing a backup and the different command options, see Operations Manual 3.5 → Perform a backup.

Restore the database backup on a 4.x standalone instance

You have a running Neo4j 4.x instance, and you want to restore your backed up database in it.

In the neo4j.conf file of the 4.x standalone instance, set dbms.allow_upgrade=true.

If your Neo4j standalone instance is a version earlier than 4.1, you have to restart it for the configuration to take effect.
Navigate to the /bin folder and run the following command to restore the database backup.
```
./neo4j-admin restore --from=/tmp/3.5.24/graphdbbackup --database=graphdbbackup
```

Run the following command to verify that the database graphdbbackup exists:

ls -al ../data/databases

total 0
drwxr-xr-x@  6 username  staff   192  4 Dec 14:15 .
drwxr-xr-x@  5 username  staff   160  7 Dec 09:35 ..
drwxr-xr-x  42 username  staff  1344  4 Dec 14:15 graphdbbackup
drwxr-xr-x  37 username  staff  1184  4 Dec 14:06 neo4j
-rw-r--r--   1 username  staff     0  4 Dec 14:06 store_lock
drwxr-xr-x  38 username  staff  1216  4 Dec 14:06 system

However, restoring a database does not automatically create it. Therefore, it will not be visible if you do SHOW DATABASES in Cypher Shell or Neo4j Browser.

Change the active database to system (:USE system;), and create the graphdbbackup database.

CREATE DATABASE graphdbbackup;

0 rows available after 145 ms, consumed after another 0 ms

Verify that the graphdbbackup database is online.

SHOW DATABASES;

+-------------------------------------------------------------------------------------------------------+
| name            | address          | role         | requestedStatus | currentStatus | error | default |
+-------------------------------------------------------------------------------------------------------+
| "graphdbbackup" | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | FALSE   |
| "neo4j"         | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | TRUE    |
| "system"        | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | FALSE   |
+-------------------------------------------------------------------------------------------------------+

3 rows available after 175 ms, consumed after another 9 ms

Change the active database to graphdbbackup, and repeat steps 2, 3, and 4 from the section Prepare to back up the database, to verify that all the data has been successfully restored.

Recreate the database users and roles

You need to manually recreate all users and roles of the restored database using your notes from step 5 of the section Prepare to back up the database and the Cypher Manual → Cypher administration commands.

Example 1. Run the following commands against the system database to recreate the graphdbbackup database’s custom users and roles.

Create the user user1.

CREATE USER user1 IF NOT EXISTS
SET PASSWORD 'password'
SET STATUS ACTIVE;

Grant the role reader to the user user1.
```
GRANT ROLE reader TO user1;
```
Grant the role editor to the user user1.
```
GRANT ROLE editor TO user1;
```

Verify that the user user1 has the same roles as in the database backup.

SHOW USERS;

+---------------------------------------------------------------------+
| user    | roles                | passwordChangeRequired | suspended |
+---------------------------------------------------------------------+
| "neo4j" | ["admin"]            | FALSE                  | FALSE     |
| "user1" | ["editor", "reader"] | TRUE                   | FALSE     |
+---------------------------------------------------------------------+