GridGain Developers Hub

Migrating to GridGain from Apache Ignite

Apache Ignite 2.x and GridGain 8.x share most modules and features. Therefore, migration from Apache Ignite to GridGain is relatively straightforward. The migration process includes the following steps:

Remove or Replace Incompatible Features

A number of Apache Ignite 2.x features are incompatible with GridGain 8.x. To make your Apache Ignite clusters work in GridGain, you need to either remove these features or replace them with GridGain equivalents.

Cluster Snapshots

GridGain snapshot implementation is different from the one in Apache Ignite. Replace your Apache Ignite implementation with the GridGain snapshots.

Calcite-based SQL Engine

GridGain’s SQL engine is H2-based, which is incompatible with Apache ignite’s Calcite-based engine. To ensure compatibility:

  1. Remove all usage instances of the ignite-calcite module.

  2. Remove all references to CalciteQueryEngineConfiguration from SqlConfiguration.

  3. Remove QUERY_ENGINE('calcite') hints from SQL queries.

Change Data Capture

GridGain does not support CDC (Change Data Capture).

Replace CDC with GridGain Data Center Replication or GridGain Kafka connector replication.


GridGain does not support the read-repair mode.

Remove all read-repair usage.

Index Query

GridGain has a different internal implementation of index queries from Apache Ignite. Public API for index queries is the same in both Apache Ignite and GridGain. When migrating, keep the following in mind:

  • Unlike Apache Ignite, null cannot be used for setting search boundaries for range criteria (lt(), lte(), gt(), gte(), between()), and the result of executing these criteria will not contain null values for the specified column.

  • If criteria do not match the index, the query will still be executed. This execution is not guaranteed to be as efficient.

Make sure your code can handle unsorted query results and that your criteria fields match table indexes when migrating.

Custom Types in REST API

GridGain does not support custom types in the REST API. You can implement these with the use of ConnectorMessageInterceptor.

Apache Ignite Sandbox

GridGain does not support Apache Ignite Sandbox. However, GridGain Enterprise Security provides the equivalent degree of security.

Remove the Sandbox usage.

Create Snapshots of Persistent Clusters

You need to create a snapshot or your persistent cluster(s) to have a backup if something goes wrong during migration.

Proceed as follows:

Sample configuration file:

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns=""

    <bean class="org.apache.ignite.configuration.IgniteConfiguration">
        <property name="igniteInstanceName" value="srv01"/>

        <property name="workDirectory" value="migrationtest/work"/>

        <property name="discoverySpi">
            <bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi">
                <property name="ipFinder">
                    <bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder">
                        <property name="addresses">

        <property name="dataStorageConfiguration">
            <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
                <property name="defaultDataRegionConfiguration">
                    <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
                        <property name="persistenceEnabled" value="true"/>

Stop Nodes in Apache Ignite

Install GridGain

  1. Download GridGain 8.x to your machine.

  2. Install the downloaded GridGain version in a dedicated directory.

  3. Copy workdir from the Apache Ignite directory to the GridGain directory.

Change Dependencies and Configurations

Thick Clients

Change dependencies fromm Apache Ignite to GridGain in the thick clients.


Excerpt from the sample pom.xml with GridGain 8.8.24 dependencies for a Maven implementation:


        <id>GridGain External Repository</id>



In the .NET client, replace the Apache.Ignite dependency with GridGain.Ignite:

dotnet remove package Apache.Ignite
dotnet add package GridGain.Ignite  --version {gridgain.version}


For the C++ platform, build the client from sources.

Thin Clients

Change dependencies fromm Apache Ignite to GridGain in the thin clients.


Excerpt from the sample pom.xml with GridGain 8.8.24 dependencies for a Maven implementation:




For the .NET thin client, use the Apache.Ignite.Core assembly located in the {GRIDGAIN_HOME}/platforms/dotnet directory of the GridGain distribution package instead of Apache.Ignite.Core from the Apache Ignite distribution.


The source code of the C++ thin client is included in the GridGain distribution package under the {GRIDGAIN_HOME}/platforms/cpp directory. Replace the Apache Ignite client with the GridGain one.


For the Python thin client, replace the pyignite package with pygridgain:

pip3 install pygridgain


To use the Node.js client, replace the apache-ignite-client package with gridgain/thin-client.


To use the PHP client, replace the apache/apache-ignite-client package with gridgain/gridgain-client, starting with:

composer require gridgain/gridgain-client


Make sure the ODBC and JDBC drivers are compatible with your GridGain implementation.


Build the GridGain ODBC driver and use it in your application instead of the Apache Ignite ODBC driver.


The JDBC thin driver is a default, lightweight driver provided by GridGain.

Replace the ignite-core-2.14.0.jar package` with ignite-core-8.8.24.jar in your application classpath.

Register the JDBC driver:


Open the the JDBC connection:

Connection conn = DriverManager.getConnection("jdbc:ignite:thin://");

XML Configuration File

Modify the XML configuration file you had used to start nodes in Apache Ignite.

In particular, add or change SQL memory quotas. Unlike Apache Ignite, GridGain uses an SQL memory quota mechanism to prevent nodes from running out of memory when executing SQL queries that return large result sets. The total amount of memory used by multiple concurrent queries cannot exceed the global quota value. By default, the global quota for SQL queries is set to 60% of the heap memory available to the node. Verify that the default global quota value is sufficient for you queries; increase the value in case it isn’t sufficient.


<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="sqlConfiguration">
        <bean class="org.apache.ignite.configuration.SqlConfiguration">
            <property name="sqlGlobalMemoryQuota" value="300M"/>

Start Nodes in GridGain

  1. Navigate to your GridGain directory.

  2. Start your cluster nodes in GridGain with the updated XML configuration file.

Test Performance

Although GridGain is expected to be at least as performant as Apache Ignite, we recommend that you verify performance of your cluster(s) in GridGain 8.x upon migration from Apache Ignite 2.x.