Hypersistence Utils: Spring and Hibernate utilities in one library

A rename that forced a decision

The library was called Hibernate Types until version 3, and the project description still carries the old name in parentheses. The README explains the change: the project name was changed from Hibernate Types to Hypersistence Utils because the scope of the project is much broader now, offering Spring utilities as well.

The consequence for anyone upgrading from the 2.x line is that a version bump was also a rename, and the migration is spelled out in three steps. First, change the Maven or Gradle dependency, using the installation guide. Second, change the package name from com.vladmihalcea.hibernate to io.hypersistence.utils.hibernate. Third, change the package name from com.vladmihalcea.spring to io.hypersistence.utils.spring. The README closes that section with a short phrase rather than a compatibility table, and the intent is clear: this is a cut, not a soft landing. There is no deprecation shim between the two package roots, so a build that mixes artifacts across the rename will fail on imports rather than on behaviour.

For a team holding an older Hibernate Types dependency, that is the first decision to make. Either spend the migration and land on the io.hypersistence coordinates now, or pin the old artifact deliberately and accept that it no longer receives the broader Spring-side work. The version matrix below makes that choice concrete.

Why there is one artifact per ORM line

The main advantage the project claims for itself is breadth: it supports a broad range of Hibernate versions, spanning from 7.4, 7.3, 7.2, 7.1 and 7.0 back through 6.6, 6.5, 6.4, 6.3, 6.2, 6.1 and 6.0 to 5.6, 5.5, 5.4, 5.3, 5.2, 5.1 and 5.0.

That range is delivered through separate artifacts rather than one jar with version conditionals. For Hibernate 7.4 and 7.3 the README points at hypersistence-utils-hibernate-73, for 7.2 and 7.1 at hypersistence-utils-hibernate-71, for 7.0 at hypersistence-utils-hibernate-70, for 6.6 down to 6.3 at hypersistence-utils-hibernate-63, and then a tail of older lines with 62, 60, 55, 52 and an artifact named hypersistence-utils-hibernate-5 for 5.1 and 5.0.

The Maven coordinates for the current line look like this:

    <dependency>
        <groupId>io.hypersistence</groupId>
        <artifactId>hypersistence-utils-hibernate-73</artifactId>
        <version>3.16.0</version>
    </dependency>

The same version number, 3.16.0, appears on the 7.3, 7.1, 7.0 and 6.3 artifacts, which confirms the split is about the Hibernate API surface rather than about release cadence. Older lines carry their own last versions: 3.9.4 for the 6.2 and 6.0 artifacts, 3.9.5 for 5.6 and 5.5, 3.7.6 for 5.4 through 5.2, and 3.7.0 for 5.1 and 5.0.

Now the part that matters for anyone browsing the repository. The top level tree lists only three module directories, hypersistence-utils-hibernate-63, hypersistence-utils-hibernate-71 and hypersistence-utils-hibernate-73, alongside pom.xml, mvnw, mvnw.cmd, changelog.txt, a docker directory and a set of Windows batch scripts for building and releasing. Meanwhile the README marks several artifacts as commercial support only, including the 7.0, 6.2, 6.1 and 6.0, 5.6 and 5.5, 5.4 through 5.2 and 5.1 and 5.0 lines. The consistent reading is that the open repository carries the community modules and the remaining artifacts are maintained elsewhere, which is also why a branch can contain only three module directories and still document nine. If you are on one of the commercial-only lines, the artifact in the installation guide is a coordinate reference, not something you will build from this tree.

Optional dependencies as a security decision

The installation guide has a section on optional Maven dependencies that is worth reading even if you never touch the feature list. The project defines a list of optional dependencies that you have to declare explicitly in your project in order to use them, and the stated reason is that not all projects may need them.

The second reason is more interesting. The README says the dependency version is extremely important because, from time to time, security issues may be discovered that get fixed in newer versions, and then puts the conclusion bluntly: relying on this library to supply you with the dependency versions is a very dangerous thing to do. The example given is Jackson Data Bind, where the README notes there have been 65 security issues discovered in a library the project heavily relies on. The guidance that follows is to take responsibility for constantly upgrading all the dependencies used alongside the library.

The affected dependencies are named. Guava, if you are mapping a Range. Jackson, for JSON types, split by ORM line. Moneta from the Java Money and Currency API, if you are mapping a MonetaryAmount. And the PostgreSQL JDBC driver, if you are mapping a PostgreSQL specific column type such as inet, hstore, array or interval:

    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>${postgresql.version}</version>
    </dependency>

That pattern has a practical consequence for dependency scanning in a corporate build. Nothing transitive arrives through this library that you did not ask for, so a vulnerability report naming Hypersistence Utils tends to point at your own choice of version rather than at a version the library forced on you. The cost is that a new contributor has to read the guide and wire up four or five dependencies before any feature works, which is exactly the trade the README is making in the open.

Where the features start, and what they target

The README organizes its capabilities as a Features section, and the first entry is JSON. The Generic JSON Type is described as allowing you to map JSON column types no matter if you are using Oracle, SQL Server, PostgreSQL or MySQL. For Hibernate 7 and 6, you can map any JSON column to a Map, a List, a POJO, a String or a JsonNode entity property, with the example that follows showing the mapping applied through the @Type annotation.

The mention of four vendors in one sentence is the design goal stated plainly. JSON support is the classic case where each database has its own column type and its own driver behaviour, so a mapping that works identically across four of them removes a recurring source of per-project code. Naming the target side is equally deliberate, since Map, List, POJO, String and JsonNode covers everything from an untyped column to a fully typed domain object, and the project topics back that up: array, custom-types, enum, hibernate, hibernate-types, hypersistence, java, json, performance, performance-testing, spring, spring-boot and spring-data-jpa.

The performance and performance-testing topics are the other tell about where the maintainer puts the effort, and the changelog.txt file in the tree suggests the library is measured as much as it is extended. The description on the repository states that the library gives you Spring and Hibernate utilities that can help you get the most out of your data access layer, while the tree at the root shows only Hibernate side module directories. Both are true at their own level: the Spring utilities belong to the broader 3.x scope that motivated the rename, and what sits in this repository root is the Hibernate module build. If Spring-side utilities matter to your evaluation, expect to find them in the wider io.hypersistence.utils.spring package rather than in a module directory at the top of this tree.

The build tooling tells you about the project

The repository layout is a small window into how the library is developed. A Maven wrapper sits at the root in both shell and Windows form, as mvnw and mvnw.cmd, next to the parent pom.xml and a .mvn directory, which is the conventional way to pin a Maven version so every contributor builds with the same one.

Alongside that are several batch scripts that describe the release routine without any prose: release-prepare.bat and release-perform.bat for cutting a version, test.bat and test-hibernate-module.bat for running the suite against one module, fork-jvm-test.bat for testing under a forked JVM, and build-without-tests.bat for a fast compile. A docker directory at the root suggests containerised runs against real database instances, which is the normal requirement for a library whose features are defined by database specific column types.

There is also a .github directory and a changelog.txt. Worth noting alongside that is the absence of any published tag on the project, so the artifact versions quoted in the installation guide, up to 3.16.0 for the current Hibernate lines, are the version reference to work from rather than a tag you can browse.

GitHub reports 2,670 stars, 402 forks and 43 open issues, with the most recent push on 2026-09-20, licence Apache-2.0, primary language Java, and master as the default branch. An open issue count in the low tens against that level of adoption is a good sign for a library whose users are mostly on a fixed set of ORM versions: the questions that arrive tend to be integration edge cases rather than basic usage.

How to evaluate it on your own stack

A sensible evaluation order follows from the structure. Start by identifying your Hibernate line, because that single fact selects the artifact and decides whether you are in the community set or the commercial support only set named in the guide.

Next, list the column types your schema actually uses. The JSON type is the entry point the README leads with, and the optional dependency table tells you what you will need to declare for it, Jackson by ORM line being the one that matters most. If your model uses Guava Range, Money or PostgreSQL specific types, budget for those coordinates too.

Then decide how much of your entity layer you are willing to move onto custom types. The library's premise is that mapping through a custom type is better than hand-rolling a UserType per project, which is a reasonable default for JSON columns and a heavier decision for a schema you have already tuned by hand.

Finally, take the upgrade question seriously rather than treating it as settled. If you are on Hibernate Types 2.x, the rename means three edits and a coordinated release, and the absence of a package bridge means you cannot do it one module at a time without leaving the build broken in between. Version 3.16.0 on the artifacts for the current Hibernate lines is recent enough that waiting for the next release before migrating is a defensible timing choice.

Editorial conclusion

Hypersistence Utils is a good example of a library whose real product is its support matrix. The interesting engineering is the versioned artifact split, one module per ORM line, which lets an application on Hibernate 6.3 and one on 7.3 depend on the same library name without fighting over transitive versions. Two design choices are worth carrying to your own code. First, the renaming from Hibernate Types to Hypersistence Utils came with a package move rather than a compatibility shim, so migration is a deliberate three step edit. Second, the decision to leave Guava, Jackson and the PostgreSQL driver as optional dependencies is a security argument, not a packaging preference, and the README is unusually direct about why. The practical takeaway for an evaluator: pick the artifact that matches your ORM line, declare the optional dependencies you actually use, and treat the version of everything else as your own responsibility. With no tagged releases visible on the repository, the artifact coordinates in the installation guide are the authoritative version reference.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. vladmihalcea/hypersistence-utils on GitHub