Edit

Persistent Data Migration

Ignite 3 persistent data storage is not directly compatible with Ignite 2. You need to convert your Ignite 2 caches to Ignite 3 tables. The migration tool can be used to convert most Ignite 2 caches

There are two options for creating the required Ignite 3 configuration:

Replicating Caches to Ignite 3
Migrating Persistent Data

Regardless of the approach you choose, you need to download the migration tools first:

Download the migration tools.
Unpack the downloaded archive to your machine.
To explore the available commands in help, run the following command from the migration tools directory:
```
bin/migration-tools --help
```
or
```
bin/migration-tools {command} --help
```
Substitute {command} with the actual command name.

Replicating Caches to Ignite 3

The migration tool can analyze Ignite 2 configuration and create DDL requests required to reproduce the caches.

Export DDL Script

To create the DDL script, use the following command:

bin/migration-tools sql-ddl-generator [-o={file}] [--allow-extra-fields] [--stop-on-error] [--extra-lib={jar}] ignite-config.xml

Where:

-o - saves the script to a file (e.g., -o=ai3-script.sql). By default, the script is printed to the console.
--allow-extra-fields - if specified, any columns or fields of unsupported types will be saved to an EXTRA column as JSON data.
--stop-on-error - if specified, the command stops when it encounters an error when attempting to produce the DDL for a cache. By default,, the command logs errors and continues.
--extra-lib - if specified, adds the classes from the provided JAR file to CLI tool classpath. These classes, which that may be referenced in any cache configuration, can be used to ensure optimal results and avoid errors and warning messages. Use this parameter for each JAR you want to add. You can specify this parameter multiple times to provide multiple JARs.

Create Ignite 3 Tables

Then, execute the script from the Ignite 3 CLI tool:

sql --file=ai3-script.sql

When executed, the script will create all required schemas and tables with the same configuration specified in Ignite 2.

Migrating Persistent Data

An alternative to configuring the tables and migrating data from Ignite 2 via SQL script is to migrate data directly from the persistent storage files. When done this way, all data stored on the node will be converted to Ignite 3 tables and will be accessible once the cluster is started. As this approach converts stored data directly, schemas will be preserved from Ignite 2.

This approach requires downtime, but does not involve using data center replication.

To convert your persistent storage to Ignite 3:

Safely stop the Ignite 2 node you intend to migrate data from.

Note
Let the node complete a checkpoint after stopping the clients to make sure that all the data is properly saved in persistent storage.
Start the Ignite 3 cluster.
Run the command to list available caches on the node:
```
bin/migration-tools persistent-data work-dir consistent-id config-file list-caches [--mode] [--rate-limiter] [--client.basicAuthenticator.username]
```
Where:
- work-dir - the Ignite 2 node’s work directory. By default, it is the {IGNITE_HOME}/work folder.
- consistent-id - the Ignite 2 node’s unique node identifier.
- config-file - Ignite 2 configuration file. This file will be used to determine table parameters in Ignite 3.
- cacheName - the name of the specific cache to migrate.
- ai3urls - the list of URLs that the migration tool will use to connect to the Ignite 3 cluster.
- --mode - the migration mode, which defines what to do in case of an irreconcilable mismatch between the object stored in the cache and the Ignite 3 table:
  - ABORT (default) - abort the migration.
  - IGNORE_COLUMN - ignore (not migrate to the table) those columns/fields in the cache record that are defined in Ignite 2 but not defined in Ignite 3.
  - SKIP_RECORD - ignore (not migrate to the table) the entire cache record.
  - PACK_EXTRA - serialize to JSON and store in the EXTRA column all additional columns/fields in the cache record. The tool adds this column to the table (it is not native to Ignite 3) and makes this column accessible to the Java client.
- --rate-limiter - limits the number of records migrated per second (allows to save resources). The default is "-1", which means "no limit".
- --client.basicAuthenticator.username - the name of the user to authenticate to Ignite 3 cluster with. User password must be specified in the IGNITE_CLIENT_SECRET environment variable.
Run the persistent data migration command in the migration tool:
```
bin/migration-tools persistent-data work-dir consistent-id config-file migrate-cache cacheName ai3urls [--mode] [--rate-limiter]  [--client.basicAuthenticator.username]
```
Where:
- work-dir - the Ignite 2 node’s work directory. By default, it is the {IGNITE_HOME}/work folder.
- consistent-id - the Ignite 2 node’s unique node identifier.
- config-file - Ignite 2 configuration file. This file will be used to determine table parameters in Ignite 3.
- cacheName - the name of the specific cache to migrate.
- ai3urls - the list of URLs that the migration tool will use to connect to the Ignite 3 cluster.
- --mode - the migration mode, which defines what to do in case of an irreconcilable mismatch between the object stored in the cache and the Ignite 3 table:
  - ABORT (default) - abort the migration.
  - IGNORE_COLUMN - ignore (not migrate to the table) those columns/fields in the cache record that are defined in Ignite 2 but not defined in Ignite 3.
  - SKIP_RECORD - ignore (not migrate to the table) the entire cache record.
  - PACK_EXTRA - serialize to JSON and store in the EXTRA column all additional columns/fields in the cache record. The tool adds this column to the table (it is not native to Ignite 3) and makes this column accessible to the Java client.
- --rate-limiter - limits the number of records migrated per second (allows to save resources). The default is "-1", which means "no limit".
- --client.basicAuthenticator.username - the name of the user to authenticate to Ignite 3 cluster with. User password must be specified in the IGNITE_CLIENT_SECRET environment variable.

The migration tool analyzes the specified cache and writes it to the Ignite 3 cluster.

Here is what your commands may look like:

bin/migration-tools persistent-data ./nodeWorkDir ad26bff6-5ff5-49f1-9a61-425a827953ed ./config-file.xml list-caches
bin/migration-tools persistent-data ./nodeWorkDir ad26bff6-5ff5-49f1-9a61-425a827953ed ./config-file.xml migrate-cache cacheName localhost:10800 --mode IGNORE_COLUMN --rate-limiter 1000

In this case, the migration tools will first display what caches are available, and then migrate the cacheName cache.

Migration tool will store logs in the USER_HOME/.ignite-migration-tools/logs folder. Alternatively, the logs folder can be configured by using the IGNITE_MIGRATION_TOOLS_LOGS_DIR environment variable.

© 2025 The Apache Software Foundation.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.