Migrate a single instance
This chapter describes the necessary steps to migrate a single instance from Neo4j 3.5 directly to 4.x.
The migration of a single instance from Neo4j 3.5 to 4.x requires downtime. Therefore, it is recommended to perform a test migration in a production-like environment to get information on the duration of the downtime. |
Prerequisites
Ensure that you have completed all tasks on the Migration checklist.
Prepare for the migration
-
Verify that you have shut down the Neo4j DBMS. You can check the neo4j.log.
-
Install the Neo4j version that you want to migrate to. For more information on how to install the distribution that you are using, see Operations Manual → Installation.
-
Replace the neo4j.conf file with the one that you have prepared in section Prepare a new neo4j.conf file to be used by the new installation.
-
Copy all the files used for encryption, such as private key, public certificate, and the contents of the trusted and revoked directories (located in <neo4j-home>/certificates/).
If your old installation has modified configurations starting with
dbms.directories.*
or the settingdbms.active_database
, verify that the newneo4j.conf
file is configured properly to find these directories. -
If you are using custom plugins, make sure they are updated and compatible with the new version, and place them in the /plugins directory.
Migrate the data
Using the 4.0 Neo4j Admin tool, migrate the data store of your 3.5 Neo4j.
The neo4j-admin copy
command also removes any inconsistent nodes, properties, and relationships and does not copy them to the newly created store.
-
From the <neo4j-home> folder, run the following command to copy the data store. You need to specify the old store location and the name for the target updated database:
bin/neo4j-admin copy --from-path=/path/to/3.5.x/graph.db --to-database=<db_name>
Starting to copy store, output will be saved to: $neo4j_home/logs/neo4j-admin-copy-2020-11-26.16.07.19.log 2020-11-26 16:07:19.939+0000 INFO [StoreCopy] ### Copy Data ### 2020-11-26 16:07:19.940+0000 INFO [StoreCopy] Source: /path/to/3.5.x/graph.db (page cache 8m) 2020-11-26 16:07:19.940+0000 INFO [StoreCopy] Target: $neo4j_home/data/databases/database (page cache 8m) 2020-11-26 16:07:19.940+0000 INFO [StoreCopy] Empty database created, will start importing readable data from the source. 2020-11-26 16:07:21.661+0000 INFO [o.n.i.b.ImportLogic] Import starting Import starting 2020-11-26 16:07:21.699+0000 Estimated number of nodes: 50.00 k Estimated number of node properties: 50.00 k Estimated number of relationships: 0.00 Estimated number of relationship properties: 50.00 k Estimated disk space usage: 2.680MiB Estimated required memory usage: 8.598MiB (1/4) Node import 2020-11-26 16:07:22.220+0000 Estimated number of nodes: 50.00 k Estimated disk space usage: 1.698MiB Estimated required memory usage: 8.598MiB .......... .......... .......... .......... .......... 5% ∆239ms .......... .......... .......... .......... .......... 10% ∆1ms .......... .......... .......... .......... .......... 15% ∆1ms .......... .......... .......... .......... .......... 20% ∆0ms .......... .......... .......... .......... .......... 25% ∆1ms .......... .......... .......... .......... .......... 30% ∆0ms .......... .......... .......... .......... .......... 35% ∆0ms .......... .......... .......... .......... .......... 40% ∆1ms .......... .......... .......... .......... .......... 45% ∆0ms .......... .......... .......... .......... .......... 50% ∆1ms .......... .......... .......... .......... .......... 55% ∆0ms .......... .......... .......... .......... .........- 60% ∆51ms .......... .......... .......... .......... .......... 65% ∆0ms .......... .......... .......... .......... .......... 70% ∆0ms .......... .......... .......... .......... .......... 75% ∆1ms .......... .......... .......... .......... .......... 80% ∆0ms .......... .......... .......... .......... .......... 85% ∆0ms .......... .......... .......... .......... .......... 90% ∆1ms .......... .......... .......... .......... .......... 95% ∆0ms .......... .......... .......... .......... .......... 100% ∆0ms (2/4) Relationship import 2020-11-26 16:07:22.543+0000 Estimated number of relationships: 0.00 Estimated disk space usage: 1006KiB Estimated required memory usage: 15.60MiB (3/4) Relationship linking 2020-11-26 16:07:22.879+0000 Estimated required memory usage: 7.969MiB (4/4) Post processing 2020-11-26 16:07:23.272+0000 Estimated required memory usage: 7.969MiB -......... .......... .......... .......... .......... 5% ∆356ms .......... .......... .......... .......... .......... 10% ∆0ms .......... .......... .......... .......... .......... 15% ∆1ms .......... .......... .......... .......... .......... 20% ∆0ms .......... .......... .......... .......... .......... 25% ∆0ms .......... .......... .......... .......... .......... 30% ∆1ms .......... .......... .......... .......... .......... 35% ∆0ms .......... .......... .......... .......... .......... 40% ∆0ms .......... .......... .......... .......... .......... 45% ∆1ms .......... .......... .......... .......... .......... 50% ∆0ms .......... .......... .......... .......... .......... 55% ∆0ms .......... .......... .......... .......... .......... 60% ∆0ms .......... .......... .......... .......... .......... 65% ∆1ms .......... .......... .......... .......... .......... 70% ∆0ms .......... .......... .......... .......... .......... 75% ∆0ms .......... .......... .......... .......... .......... 80% ∆0ms .......... .......... .......... .......... .......... 85% ∆0ms .......... .......... .......... .......... .......... 90% ∆0ms .......... .......... .......... .......... .......... 95% ∆1ms .......... .......... .......... .......... .......... 100% ∆0ms IMPORT DONE in 2s 473ms. Imported: 1 nodes 0 relationships 1 properties Peak memory usage: 15.60MiB 2020-11-26 16:07:24.140+0000 INFO [o.n.i.b.ImportLogic] Import completed successfully, took 2s 473ms. Imported: 1 nodes 0 relationships 1 properties 2020-11-26 16:07:24.668+0000 INFO [StoreCopy] Import summary: Copying of 100704 records took 4 seconds (25176 rec/s). Unused Records 100703 (99%) Removed Records 0 (0%) 2020-11-26 16:07:24.669+0000 INFO [StoreCopy] ### Extracting schema ### 2020-11-26 16:07:24.669+0000 INFO [StoreCopy] Trying to extract schema... 2020-11-26 16:07:24.920+0000 INFO [StoreCopy] ... found 1 schema definitions. The following can be used to recreate the schema: 2020-11-26 16:07:24.922+0000 INFO [StoreCopy] CALL db.createIndex('index_5c0607ad', ['Person'], ['name'], 'native-btree-1.0', {`spatial.cartesian-3d.min`: [-1000000.0, -1000000.0, -1000000.0],`spatial.cartesian.min`: [-1000000.0, -1000000.0],`spatial.wgs-84.min`: [-180.0, -90.0],`spatial.cartesian-3d.max`: [1000000.0, 1000000.0, 1000000.0],`spatial.cartesian.max`: [1000000.0, 1000000.0],`spatial.wgs-84-3d.min`: [-180.0, -90.0, -1000000.0],`spatial.wgs-84-3d.max`: [180.0, 90.0, 1000000.0],`spatial.wgs-84.max`: [180.0, 90.0]}) 2020-11-26 16:07:24.923+0000 INFO [StoreCopy] You have to manually apply the above commands to the database when it is stared to recreate the indexes and constraints. The commands are saved to $neo4j_home/logs/neo4j-admin-copy-2020-11-26.16.07.19.log as well for reference.
When using the direct path, indexes are not automatically migrated so you have to recreate them. After running the store migration, the
neo4j-admin copy
command extracts the schema and generates a list of commands you can use to recreate your schema on the new 4.x store. The recreate schema commands are also saved in the migration log file, located in the /logs directory. -
Start the server.
bin/neo4j start
or
systemctl start neo4j
Copying a database does not automatically create it. Therefore, it will not be visible if you do
SHOW DATABASES
in Cypher Shell or Neo4j Browser. -
Log in to the Cypher® Shell command-line console, change the active database to
system
(:USE system;
), and create the<db_name>
database. For more information about the Cypher Shell command-line interface (CLI) and how to use it, see Operations Manual → Cypher Shell.CREATE DATABASE <db_name>;
-
Using the new database (
:USE <db_name>;
), recreate any indexes or constraints that were identified by theneo4j-admin copy
command.CALL db.createIndex('index_5c0607ad', ['Person'], ['name'], 'native-btree-1.0', {`spatial.cartesian-3d.min`: [-1000000.0, -1000000.0, -1000000.0],`spatial.cartesian.min`: [-1000000.0, -1000000.0],`spatial.wgs-84.min`: [-180.0, -90.0],`spatial.cartesian-3d.max`: [1000000.0, 1000000.0, 1000000.0],`spatial.cartesian.max`: [1000000.0, 1000000.0],`spatial.wgs-84-3d.min`: [-180.0, -90.0, -1000000.0],`spatial.wgs-84-3d.max`: [180.0, 90.0, 1000000.0],`spatial.wgs-84.max`: [180.0, 90.0]});