Migration Readiness Report

The Migration Readiness Report is only available for Instances on Neo4j version 4.

You can access the report for any version 4 instance via the link through the "Migration recommended" label on the Instance and Console pages.

Overview

This tool advises how to prepare an AuraDB v4 instance for migration to AuraDB latest. It reports current application queries, drivers, and database objects that would prevent you from migrating to AuraDB latest by providing information based on your recent usage history. In addition, you can also see Upgrade to Neo4j 5 within Aura for details on each identified issue and how to address it.

The main categories of issues that the Migration Readiness Report deals with are:

Cypher deprecations
Deprecated driver usage
Deprecated index types

The report page has a section for each category and a chart at the top titled "Deprecations and query timeline." This document explains each section, but the first is vital to controlling the others and is detailed in the following section. Note that the report only highlights issues that need to be addressed to make your code and queries compatible with AuraDB latest. Working on these issues presents a good opportunity to learn more about the advantages of the new features in the latest version.

From January 2025 Neo4j Server adopted calendar versioning (CalVer). Earlier versions, such as Neo4j 4 and 5 used semantic versioning (SemVer). Neo4j Aura uses only the latest version.

After implementing the recommendations from the report, you can use the test and live migration functionalities to prepare and, finally, guide you through the actual migration.

Control over the time window

In the "Deprecations and query timeline" section, you will see a chart displaying the usage of deprecated Cypher features and constructs and a general measure of query load on that system (query rate). You can disable and enable the data series by clicking on the legend. This can be helpful if you want to focus on something specific temporarily. The time frame can be controlled in two ways:

Zoom in by clicking on the chart area (start time) and drag while holding the mouse button down until the end time you want to select. The chart then zooms into the desired time frame.
Use the time selector in the top right corner of the chart. The chart updates with the desired time frame. The maximum time frame is 7 days of history.

To get back to the time range that was previously selected, double-click the chart area. Be aware that while the chart can display up to 7 days, the details for Cypher deprecations and deprecated driver usage can be retrieved for a maximum time range of 24 hours.

Cypher deprecations

After selecting a time frame of a maximum of 24 hours, use the button to fetch the deprecations logs in this section. Setting filters in the following popup window is optional but helpful if you want to see only specific entries. You can filter on:

Name of the deprecation
The user that executed the query
Driver that was used to execute the query
The application name that executed the query (if set)
The initiation type of the query
The query text or parts of it

Use the button in the popup to fetch applicable data to populate the report’s table.

Each row in the table represents a query in the selected timeframe that must be changed to seamlessly migrate to the latest Aura version. You have to rewrite those queries to only use Cypher supported by the latest Aura version.

All executions of the same query are aggregated into one row (see also the "Count" column). Use the magnifying glass at the start of each row to access a popup with more information about the query and suggestions on dealing with each issue. It also provides relevant links to the documentation for each deprecation.

The last column in the table of Cypher deprecations links to a view of this specific query in the Aura Query Log Analyzer tool, which can provide information on each execution of the selected query. The tool can view queries on all databases except the system database.

Deprecated driver usage

After selecting a time frame of a maximum of 24 hours, use the button to fetch the driver statistics in this section. By default, the filters in the popup are set to show only driver usage with potential issues in any database, including the system database. You can change those freely to see all driver usage, for example.

Use the button in the popup to fetch applicable data to populate the report’s table. Depending on the type of client accessing the Neo4j database, links are provided in the column “Latest version” to help with the upgrade.

Like the Cypher deprecations table, the last column links to a view of this specific driver’s executed queries in the Aura Query Log tool. The tool can provide information on each query execution in which the selected driver was used. The tool can view queries on all databases except the system database.

Deprecated index types

This section provides information on how to deal with deprecated indexes that may be used in version 4 but need to be handled before or while moving to the latest version.

This part involves manually running a provided Cypher query on your database to identify the deprecated indexes or constraints backed by deprecated indexes and then deciding how to best deal with them. For each deprecated index you can decide to manually create a replacement index before the migration (pre-create) or have the migration process create it for you. Pre-creating indexes will speed up the migration process but requires additional disk space. Not pre-creating indexes will lead to a longer migration process and may result in the need to manually recreate indexes after the migration, as the automatically migrated indexes may not be the optimal type for your application.

Further enhancements to this feature will be provided in the future.

Testing and executing the migration

After implementing the recommendations from the report, you can now test and run the migration. Only users with the permission to create and delete instances can access this functionality. It is highly recommended to run a test migration before attempting the live migration.

It is also advisable to set up a custom endpoint before the migration to speed up the switch to the migrated instance in your application. For more information, see Custom endpoints.

At this time, neither the test nor the live migration will include changes to the store format like moving to block format.

During the migration, the migration target instance may be shown with a few different statuses on the instance page, such as LOADING or OVERWRITING for example. Do not attempt to access the instance before the migration is safely finished. The progress of migration can be seen in the Migration Readiness Report of the original instance.

Run a test migration

Use the Run test migration buttons at the top or bottom of the page and then follow the steps outlined in the dialog boxes.

The steps of running a test migration are:

Carefully read and act upon the steps described in the "Read before test migration" dialog. Proceed only if you made the appropriate preparations (e.g. backups of your configurations).
Configure a target instance, as described in the next section.
1. If you have selected a new instance to migrate to: Download the new credentials for that instance.
Wait for the migration to finish.
Follow all steps outlined in "Next steps before finalizing the test migration" at the top of the Migration Readiness Report page. This includes all your testing on the migrated instance.
Once you are done with testing, click the "Finalize test migration" button and complete the dialog to remove your test instance.

You can repeat test migrations or run them in parallel as much as need. Be aware that running those instances incur the same cost as running any other instance of that size.

Configure target instance

An instance can either be migrated to a new instance or an instance that is already running the latest version of Aura and that fits the memory and storage configuration of the original instance. This means that if you select the second option, the instance you want to migrate to has to have at least the same amount of memory and storage as the original one.

Note that cloning into an existing instance overwrites all of its existing data and name. This action cannot be undone and may take longer than cloning to a new instance. If you still have data that you want to keep on the instance, it is advised to take a snapshot and download it before continuing.

In the process of migrating to a test instance, the instance will get a new name, regardless if it is new or existing. It starts with "[Testing]", followed by (most of) the original instance’s name and a test counter in parentheses e.g. "[Testing] original name (1)".

Testing the migrated instance

Once you see the box below on the Migration Readiness Report, your migrated instance is ready for testing. Follow the steps described and test your instance to make sure your live migration will go smoothly.

Finalize test migration

Once you are done with testing, use the "Finalize test migration" button. You will be asked to acknowledge the finalization since the test instance is deleted in the process. You can skip this step and keep the test instance, but this incurs a cost. Therefore, to minimize costs if you test manually, don’t forget to delete the test instance when you are done.

Run the live migration

Use the Live migration buttons at the top or bottom of the page and then follow the steps outlined in the dialog boxes.

The steps of running the live migration are:

Carefully read and act upon the steps described in the "Read before live migration" dialog. Proceed only if you made the appropriate preparations (e.g. backups of your configurations).
Carefully read and act upon the step described in the "Writes made on the v4 instance during migration" dialog. Make sure that your application will not write to the original instance during the migration to prevent this data from being lost.
Configure a target instance, as described in the next section.
1. If you have selected a new instance to migrate to: Download the new credentials for that instance.
Wait for the migration to finish.
Follow all steps outlined in "Next steps before finalizing the live migration" at the top of the Migration Readiness Report page. This includes all your testing on the migrated instance.
Once you are done with testing, click the "Finalize live migration" button and complete the dialog to remove your original version 4 instance.

There can only be one live migration in progress at any time. If you need to, you can restart the process at any point by removing the migrated instance until you finalize the migration by removing the original instance.

Configure target instance

Regardless of which option you select, the name of the migration target instance will be the same as the original instance.

Testing the migrated instance

Once you see the following box on the Migration Readiness Report your migrated instance is ready for testing. Follow the steps described and test your instance to make sure your application can work with it in your production system.

Finalize live migration

Once you are done with testing, use the "Finalize live migration" button. You will be asked to acknowledge the finalization since the original instance is permanently removed in the process. Additionally, when the dialog is completed, you will no longer have access to the Migration readiness report.

You can also postpone this step and keep the original instance e.g. as a rollback option. Be mindful that this means you have the running costs for both the migrated and the original instance. If you wish to remove the original instance later, you can revisit this step or remove it via the Aura console.