anchor.diff: +:toc:
  +:toclevels: 4
  +
   = Google Cloud Spanner Dialect for Hibernate ORM
   
   This is a dialect compatible with https://hibernate.org/orm/releases/5.4/[Hibernate 5.4] for the https://cloud.google.com/spanner/[Google Cloud Spanner] database service.
  
positive.code: 
  This results in sequential IDs that are https://cloud.google.com/spanner/docs/schema-and-data-model#primary_keys[not optimal for Cloud Spanner] and makes use of the `hibernate_sequence` table for generating IDs.
  
  === Limit Large DML Transactions
  
  Cloud Spanner has a mutation limit on each transaction - each Spanner transaction https://cloud.google.com/spanner/quotas#limits_for_creating_reading_updating_and_deleting_data[may only have up to 20,000 operations which modify rows of a table].
  
  NOTE: Deleting a row counts as one operation and inserting/updating rows will count as a number of operations equal to the number of affected columns.
  For example if one inserts a row that contains 5 columns, it counts as 5 modify operations for the insert.
  
  Consequently, users must take care to avoid encountering these constraints.
  
  1. We recommend being careful with the use of `CASCADE_TYPE.ALL` in Entity annotations because, depending on the application, it might trigger a large number of entities to be deleted in a single transaction and bring you over the 20,000 limit.
  2. Also, when persisting a collection of entities, be mindful of the 20,000 mutations per transaction constraint.
  
  === Enable Hibernate Batching
  
  Batching SQL statements together allows you to optimize the performance of your application by including a group of SQL statements in a single remote call.
  This allows you to reduce the number of round-trips between your application and Cloud Spanner.
  
negative.code: 
  == User Guide
  
  This guide contains a variety of best practices for using Hibernate with Spanner which can significantly improve the performance of your application.
  
  === Schema Creation and Entity Design
  
  Hibernate generates statements based on your Hibernate entity design. Following these practices can result in better DDL and DML statement generation which can improve performance.
  
  ==== Use Generated UUIDs for ID Generation
  
  The Universally Unique Identifier (UUID) is the preferred ID type in Cloud Spanner because it avoids hotspots as the system divides data among servers by key ranges.
  UUIDs are strongly preferred over sequentially increasing IDs for this reason.
  
  It is also recommended to use Hibernate's `@GeneratedValue` annotation to generate this UUID automatically; this can reduce the number of statements that Hibernate generates to perform an insert because it does not need to run extra `SELECT` statements to see if the record already exists in the table.
  
  You can configure UUID generation like below:
  
  [source, java]
  ----
  