Using 'neo4j-admin database upload' in Neo4j 5.x to load a database dump to Neo4j Aura

The neo4j-admin tool in Neo4j version 5 is a command-line tool for managing and administering a Neo4j DBMS. The `neo4j-admin database` command helps perform database-specific administration tasks.

Particularly, neo4j-admin database upload can be used to upload a local Neo4j database dump into a Neo4j Aura instance. This also allows uploading a dump (backup) from a Neo4j Aura instance to the same or another Neo4j Aura instance.

The procedure can be applied to both AuraDB and AuraDS instances.

For Neo4j version 4 :

This article explains the procedure for using neo4j-admin database uploadcommand available in local installations of Neo4j 5.x . If you are using a 4.x version of Neo4j, please refer to the Running push-to-cloud to load a database dump file to Neo4j AuraDB article.

Important Note on compatibility between different source and destination versions of Neo4j:
Neo4j 5.x instances(Destination) are backwards compatible and can accept backups from Neo4j 4.x and Neoj 5.x (Source) instances.
Neo4j 4.x instances(Destination) are not forward compatible. 
i.e.

• You can import backups from Neo4j 5.x and 4.4 (and later) instances into a Neo4j 5.x instance.
• You can import backups from Neo4j 4.x instances into a Neo4j 4.x instance.
• You cannot import backups from Neo4j 5.x instances into a 4.x instance. 

The process can be split into five steps:

1. Identify / Create a backup for the source Aura instance.
2. Download the snapshot to your local computer.
3. Verify your local Neo4j installation has the neo4j-admin tool.
4. Upload your backup to the destination Neo4j Aura instance by running `neo4j-admin database upload`.
5. Monitor the status and availability of your Aura Instance during the upload.

Identify / Create a backup for the source Aura instance.

1. Login to the Aura Console.
2. Click the Aura instance you would like to create a backup for.
3. Click 'Take Snapshot' if you would like to create a new backup. Skip this step if you would like to use an existing snapshot.
   
4. Wait for the snapshot to complete.

Download the backup (snapshot/dump) to your local computer.

1. Click the three dots below the desired snapshot's 'Restore' button and select 'Export'.
   This will download the backup to your local computer.
   The download time will depend on the dump file's size (compressed datastore size) and your connection's speed.
   
   
2. The backup will be downloaded as 'neo4j.dump'.
   Note for AuraDS instances:
   Snapshots from AuraDS instances will be a tar file that contains the instance's dump and GDS metadata.
   Extract the .tar archive to get the 'neo4j.dump' file.
3. If you rename the backup, please ensure the file's name consists of simple ASCII characters, numbers, dots and dashes. Do not use underscores(_) or spaces in the dump file's name.

Verify your local Neo4j installation has the neo4j-admin tool.

You need a local Neo4j installation.

The easiest option is to use the neo4j Desktop to achieve this, as the neo4-admin tool is present by default. You could also use full installations of Neo4j Community/Enterprise editions or even docker images.

The root/base directory of your Neo4j installation is referred to as NEO4J_HOME, and its location would vary depending on your type of installation.

1. If you are using Neo4j Desktop, access the settings from a 5.x database and database and select Terminal. This will open the terminal directly into the database's NEO4J_HOME directory.
   
   For other installations, open a terminal and navigate to your NEO4J_HOME directory manually.
2. Run bin\neo4j-admin database upload --help .You should get a response similar to the below one:
   

Run the `neo4j-admin database upload` command

neo4j-admin database upload [--verbose] [--overwrite-destination[=true|false]]
                            --from-path=<path> [--to=<destination>] [--to-password=<password>]
                            --to-uri=<uri> [--to-user=<username>] <database>

For example, to upload a dump file named neo4jv5.dumpin the importfolder to an Aura instance of DBID 123456, overwriting the destination instance's content, with verbose output :

From a Linux or MAC computer:

bin/neo4j-admin database upload \
--verbose
--overwrite-destination=true \
--from-path=import \
--to-uri=neo4j+s://123456.databases.neo4j.io\
--to-user=neo4j \
--to-password=<myTopSecret> \
neo4jv5

From a Microsoft Windows computer:

bin\neo4j-admin database upload --verbose ^
--overwrite-destination=true ^
--from-path=import ^
--to-uri=neo4j+s://123456.databases.neo4j.io ^
--to-user=neo4j ^
--to-password=<myTopSecret>^
neo4jv5

Notes:

• In this example, we have included the username and password in the command line. But you can set it via environment variables (NEO4J_USERNAME, NEO4J_PASSWORD).
• If you haven't provided them in the command line and haven't set them as environment variables, you will be prompted for the same.
• As mentioned earlier, please ensure the dump file's name consists of simple ASCII characters, numbers, dots and dashes. Do not use underscores(_) or spaces in the dump file's name.
• DO NOT include the .dump extension while specifying the file's name in the neo4j-admin database uploadcommand.
• --verbose is optional 

Please refer to the Operations Manual on Neo4j Admin if you wish to know more about the command's syntax and the options.

Monitor the status and availability of your Aura Instance during the upload.

• The neo4j-admin command will display the status of the upload in the terminal itself.
• You could also monitor the status of the Aura instance in the Aura Console. 
  The instance's status will change to Loading while the uploaded dump is being processed and will change back to Running once the load job has been completed.

Status in the Aura console:

Status displayed in the command line:

bin\neo4j-admin database upload ^
--overwrite-destination=true ^
--from-path=import ^
--to-uri=neo4j+s://123456.databases.neo4j.io ^
--to-user=neo4j ^
--to-password=<my-secret> ^
neo4jv5
Upload
.................... 10%
.................... 20%
.................... 30%
.................... 40%
.................... 50%
.................... 60%
.................... 70%
.................... 80%
.................... 90%
.................... 100%
We have received your export and it is currently being loaded into your Aura instance.
You can wait here, or abort this command and head over to the console to be notified of when your database is running.
Import progress (estimated)
.................... 10%
.................... 20%
.................... 30%
.................... 40%
.................... 50%
.................... 60%
.................... 70%
.................... 80%
.................... 90%
.................... 100%
Your data was successfully pushed to Aura and is now running.
It is safe to delete the dump file now: ..\.Neo4jDesktop\relate-data\dbmss\dbms-a903e1e1-01b5-4d85-bc40-db3cf88b8582\import\neo4jv5.dump