Introduction

The aim of this guide is to assist you migrating an existing application using any version 8.2.x of Hibernate Search to the latest of the 8.4.x series.

If you think something is missing or something does not work, please contact us.

If you’re looking to migrate from an earlier version, you should migrate step-by-step, from one minor version to the next, following the migration guide of each version.

To Hibernate Search 5 users

Be aware that a lot of APIs have changed since Hibernate Search 5, some only because of a package change, others because of more fundamental changes (like moving away from using Lucene types in Hibernate Search APIs).

When migrating from Hibernate Search 5, you are encouraged to migrate first to Hibernate Search 6.0 using the 6.0 migration guide, and only then to later versions (which will be significantly easier).

Requirements

Hibernate ORM

Hibernate Search 8.4.0.Final ORM mapper now targets Hibernate ORM 7.4.

You will need to upgrade Hibernate ORM to 7.4.x when upgrading to Hibernate Search 8.4.0.Final. Or you can use one of the Hibernate Search platform BOMs to keep dependency versions aligned automatically:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.hibernate.search</groupId>
            <artifactId>hibernate-search-platform-bom</artifactId>
            <version>8.4.0.Final</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

See Hibernate Search Platform for more details.

Artifacts

The coordinates of Maven artifacts in Hibernate Search 8.4.0.Final are the same as in Hibernate Search 8.2.

Data format and schema

Indexes

The index format and schema in Hibernate Search 8.4.0.Final is backward-compatible with Hibernate Search 8.2: older indexes can be read from and written to without reindexing.

Outbox polling database tables

The event and agent database tables used for outbox-polling in Hibernate Search 8.4.0.Final are backward-compatible with Hibernate Search 8.2: no database schema update is necessary for these tables.

Configuration

The configuration properties in Hibernate Search 8.4.0.Final, in general, are backward-compatible with Hibernate Search 8.2.

API

The API in Hibernate Search 8.4.0.Final is, in general, backward-compatible with Hibernate Search 8.2.

SPI

The SPI in Hibernate Search 8.4.0.Final is, in general, backward-compatible with Hibernate Search 8.2.

Behavior

The behavior of Hibernate Search 8.4.0.Final is, in general, backward-compatible with Hibernate Search 8.2.

StatelessSession usage with indexed entities now throws an explicit exception

Hibernate Search now explicitly detects when listener-triggered indexing is used with a StatelessSession and throws an exception.

Previously, this scenario could lead to confusing errors or silently incorrect behavior.

If you need to use a StatelessSession to persist or update indexed entities, see the workarounds documented in the reference guide.