Using NuoDB with Hibernate

Overview

NuoDB provides explicit support for Java applications using Hibernate object-relational mapping:

  • A NuoDB specific dialect for mapping to NuoDB specific SQL.

  • Custom Driver and Connection classes, specifically designed for Hibernate.

    • Allow NuoDB to throw appropriate Hibernate exceptions related to connection errors.

  • Packaged in nuodb-hibernate-XXX.jar.

However we recommend that your applications use JPA (the Jakarta Persistence API, formerly Java Persistence API) rather than Hibernate directly.

Our Hibernate 5 drivers released before Jan 2021 had a direct dependency on Hibernate in order to throw the appropriate Hibernate exceptions.

  • If you try to use the driver without Hibernate JARs on the CLASSPATH, you will get a ClassNotFoundException due to the missing StateStateException class.

  • This most commonly occurs on start up when using NuoDB as a JNDI resource in Web or JEE/Jakarta containers.

From V20.0.2-hib5 the JAR has an indirect dependency, avoiding start up errors.

This documentation is not meant to be a full Reference or Programming manual for Hibernate. It helps you get started with Hibernate and NuoDB.

Requirements

NuoDB supports both Hibernate 5 and Hibernate 6 but, because JPA 3 is a breaking change, requires different JARs to do so — see versions below.

Hibernate 5 JAR

Requires Java 11 or 17, NuoDB 4.2 or later, and is compatible with JPA 2, JEE 7 or 8, Spring 5 and Spring Boot 2.

Hibernate 6 JAR

Requires Java 11 or 17, NuoDB 5.0.2 or later, and is compatible with JPA 3, JEE 9+, Spring 6 and Spring Boot 3.

To use Spring with Hibernate 6 you need Spring 6 and/or Spring Boot 3 which, in turn, require Java 17.

For more on Java requirements, see System Requirements.

  • Hibernate 6 is supported in NuoDB 5.0.2 and later.

  • Both drivers require Java 8 or 11.

Installation and Versions

The Hibernate and JDBC JARs are published via Sonatype to Maven Central so that you can declare a dependency in your Gradle, Ivy or Maven build files. For the Maven URL required to download JAR files, see NuoDB Drivers Available at Other Public Sites.

  • NuoDB Hibernate JAR 20.0.2-hib5 supports Hibernate 5.3 and JPA 2.1

  • NuoDB Hibernate JAR 21.0.0-hib5 supports Hibernate from 5.3 or 5.4 and JPA 2.1.

  • NuoDB Hibernate JAR 22.0.0-hib5 and later supports Hibernate from 5.3 to 5.6. Hibernate supports JPA 2.2 from V5.5.

  • None of the above NuoDB Hibernate JARs work with Hibernate 6.x due to all the JPA 3 package changes.

  • NuoDB Hibernate JAR 23.0.0-hib6 and later supports Hibernate 6 and JPA 3.

  • NuoDB Hibernate Driver JARs have a version number and release schedule independent of NuoDB releases, starting with version 20.0.0-hib5.

  • To manually download a local copy of the JAR, go to the Maven Repository, click on the specific version of Hibernate you need and look for Files - there should be a link to download the JAR.

  • If copying JARs directly from Maven is not permitted by your organization, our JARs are also available in the Client Tools package. Customers can download it from our support portal https://support.nuodb.com.

Hibernate Dependencies

<!-- Maven POM -->
<dependency>
  <groupId>com.nuodb.hibernate</groupId>
  <artifactId>nuodb-hibernate</artifactId>
  <version>xxx-hib5</version>
</dependency>
<dependency>
  <groupId>com.nuodb.jdbc</groupId>
  <artifactId>nuodb-jdbc</artifactId>
  <version>yyy</version>
</dependency>
<!-- Gradle Build -->
compile group: 'com.nuodb.hibernate', name: 'nuodb-hibernate', version: 'xxx-hib5'
compile group: 'com.nuodb.jdbc', name: 'nuodb-jdbc', version: 'yyy'
<!-- Ivy XML -->
<dependency org="com.nuodb.hibernate" name="nuodb-hibernate" rev="xxx-hib5"/>
<dependency org="com.nuodb.jdbc" name="nuodb-jdbc" rev="yyy"/>

where:

  • xxx-hib5 is the NuoDB Hibernate 5 JAR version and yyy is the NuoDB JDBC JAR version.

  • For the Hibernate 6 JAR, replace -hib5 with -hib6.

  • The version numbers xxx-hib5 and xxx-hib6 are subject to change.

Note on Vulnerabilities

If you look on Maven Central it highlights a number of supposed vulnerabilities from dependencies. These are all related to H2 database which is only used as part of the unit tests for the driver.

There are no known vulnerabilities in the JAR itself.

Release Notes

Highlights of each release:

V20.0.0-hib5

  • Renumbered to allow Hibernate JAR to be released independently of the NuoDB database.

  • Last update for this version 20.0.2-hib5.

V21.0.0-hib5

  • Supports Hibernate V5.4.

  • Enables mapping of String data-members to NuoDB’s STRING column type.

  • Removes direct dependency on Hibernate to avoid start up issues in Web/Application Server.

V22.0.0-hib5

  • Supports Hibernate V5.6.

  • Adds support for NuoDB database query hints and FOR UPDATE SKIP LOCKED and FOR UPDATE NOWAIT.

  • Adds isValidJson() and jsonUnquote(), listagg() and rownum() functions.

  • Adds era(), quarter(), dayofweek(), dayofyear(), weekofmonth(), weekofyear() functions.

V22.0.1-hib5

  • Fixes for UPDATE SKIP LOCKED and a few function definitions.

  • Adds uuid() function.

  • Refactored, commented and tidied NuoDBDialect class.

V23.0.0-hib6

  • Supports JPA 3 and Hibernate 3.1

  • Hibernate 6 requires Java 11, but Spring 6 and Spring Boot 3 require Java 17.