Integrar o Spanner com o Hibernate ORM (dialeto GoogleSQL)

O Hibernate é uma ferramenta de mapeamento relacional de objetos para a linguagem de programação Java. Ele fornece uma estrutura para mapear um modelo de domínio orientado a objetos para um banco de dados relacional.

É possível integrar bancos de dados do dialeto GoogleSQL ao Hibernate. O Spanner é compatível com o Hibernate ORM 6.x e 7.x. Tanto o dialeto integrado quanto o de código aberto produzem instruções SQL, DML e DDL para os tipos de entidade e relacionamentos mais comuns usando anotações padrão do Hibernate e do Java Persistence.

Usar a integração do Hibernate integrada (Hibernate ORM 7.4 ou mais recente)

A partir do Hibernate ORM 7.4, o Hibernate inclui um dialeto integrado para o Spanner (org.hibernate.dialect.SpannerDialect).

Recomendamos que novos projetos usem esse dialeto integrado, já que ele não exige a adição da dependência externa google-cloud-spanner-hibernate-dialect. O dialeto integrado não tem alguns recursos e otimizações disponíveis no dialeto Spanner de código aberto.

Para usar o dialeto integrado, adicione as dependências do Maven para o núcleo do Hibernate ORM e o driver JDBC do Spanner ao arquivo pom.xml do projeto. Para encontrar as versões mais recentes dessas dependências, consulte as versões do Hibernate ORM e as versões do driver JDBC do Spanner:

<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 o arquivo hibernate.properties do projeto (normalmente localizado no diretório src/main/resources) para usar o dialeto do Spanner integrado:

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

Para autenticar com o Spanner, o driver JDBC exige credenciais. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON de credenciais da conta de serviço. Caso contrário, o driver usará as credenciais padrão definidas no aplicativo gcloud da Google Cloud CLI.

Usar o dialeto do Spanner de código aberto

Para projetos que usam versões anteriores do Hibernate (6.x ou 7.x antes da 7.4) ou se você precisar de recursos e otimizações que ainda não são compatíveis com o dialeto integrado, use o dialeto do Spanner de código aberto.

Para usar o dialeto de código aberto, adicione as dependências do Maven ao arquivo pom.xml do projeto:

<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 o arquivo hibernate.properties do projeto para usar o Dialeto do Spanner de código aberto e o driver JDBC:

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

Para mais informações sobre os recursos e as recomendações do Hibernate ao usar esse dialeto, consulte a documentação de referência no GitHub.

A seguir