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 de dialeto do GoogleSQL ao Hibernate. O Spanner é compatível com o Hibernate ORM 6.x e 7.x. O Hibernate ORM tem um dialeto do Spanner integrado, e também há um dialeto do Hibernate mantido pelo Google disponível no GitHub. Ambos os dialetos 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, porque ele não exige a adição da dependência externa google-cloud-spanner-hibernate-dialect. O dialeto integrado oferece suporte aos recursos padrão do Hibernate. Se o aplicativo exigir recursos avançados específicos do Spanner, recomendamos usar o dialeto externo mantido pelo Google.

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:


  
  
    org.hibernate.orm
    hibernate-core
    7.4.0.Final
  

  
  
    com.google.cloud
    google-cloud-spanner-jdbc
    2.40.0

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 de credenciais JSON 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 mantido pelo Google

Para projetos que usam versões anteriores do Hibernate (6.x ou 7.x anteriores a 7.4) ou se você precisar de recursos avançados específicos do Spanner que ainda não são compatíveis com o dialeto integrado , use o dialeto do Spanner mantido pelo Google.

Os recursos avançados com suporte do dialeto mantido pelo Google incluem:

  • Hierarquias de tabelas intercaladas (@Interleaved)
  • Dicas de consulta, índice e verificação
  • Loteamento de esquema DDL
  • Marcação de transação (@TransactionTag)
  • Sequências agrupadas (@PooledBitReversedSequenceGenerator)

Para usar o dialeto mantido pelo Google, adicione as dependências do Maven ao arquivo pom.xml do projeto:


  
  
    com.google.cloud
    google-cloud-spanner-jdbc
  

  
  
    org.hibernate.orm
    hibernate-core
    6.4.4.Final

Configure o arquivo hibernate.properties do projeto para usar o dialeto do Spanner e o driver JDBC mantidos pelo Google:

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