Migrate a database

You can use the neo4j-admin database migrate command to migrate a Neo4j database from one store format to another or to a later MAJOR version of the same format.

A store format defines how the data of a database is stored on the file system.

The store format of a database is versioned with the MAJOR.MINOR scheme, independent of the Neo4j calendar versioning. An upgrade to the latest MINOR format version is an automatic operation performed on database startup. A migration to a higher MAJOR format version or another format is a manual action performed with the migrate command.

The store format for new databases can be set with the db.format configuration setting.

Syntax

The neo4j-admin database migrate has the following syntax:

neo4j-admin database migrate [-h] [--expand-commands]
                             [--force-btree-indexes-to-range]
                             [--verbose]
                             [--additional-config=<file>] [--pagecache=<size>]
                             [--to-format=standard|high_limit|aligned|block] <database>

The neo4j-admin database migrate command is run only on a stopped database.

Parameters

Table 1. neo4j-admin database migrate parameters
Parameter Description

<database>

Name of the database to migrate. Can contain * and ? for globbing. Note that * and ? have special meaning in some shells and might need to be escaped or used with quotes.

Options

The neo4j-admin database migrate command has the following options:

Table 2. neo4j-admin database migrate options
Option Description

--additional-config=<file>[1]

Configuration file with additional configuration.

--expand-commands

Allow command expansion in config value evaluation.

--force-btree-indexes-to-range

Special option for automatically turning all BTREE indexes/constraints into RANGE. Be aware that RANGE indexes are not always the optimal replacement of BTREEs and performance may be affected while the new indexes are populated. See the Neo4j v5 migration guide online for more information. The newly created indexes will be populated in the background on the first database start up following the migration and users should monitor the successful completion of that process.

This option is only relevant when migrating from Neo4j 4.4.

-h, --help

Show this help message and exit.

--pagecache=<size>

The size of the page cache to use for the migration process. The general rule is that values up to the size of the database proportionally increase performance.

--to-format=standard|high_limit|aligned|block

Name of the format to migrate the store to. If the format is specified, the target database is migrated to the latest known combination of MAJOR and MINOR versions of the specified format. If not specified, the tool migrates the target database to the latest known combination of MAJOR and MINOR versions of the current format.

--verbose

Enable verbose output.

1. See Tools → Configuration for details.

The block format is the default format for all databases in Enterprise Edition as long as they do not have the db.format setting specified. For more information on the block format, see Store formats.

Example

The following example migrates the movies database to the latest known combination of MAJOR and MINOR versions of the block format:

bin/neo4j-admin database migrate --to-format=block movies
Example output
2025-01-22 18:03:21.842+0000 INFO  [c.n.c.d.EnterpriseMigrateStoreCommand] Starting migration for database 'movies'
2025-01-22 18:03:22.504+0000 INFO  [o.n.k.i.s.StoreMigrator] 'record-aligned-1.1' has been identified as the current version of the store
2025-01-22 18:03:22.504+0000 INFO  [o.n.k.i.s.StoreMigrator] 'block-block-1.1' has been identified as the target version of the store migration
2025-01-22 18:03:22.506+0000 INFO  [o.n.k.i.s.StoreMigrator] Starting migration of database
2025-01-22 18:03:22.586+0000 INFO  [o.n.k.i.s.StoreMigrator] Migrating Store files (1/1):
2025-01-22 18:03:22.588+0000 INFO  [o.n.k.i.s.StoreMigrator] Store files
2025-01-22 18:03:23.270+0000 INFO  [c.n.i.b.i.BlockBatchImporter] Import completed successfully, took 654ms.
2025-01-22 18:03:23.708+0000 INFO  [o.n.k.i.s.StoreMigrator]  10% completed
2025-01-22 18:03:23.708+0000 INFO  [o.n.k.i.s.StoreMigrator]  20% completed
2025-01-22 18:03:23.708+0000 INFO  [o.n.k.i.s.StoreMigrator]  30% completed
2025-01-22 18:03:23.708+0000 INFO  [o.n.k.i.s.StoreMigrator]  40% completed
2025-01-22 18:03:23.709+0000 INFO  [o.n.k.i.s.StoreMigrator]  50% completed
2025-01-22 18:03:23.709+0000 INFO  [o.n.k.i.s.StoreMigrator]  60% completed
2025-01-22 18:03:23.709+0000 INFO  [o.n.k.i.s.StoreMigrator]  70% completed
2025-01-22 18:03:23.709+0000 INFO  [o.n.k.i.s.StoreMigrator]  80% completed
2025-01-22 18:03:23.709+0000 INFO  [o.n.k.i.s.StoreMigrator]  90% completed
2025-01-22 18:03:23.709+0000 INFO  [o.n.k.i.s.StoreMigrator] 100% completed
2025-01-22 18:03:23.761+0000 INFO  [o.n.k.i.s.StoreMigrator] Starting transaction logs migration.
2025-01-22 18:03:23.800+0000 INFO  [o.n.k.i.s.StoreMigrator] Transaction logs migration completed.
2025-01-22 18:03:23.802+0000 INFO  [o.n.k.i.s.StoreMigrator] Successfully finished migration of database, took 1s 296ms
2025-01-22 18:03:23.804+0000 INFO  [c.n.c.d.EnterpriseMigrateStoreCommand] Database migration completed successfully