B.3. Online database backup and restore

This tutorial provides a detailed example of an online backup and restore of a database.

In this tutorial, you will learn how to back up a single database in a running 3.5.x Neo4j instance and restore it in a running Neo4j 4.0.x instance, where there might be other databases as well. The tutorial covers the following topics:

In a Neo4j DBMS, every database is backed up individually. Therefore, it is very important to plan your back up strategy for each of them. For more detailed information on how to design an appropriate backup strategy for your setup, see Chapter 9, Backup.

Perform a database backup against a live 3.5.x Neo4j instance

You have a database that runs in a 3.5.x version of Neo4j, and you want to back it up without stopping it.

  1. Check the status of the Neo4j instance that contains the database that you want to back up.

    ~/neo4j-enterprise-3.5.x/bin$ ./neo4j status

    The Neo4j instance must be running.

  2. Check all available databases.

    ~/neo4j-enterprise-3.5.x/bin$  ls -al ../data/databases/
  3. Connect to the Neo4j instance using ./cypher-shell and your credentials.

    ~/neo4j-enterprise-3.5.x/bin$  ./cypher-shell -u neo4j -p admin
  4. Run a query to count the number of nodes in your database, which you can later use to verify that the restore is successful.

    neo4j> match (n) return count(n) as countNode;
    +-----------+
    | countNode |
    +-----------+
    | 171       |
    +-----------+
    
    1 row available after 22 ms, consumed after another 1 ms
  5. 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
  6. Exit the Cypher Shell command-line tool.

    neo4j> :exit
    
    Bye!
  7. Remove the temporary folder and its content. In this example the temporary folder is named /tmp/3517.

    ~/neo4j-enterprise-3.5.x/bin$ rm -rf /tmp/3517
  8. Create a new /tmp/3517 temporary folder, where you will place the database backup.

    ~/neo4j-enterprise-3.5.x/bin$ mkdir /tmp/3517
  9. Back up your database in this newly created folder using the command ./neo4j-admin backup --backup-dir=/tmp/3517 --name=graph.db. For details on performing a backup and the different command options, see Chapter 9, Backup.

    ~/neo4j-enterprise-3.5.x/bin$ ./neo4j-admin backup --backup-dir=/tmp/3517 --name=graph.db
  10. Verify that your backup is in the folder /tmp/3517.

    ~/neo4j-enterprise-3.5.x/bin$ ls -al /tmp/3517
    
    total 0
    drwxr-xr-x   3 username       wheel    96 21 Apr 13:48 .
    drwxrwxrwt   8 root           wheel   256 21 Apr 13:47 ..
    drwxr-xr-x  41 username       wheel  1312 21 Apr 13:48 graph.db
  11. (Optional) Stop Neo4j.

    ~/neo4j-enterprise-3.5.x/bin$ ./neo4j stop
    
    Stopping Neo4j.. stopped

Restore the database in a live 4.0.x Neo4j instance

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

  1. Open the /neo4j-enterprise-4.0.x/conf/neo4j.conf file of the Neo4j 4.0.x instance in which you want to restore the database and uncomment the setting dbms.allow_upgrade=true.
  2. Restart the Neo4j 4.0.x instance.

    ~/neo4j-enterprise-4.0.x/bin$ ./neo4j restart
  3. Check all available databases.

    ~/neo4j-enterprise-4.0.x/bin$  ls -al ../data/databases/
    
    total 0
    drwxr-xr-x@  5 username  staff   160 21 Apr 14:45 .
    drwxr-xr-x@  4 username  staff   128 31 Mar 11:25 ..
    drwxr-xr-x  37 username  staff  1184 21 Apr 14:45 neo4j
    -rw-r--r--   1 username  staff     0 21 Apr 14:45 store_lock
    drwxr-xr-x  38 username  staff  1216 21 Apr 14:45 system
  4. Connect to the Neo4j instance using ./cypher-shell and your credentials.

    ~/neo4j-enterprise-4.0.x/bin$  ./cypher-shell -u neo4j -p admin
  5. Change the active database to system, to be able to see all available databases and their current status.

    neo4j@neo4j> :use system
  6. Run a cypher query to list all databases.

    neo4j@system> show databases;
    +------------------------------------------------------------------------------------------------+
    | name     | address          | role         | requestedStatus | currentStatus | error | default |
    +------------------------------------------------------------------------------------------------+
    | "neo4j"  | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | TRUE    |
    | "system" | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | FALSE   |
    +------------------------------------------------------------------------------------------------+
    
    2 rows available after 3 ms, consumed after another 2 ms
  7. Exit the Cypher Shell command-line tool.

    neo4j@system> :exit
    Bye!
  8. Perform the restore operation.

    ~/neo4j-enterprise-4.0.x/bin$ ./neo4j-admin restore --from=/tmp/3517/graph.db --database mydatabase
  9. Connect to the Neo4j instance using ./cypher-shell and your credentials.

    ~/neo4j-enterprise-4.0.x/bin$ ./cypher-shell -u neo4j -p admin
  10. Change the active database to system, to be able to see all available databases and their current status.

    neo4j@neo4j> :use system
  11. Run a Cypher query to list all databases and see if the new database is displayed.

    neo4j@system> show databases;
    +------------------------------------------------------------------------------------------------+
    | name     | address          | role         | requestedStatus | currentStatus | error | default |
    +------------------------------------------------------------------------------------------------+
    | "neo4j"  | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | TRUE    |
    | "system" | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | FALSE   |
    +------------------------------------------------------------------------------------------------+
    
    2 rows available after 3 ms, consumed after another 2 ms

    The new database is not listed because it does not exist yet. You can either create it after running the restore command or in advance and use the option --force of the restore command to replace it. For more details on the restore command, see Section 9.3.1, “Restore command”.

  12. Create the database.

    neo4j@system> create database mydatabase;
  13. Again, run the query to see if mydatabase is now listed.

    neo4j@system> show databases;
    +------------------------------------------------------------------------------------------------+
    | name     | address          | role         | requestedStatus | currentStatus | error | default |
    +------------------------------------------------------------------------------------------------+
    | "mydatabase" | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | FALSE   |
    | "neo4j"  | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | TRUE    |
    | "system" | "localhost:7687" | "standalone" | "online"        | "online"      | ""    | FALSE   |
    +------------------------------------------------------------------------------------------------+
    
    3 rows available after 6 ms, consumed after another 2 ms
  14. Change the active database to mydatabase, to be able to verify the data consistency.

    neo4j@system> :use mydatabase
  15. Run the following queries to see if the number of nodes and relationships is the same as in the 3.5.x database you backed up.

    neo4j@mydatabase> match (n) return count(n) as countNode;
    +-----------+
    | countNode |
    +-----------+
    | 171       |
    +-----------+
    
    1 row available after 22 ms, consumed after another 1 ms
    neo4j@mydatabase> match (n)-[r]->() return count(r) as countRelationships;
    +--------------------+
    | countRelationships |
    +--------------------+
    | 253                |
    +--------------------+
    
    1 row available after 29 ms, consumed after another 0 ms
  16. Exit the Cypher Shell command-line tool.

    neo4j@mydatabase> :exit
    
    Bye!

Clean up your Neo4j 4.0.x instance

This tutorial is just an example of how to back up a database and restore it in a running version of Neo4j. If you have used a dummy database, you can safely remove it by using the Cypher Shell command drop database mydatabase;.