Integrate Spanner with Hibernate ORM (GoogleSQL dialect)

Hibernate is an object-relational mapping tool for the Java programming language. It provides a framework for mapping an object-oriented domain model to a relational database.

You can integrate GoogleSQL-dialect databases with Hibernate. Spanner is compatible with Hibernate ORM 6.x and 7.x. Hibernate ORM has a built-in Spanner dialect, and there is also a Google-maintained Hibernate dialect available on GitHub. Both dialects produce SQL, DML, and DDL statements for most common entity types and relationships using standard Hibernate and Java Persistence annotations.

Use built-in Hibernate integration (Hibernate ORM 7.4+)

Starting with Hibernate ORM 7.4, Hibernate includes a built-in dialect for Spanner (org.hibernate.dialect.SpannerDialect).

We recommend that new projects use this built-in dialect, as it does not require adding the external google-cloud-spanner-hibernate-dialect dependency. The built-in dialect supports standard Hibernate features. If your application requires advanced Spanner-specific features, we recommend using the Google-maintained external dialect instead.

To use the built-in dialect, add the Maven dependencies for Hibernate ORM core and the Spanner JDBC driver to your project's pom.xml file. To find the latest versions of these dependencies, see the Hibernate ORM releases and the Spanner JDBC driver releases:

<dependencies>
  <!-- Hibernate ORM Core -->
  <dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.4.0.Final</version>
  </dependency>

  <!-- Cloud Spanner JDBC Driver -->
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-jdbc</artifactId>
    <version>2.40.0</version>
  </dependency>
</dependencies>

Configure your project's hibernate.properties file (typically located in the src/main/resources directory) to use the built-in Spanner Dialect:

hibernate.dialect=org.hibernate.dialect.SpannerDialect
hibernate.connection.driver_class=com.google.cloud.spanner.jdbc.JdbcDriver
hibernate.connection.url=jdbc:cloudspanner:/projects/YOUR-PROJECT/instances/YOUR-INSTANCE/databases/YOUR-DATABASE

To authenticate with Spanner, the JDBC driver requires credentials. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account JSON credentials file. Otherwise, the driver uses the default credentials set in the Google Cloud CLI gcloud application.

Use Google-maintained Spanner dialect

For projects using earlier versions of Hibernate (6.x or 7.x prior to 7.4), or if you need advanced Spanner-specific features that are not yet supported by the built-in dialect, you can use the Google-maintained Spanner Dialect.

Advanced features supported by the Google-maintained dialect include:

  • Interleaved table hierarchies (@Interleaved)
  • Query, index, and scan hints
  • DDL schema batching
  • Transaction tagging (@TransactionTag)
  • Pooled sequences (@PooledBitReversedSequenceGenerator)

To use the Google-maintained dialect, add the Maven dependencies to your project's pom.xml file:

<dependencies>
  <!-- The Spanner JDBC driver dependency -->
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-jdbc</artifactId>
  </dependency>

  <!-- Hibernate core dependency -->
  <dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.4.4.Final</version>
  </dependency>
</dependencies>

Configure your project's hibernate.properties file to use the Google-maintained Spanner Dialect and JDBC Driver:

hibernate.dialect=com.google.cloud.spanner.hibernate.SpannerDialect
hibernate.connection.driver_class=com.google.cloud.spanner.jdbc.JdbcDriver
hibernate.connection.url=jdbc:cloudspanner:/projects/YOUR-PROJECT/instances/YOUR-INSTANCE/databases/YOUR-DATABASE

For more information about the features and recommendations for Hibernate when using this dialect, consult the reference documentation on GitHub.

What's next