What to Know Before Migrating from Apache Ignite 2.x

This page is the starting point for planning a migration from Apache Ignite 2.18 to the latest GridGain 8 Ultimate release. Use it to identify the changes relevant to your deployment and estimate the work involved.

GridGain 8 forked from Apache Ignite around version 2.7. The two products remain largely compatible, so most APIs, configuration, on-disk formats, and application code carry over unchanged.

Most migration work falls into three areas: cluster cutover, configuration changes, and feature replacement. The sections below explain each area and help you determine which changes apply to your deployment.

On this page:

Before You Begin — the license, downtime, and backups to have in place first
Migration Constraints — hard rules that shape the cutover plan
Compatibility Summary — what works, what doesn’t, at a glance
Migration Scope and Effort — the ranked work list: who each change affects and how much effort it takes

Detailed topics:

Features to Replace — features that need a code change or a workaround
Configuration and Validation Changes — changed defaults, removed properties, binary field ordering
APIs, Clients, and Extensions — the SQL engine, per-language client changes, and custom plugins and SPIs
Artifacts and Deployment — distribution, build coordinates, Docker, modules
Monitoring and CLI Changes — logs, metrics, system views, events, and control.sh / ignite.sh

When you are ready to execute the migration, follow the step-by-step Migration Procedure.

Before You Begin

Have the following in place before you plan the migration:

A GridGain 8 license. GridGain 8 Ultimate Edition requires a license file. The enterprise features that migrations most often depend on, such as Data Center Replication, enterprise snapshots, and enterprise security, will not start without a valid one. Obtain the license and install it as described in Licensing.
Scheduled downtime. The cutover stops the whole cluster, converts it, and restarts it on GridGain. Ignite and GridGain nodes cannot run together, so there is no rolling upgrade (see Migration Constraints).
Backup storage. Reserve space for a full backup of the persistence directory, taken before the first GridGain start. It is your only rollback path once GridGain writes.
Distributions. The GridGain 8 distribution for your platform, plus your existing Apache Ignite distribution kept archived until the migration is confirmed stable.

The Migration Procedure expands these into a pre-cutover checklist.

Migration Constraints

Keep in mind these constraints before migrating your cluster:

One-way upgrade. Once GridGain writes to the persistence directory, Apache Ignite can no longer read it.
CDC must be off at the last write. GridGain can start on Ignite’s persistence only if Change Data Capture was disabled when the data was last written. Stop all CDC processes and disable CDC before the final checkpoint and shutdown.
Full cutover, no mixed topology. Ignite and GridGain server nodes cannot coexist in one cluster, and clients are not cross-compatible.
In-memory data is not carried over. Data in non-persistent regions does not survive the cutover. Plan to reload it from its original sources, as after any cluster restart. See Persistent and In-Memory Clusters.
Planned downtime is required. The whole cluster stops, converts, and restarts as GridGain; all clients are updated before reconnecting.
No in-place rollback after the first GridGain write. Rollback is possible only by restoring a pre-cutover backup.

These constraints mean that all server nodes and clients must be upgraded together. Take a full backup before the first GridGain start and keep the Ignite distribution archived until the migration is confirmed stable.

Compatibility Summary

This is the high-level picture of what works, what does not, and what needs attention.

Area Status What it means for you

Area	Status	What it means for you
Inter-node protocols (Discovery, Communication)	Incompatible	Ignite and GridGain server nodes cannot coexist in one cluster, so a full cutover is required.
Thick clients (join the topology)	Incompatible	Clients must be rebuilt against GridGain and updated before connecting.
Thin client, JDBC, ODBC protocols	Incompatible	Update all clients before connecting. They may appear to connect because the protocols share common roots, but fail on anything beyond basic operations.
Persistent data	Compatible, one-way	GridGain can start on Ignite’s Native Persistence if conditions are met (clean shutdown, CDC disabled, consistent binary field-sort setting). Once GridGain writes, Ignite can no longer read it.
In-memory data	Not carried over	Data in non-persistent regions does not survive the full-cluster cutover. Reload it the way you reload after any restart: `CacheStore` loading or your data-loading jobs.
Configuration	Mostly compatible	Some defaults differ, some properties don’t exist in GridGain, and GridGain validates more strictly.
APIs (Java, SQL, REST)	Mostly compatible	Core cache, compute, and service APIs are largely compatible. Differences exist in specific areas.
CLI (`ignite.sh`, `control.sh`)	Mostly compatible	Some commands are added, removed, or renamed.
Runtime behavior	Differs in places	Stricter validation, different error handling, and changed service-deployment timing, even where the same code compiles and runs.

Inter-node protocols (Discovery, Communication)

Incompatible

Ignite and GridGain server nodes cannot coexist in one cluster, so a full cutover is required.

Thick clients (join the topology)

Incompatible

Clients must be rebuilt against GridGain and updated before connecting.

Thin client, JDBC, ODBC protocols

Incompatible

Update all clients before connecting. They may appear to connect because the protocols share common roots, but fail on anything beyond basic operations.

Persistent data

Compatible, one-way

GridGain can start on Ignite’s Native Persistence if conditions are met (clean shutdown, CDC disabled, consistent binary field-sort setting). Once GridGain writes, Ignite can no longer read it.

In-memory data

Not carried over

Data in non-persistent regions does not survive the full-cluster cutover. Reload it the way you reload after any restart: CacheStore loading or your data-loading jobs.

Configuration

Mostly compatible

Some defaults differ, some properties don’t exist in GridGain, and GridGain validates more strictly.

APIs (Java, SQL, REST)

Mostly compatible

Core cache, compute, and service APIs are largely compatible. Differences exist in specific areas.

CLI (ignite.sh, control.sh)

Mostly compatible

Some commands are added, removed, or renamed.

Runtime behavior

Differs in places

Stricter validation, different error handling, and changed service-deployment timing, even where the same code compiles and runs.

Most APIs are compatible, so most application code compiles and runs unchanged once rebuilt against GridGain. The main exceptions are features that were removed or replaced. Check which of the following apply to your deployment:

Replaced by a GridGain enterprise equivalent with a different API. For example, CDC is replaced by Data Center Replication.
Experimental Ignite features that were dropped. Where a supported alternative exists, migrate to it. For example, the Calcite engine is replaced by H2.
Features with no direct equivalent. These require a workaround or redesign. For example, Cache Dump.

The Features to Replace topic describes each affected feature and the required migration path. Configuration related to removed features must also be removed; see Server Configuration Differences.

Migration Scope and Effort

Use the following tables to identify the work relevant to your environment and estimate the effort involved.

The tables group changes by responsibility: application developers and cluster operators. Within each group, items are roughly ordered from changes that affect every migration to changes that apply only to specific features.

Two columns help you evaluate each item:

Applies if — when the item is relevant. If it does not apply to your deployment, skip it.
Effort — the kind of work involved:
- Mechanical — a package rename, path change, or similar update with no logic changes.
- Config-only — set, remove, or restore a configuration property; no code changes.
- Code — a contained code change, such as a renamed API call or a small rework.
- Redesign — adopt a different system or API; expect design work, implementation, and re-testing.

Some items show a range, such as Mechanical to Code: the effort spans those two levels depending on which features your deployment uses.

For Application Developers

These changes affect application and client code.

What changes Applies if Effort Details

What changes	Applies if	Effort	Details
Build coordinates and dependencies	Always	Mechanical	Build Coordinates
Rebuild and update all clients	Always	Mechanical and Code	Clients
Calcite SQL engine → H2	You set `queryEngine=calcite`	Code + re-test queries	SQL Changes
CDC → Data Center Replication or Kafka Connect	You run Change Data Capture	Redesign	Features to Replace
Snapshots → GridGain snapshots	You script or automate Ignite snapshots	Redesign	Features to Replace
Security plugins → GridGain security	You use a custom `GridSecurityProcessor` or built-in authentication	Redesign	Features to Replace
Custom plugins and SPIs	You maintain custom SPI or plugin implementations	Code and Redesign	Plugins and Custom SPIs
Other feature replacements (Read Repair, service interceptors, Metrics API, transaction-aware queries, Cache Dump, multi-disk storage, Performance Statistics, thin-client callbacks)	You use the specific feature	Code	Features to Replace

Build coordinates and dependencies

Always

Mechanical

Build Coordinates

Rebuild and update all clients

Always

Mechanical and Code

Clients

Calcite SQL engine → H2

You set queryEngine=calcite

Code + re-test queries

SQL Changes

CDC → Data Center Replication or Kafka Connect

You run Change Data Capture

Redesign

Features to Replace

Snapshots → GridGain snapshots

You script or automate Ignite snapshots

Redesign

Features to Replace

Security plugins → GridGain security

You use a custom GridSecurityProcessor or built-in authentication

Redesign

Features to Replace

Custom plugins and SPIs

You maintain custom SPI or plugin implementations

Code and Redesign

Plugins and Custom SPIs

Other feature replacements (Read Repair, service interceptors, Metrics API, transaction-aware queries, Cache Dump, multi-disk storage, Performance Statistics, thin-client callbacks)

You use the specific feature

Code

Features to Replace

For Cluster Operators

These changes affect cluster configuration, deployment, and operational tooling.

What changes Applies if Effort Details

What changes	Applies if	Effort	Details
Changed configuration defaults	Always	Config-only	Changed Defaults
Removed configuration properties	You configured CDC, snapshots, Calcite, or multi-disk storage	Config-only	Removed Configuration Properties
Binary object field-sort property	You set `IGNITE_BINARY_SORT_OBJECT_FIELDS`	Config-only	Binary Object Field Ordering
CLI and script changes	You have operational scripts or automation	Code	CLI Changes
Monitoring (logs, metrics, system views, events)	You have monitoring or log-parsing tooling	Code	Monitoring
Docker / container setup	You run in containers	Mechanical	Docker

Changed configuration defaults

Always

Config-only

Changed Defaults

Removed configuration properties

You configured CDC, snapshots, Calcite, or multi-disk storage

Config-only

Removed Configuration Properties

Binary object field-sort property

You set IGNITE_BINARY_SORT_OBJECT_FIELDS

Config-only

Binary Object Field Ordering

CLI and script changes

You have operational scripts or automation

Code

CLI Changes

Monitoring (logs, metrics, system views, events)

You have monitoring or log-parsing tooling

Code

Monitoring

Docker / container setup

You run in containers

Mechanical

Docker

© 2026 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Jun 12, 2026