Chapter 1. Data Grid 8 upgrade notes

Read the following information to ensure a successful upgrade from Data Grid 8.5 to 8.6.

If you are upgrading from an earlier version of Data Grid 8, review the upgrade information for the intermediate releases before upgrading to 8.6. For example, see Upgrading to Data Grid 8.5, which covers the upgrade from Data Grid 8.4 to 8.5.

Marshalling changes

To support zero-downtime upgrades, the Data Grid internal marshaller has been rewritten to be based on ProtoStream. As a result, it is no longer possible to define AdvancedExternalizer instances as part of the global configuration or add @SerializeWith annotations to classes.

User key and value marshalling

Users of the jboss-marshalling library that depended on AdvancedExternalizer to marshal classes stored in caches should either:

All AdvancedExternalizer definitions declared for older schema versions are ignored.

Custom commands

All commands, both user-defined and internal, are now marshalled using ProtoStream. As a result, the following interfaces have been removed:

Custom commands must now be marshalled with ProtoStream and registered by providing a org.infinispan.protostream.SerializationContextInitializer in the global serialization configuration.

Legacy stores

The tools module now contains the Externalizer and AdvancedExternalizer interfaces that were removed from infinispan-commons, to assist with migrating legacy stores.

To use the StoreMigrator, update existing Externalizer implementations to reference the following package:

org.infinispan.tools.store.migrator.marshaller.common

Query changes

The following query modules have been refactored:

Transport changes

Providing custom org.infinispan.remoting.transport.Transport implementations through the GlobalConfiguration is no longer supported.

This capability was removed with no replacement because Data Grid is tightly coupled to the underlying JGroupsTransport implementation.

Expiration configuration validation

Caches will not start if the max-idle setting is greater than or equal to the lifespan expiration value.

This configuration previously resulted in max-idle having no effect because the lifespan expiration always removed entries first.

Metrics

The metrics format has changed.

The base_ prefix for JVM and system metrics has been removed. A jvm setting can be used to disable export of JVM and system metrics when these metrics are already exported by the host application, for example Spring Boot.

The prefix for Data Grid metrics has changed from vendor_ to infinispan_. The cache manager and cache name now appear as tags.

The previous settings names-as-tags and prefix are deprecated and have no effect on the new metrics format.

For example, metrics for cache manager Foo and cache Bar previously used the following format:

vendor_cache_manager_Foo_cache_Bar_statistics_approximate_entries
vendor_cache_manager_Foo_cache_Bar_statistics_hits

Metrics now appear as:

infinispan_statistics_approximate_entries{cache_manager="Foo",cache="Bar"}
infinispan_statistics_hits{cache_manager="Foo",cache="Bar"}

Removals

The metric for persisted entries has been removed. Use the metrics for approximate size and in-memory entries instead.

Virtual threads enabled by default (JDK 21+)

Virtual thread pools are now enabled by default. This change can improve application responsiveness and scalability under high concurrency.

On systems with very low CPU counts (two or fewer cores), virtual threads might in rare cases cause system freezes due to thread pinning.

If this occurs, you can disable virtual threads as follows:

Monitor application performance after upgrading, especially on systems with low CPU counts.

Non-segmented FileStore support

When the file store implementation changed in Data Grid 8.3, the ability to disable segmentation was removed. This capability has now been restored.

Disabling segmentation for the file store is recommended only for caches with a smaller data size.

Legacy Hot Rod client removal

The legacy Hot Rod client, org.infinispan:infinispan-hotrod-client-legacy has been removed.

If required, you can continue using versions from earlier releases that are still maintained.

Hibernate second level cache support

Support has been added for the following Hibernate versions:

Hibernate 6.2, 6.4, and 6.5 are no longer supported but might still work. Upgrading to version 6.6 is recommended.

Deprecation removals

All features that was deprecated in Data Grid 7.x and 8.0 has been removed.

Native server removal

The native server and the associated quay.io/infinispan/server-native images are no longer provided. Use the JVM-based server instead. The JVM-based server provides better performance than the native server without compromising features and is fully supported.

Default index startup mode

The default used to be NONE, which means that no actions at cache startup time are taken in case potential index data inconsistencies are detected from the cache configuration. With AUTO, for instance, a purge is automatically triggered if the cache is not persistent while the indexes are. For more information, see Index startup mode.

Server endpoint request size

All server endpoints (Hot Rod, RESP, Memcached, and REST) now enforce a default max-content-length of 10 MB per request. Requests larger than this limit are rejected unless the limit is explicitly increased in the server configuration.

Java Hot Rod client connection handler

A new Hot Rod client maintains a single connection per server and supports pipelining by batching concurrent requests into a single flush operation. This approach reduces system resource usage, including file descriptors and threads, and lowers CPU usage when submitting the same tasks.

The previous client that used a connection pool to handle concurrent requests has been moved to the hotrod-client-legacy module.

The new client is a drop-in replacement in most cases. The exception is when applications reference internal classes, such as ChannelFactory, which were part of a non-public API and have been removed.

Connection pool configuration is deprecated and no longer used.

Java Hot Rod client RemoteCache withFlags ThreadLocal removal

Previously, RemoteCache stored Flag settings in a ThreadLocal and cleared them after a cache invocation. This approach does not work with virtual threads and can lead to errors when the same RemoteCache instance is shared across threads.

The withFlags method now returns a new RemoteCache instance when new flags are applied, leaving the original instance unchanged. This behavior improves thread and virtual thread safety.

Upgrade from 8.1 at a minimum

If you are upgrading from 8.0, you must first upgrade to 8.1. Persistent data in Data Grid 8.0 is not binary compatible with later versions. To overcome this incompatibility issue, Data Grid 8.2 and later automatically converts existing persistent cache stores from Data Grid 8.1 at cluster startup. However, Data Grid does not convert cache stores from Data Grid 8.0.