Fleet manager: document migration #1043
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,180 @@ | ||
| = Migrate a self-managed deployment to Aura | ||
| :description: This page describes how to migrate a self-managed Neo4j deployment to Aura using Fleet Manager. | ||
| :min-version: 2026.05.0 | ||
| :min-version-plugin: 5.26.0 | ||
| :min-plugin-version: 1.2.0 | ||
|
|
||
| Fleet Manager can guide you through migrating a monitored self-managed Neo4j deployment to Aura, directly from the Aura console. | ||
| The migration is driven by a wizard that helps you check compatibility, choose a destination Aura instance, and transfer your data. | ||
|
|
||
| You can transfer your data in two ways: | ||
|
|
||
| * *Automatic* (recommended) – Fleet Manager stops the database, creates a dump, and uploads and imports it into Aura for you. | ||
| * *Manual* – you create and upload the database dump yourself using `neo4j-admin`, following an online checklist. | ||
|
|
||
| == Requirements | ||
|
|
||
| To migrate a self-managed deployment to Aura using Fleet Manager: | ||
|
|
||
| * The deployment must be *monitored* by Fleet Manager and in the *RUNNING* state. | ||
| See xref:fleet-management/setup.adoc[Add a deployment] for how to set up monitoring. | ||
| * The deployment must run *Neo4j {min-version} or later*, or *Neo4j {min-version-plugin} or later with Fleet Management plugin {min-plugin-version} or later*. | ||
| * You must have the *Project admin* role for the Aura project where the deployment is monitored. | ||
|
|
||
| == Start a migration | ||
|
|
||
| You can start a migration from a self-managed deployment in the Aura console: | ||
|
|
||
| * Select *Migrate to Aura* from the deployment's action menu (or the *Migrate to Aura* button) to open the migration wizard. | ||
| * Select *Migrate to Aura with one click* to migrate to a new instance using a recommended configuration, without going through the full wizard (see <<one-click-migration>>). | ||
|
|
||
| [[one-click-migration]] | ||
| == One-click migration | ||
|
|
||
| *Migrate to Aura with one click* creates a new Aura instance using a configuration recommended from your deployment's recent usage, then starts the migration. | ||
|
|
||
| A confirmation dialog shows the recommended configuration before you proceed: | ||
|
|
||
| * Self-managed disk usage | ||
| * Cloud provider | ||
| * Region | ||
| * Tier | ||
| * Memory | ||
| * Storage | ||
|
|
||
| The dialog also shows the estimated cost of the new instance. | ||
| Select *Migrate* to start or *Cancel* to go back. | ||
|
|
||
| == Migration wizard | ||
|
|
||
| The wizard has three steps: *Check compatibility*, *Choose Aura destination*, and *Transfer data*. | ||
|
|
||
| === Step 1: Check compatibility | ||
|
|
||
| This step helps you verify that your workload is compatible with Aura before migrating. | ||
|
|
||
| *Check your driver versions*:: | ||
| If you connect using one of Neo4j's official drivers, make sure you are on a version supported by Aura. | ||
| Only some 4.4 driver versions work with Aura, so updating to 5.x drivers or later is recommended (for more information see the https://support.neo4j.com/s/article/10845868658579[driver support article]). | ||
|
|
||
| *Identify queries or workloads that can't run on Aura*:: | ||
| + | ||
| [NOTE] | ||
| ==== | ||
| Automatic workload analysis will be available in future versions of Neo4j. | ||
| ==== | ||
| + | ||
| Manually review your workload. Aura does not allow custom plugins or arbitrary procedures and functions: | ||
| + | ||
| ** A subset of APOC Core is available. See xref:apoc.adoc[APOC support]. | ||
| ** APOC Extended and custom plugins are not supported. | ||
| ** User-defined procedures and functions are not available on Aura. | ||
|
|
||
| You must acknowledge that verifying compatibility is your responsibility before continuing. | ||
|
|
||
| === Step 2: Choose Aura destination | ||
|
|
||
| Choose where to migrate your data: | ||
|
|
||
| *Migrate to a new instance*:: | ||
| Create a new Aura instance for the migration. | ||
| The wizard pre-fills a recommended size based on your deployment's usage and hides unsupported (too-small) sizes. | ||
| Migrating to AuraDB Free is not supported. | ||
| The estimated cost is shown before you create the instance. | ||
|
|
||
| *Migrate to an existing instance*:: | ||
| Select a running Aura instance as the target. | ||
| + | ||
| [WARNING] | ||
| ==== | ||
| All existing data in the selected instance is *deleted* and replaced with data from your deployment. | ||
| You must acknowledge this before continuing. | ||
| ==== | ||
| + | ||
| The target instance must: | ||
| + | ||
| * Have more than double the storage of your database dump file. | ||
| * Have enough RAM for your query load and memory requirements. | ||
| * Not be an AuraDB Free instance. Migrating to AuraDB Free is not supported. | ||
|
|
||
| === Step 3: Transfer data | ||
|
|
||
| Choose how to transfer your data. | ||
|
|
||
| ==== Automatic (recommended) | ||
|
|
||
| Fleet Manager performs the migration for you. It: | ||
|
|
||
| . Shuts down the `neo4j` database on the self-managed deployment. | ||
| . Creates a database dump. | ||
| . Restarts the `neo4j` database on the self-managed deployment. | ||
| . Creates or selects the target Aura instance. | ||
| . Uploads the dump to Aura and starts the import. | ||
| . Waits for the import to complete. | ||
|
|
||
| You must consent to these actions – including the database shutdown – before selecting *Start migration*. | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| This process can take several hours depending on the size of the database. | ||
| You can monitor progress in the Aura console (see <<monitor-migration-status>>). | ||
| ==== | ||
|
|
||
| ==== Manual | ||
|
|
||
| You migrate the data yourself by following an in-console checklist. Mark each section *Done* to complete the guide. | ||
|
|
||
| . *Create a database dump* | ||
| + | ||
| Open a console in the Neo4j installation directory, stop the database, and create the dump: | ||
| + | ||
| [source,shell] | ||
| ---- | ||
| # Stop the database | ||
| bin/neo4j stop | ||
|
|
||
| # Create the dump (note the path -- you need it later) | ||
| bin/neo4j-admin database dump neo4j --to-path=PATH_TO_DUMP | ||
| ---- | ||
| + | ||
| Make a note of the dump file size to help choose the correct Aura instance size. | ||
|
|
||
| . *Check the target Aura instance state* | ||
| + | ||
| Confirm the selected target Aura instance is in the expected state before uploading. | ||
|
|
||
| . *Upload the database dump to Aura* | ||
| + | ||
| [IMPORTANT] | ||
| ==== | ||
| After a successful upload, the Aura instance is in a `LOADING` state and unavailable until the dump is processed. This can take several hours depending on database size. | ||
| ==== | ||
| + | ||
| Upload using `neo4j-admin` (recommended for large dumps): | ||
| + | ||
| [source,shell] | ||
| ---- | ||
| bin/neo4j-admin database upload neo4j \ | ||
| --from-path=PATH_TO_DUMP \ | ||
| --to-uri=BOLT_URL \ | ||
| --overwrite-destination=false | ||
| ---- | ||
| + | ||
| Alternatively, for dumps *4 GB or smaller*, you can restore directly from the Aura console: open *Inspect* on the Aura instance, select *Restore from backup* file, and drag and drop the `.dump` file. | ||
|
|
||
| [[monitor-migration-status]] | ||
| == Monitor migration status | ||
|
|
||
| After a migration starts, open the status page from the deployment's *Migration status* menu item or the *View migration status* banner. | ||
|
|
||
| A migration can be in one of three states: *running*, *completed* (success), or *failed*. | ||
|
|
||
| The status page shows a timeline of four stages: | ||
|
|
||
| . *Aura instance creation* | ||
| . *Database dump* | ||
| . *Upload to Aura* | ||
| . *Import into Aura* | ||
|
|
||
| Each stage shows its progress (pending, in progress, success, or failure). | ||
| If a stage fails, you can expand *Standard output*, *Standard error*, and *Stack trace* sections to inspect the logs. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Contributor
Author
There was a problem hiding this comment. actually this page is outdated. There is a separate issue to fix it |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we link to migration.adoc here? I think it's currently not entirely obvious that this page concerns the automatic flow(s) only.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the "online checklist" in this sentence refers to the manual data transfer step of the migration wizard, so it is self-contained. I see the
migration.adocas kind of external to this page.