Tutorial: Use Google Cloud Spanner with Spring Boot, JPA and Hibernate

on Google_Cloud_Spanner, Google_Cloud, Cloud_Spanner, Spring_Boot, JPA, Hibernate, JDBC, Java, Open_Source

A new version of this article can be found here: http://www.googlecloudspanner.com/2017/09/google-cloud-spanner-with-jpa-and.html. Click on the link if you are not redirected automatically.

Google Cloud Spanner is Google’s horizontally scalable, globally consistent, relational database service. Cloud Spanner claims to be the first and only relational database service that is both strongly consistent and horizontally scalable. Cloud Spanner supports transactions and SQL queries and could in theory be used with any application currently running on other relational databases. This tutorial will guide you through the steps needed to set up a test environment for developing a Spring Boot application with Cloud Spanner as its data source using JPA/Hibernate.

Step 1: Create a Cloud Spanner test database

Google kindly offers a $300 in free credit for trying out Cloud Spanner. Go to https://cloud.google.com/spanner/ and click on Try It Free to create a test instance. Go through the registration process and then follow these steps to create a Cloud Spanner instance and database:

  1. If you register for the first time with Google Cloud, Google automatically creates a project for you with the title 'My first project' and a generated project id. Rename this project to something like cloudspanner-test. If you already have a Google Cloud account, you can add a new project.

  2. Click on the main menu button in the top left corner next to the text Google Cloud Platform and select Spanner. Google will now initialize Cloud Spanner for your project.

  3. Create an instance with these values:

    • Instance name: Test Instance

    • Instance id: test-instance

    • Configuration: your choice

    • Nodes: 1

  4. Create a database with these values:

    • Database name: test-database

    • Tables: Do not create any tables now

  5. Now we will create a service account that you can use to access the database remotely. Click on the main menu button in the top left corner and select IAM & Admin.

  6. Click on Service accounts in the menu on the left.

  7. Click on Create Service Account on top of the page.

  8. Name the service account spanner and select the role Cloud Spanner | Cloud Spanner Admin. Turn on the option Furnish a private key and choose JSON. This key file will be downloaded to your computer and you will need it to access the database remotely. Click on Create.

That’s it! You have now created the Google Cloud Spanner database needed for this tutorial.

Step 2: Get and Run the Example Project

I have created a sample project that will be used for this tutorial. Clone the project from https://github.com/olavloite/spanner-jpa-example . It is a Maven project with a dependency on a JDBC Driver for Google Cloud Spanner and on a Hibernate Dialect library. Make sure to get these dependencies. They are available on Maven Central. Then follow these steps:

  1. Find the file application.properties.example in the root of the project and make a copy of this and name the copy application.properties.

  2. Open application.properties and change the value of spring.datasource.url into the following string. Make sure you change the placeholder [project-id] with the project id generated by Google (this is NOT the project name). Also change the placeholder [path-to-keyfile] with the actual location on your local disk of the JSON keyfile generated in the steps above:

    jdbc:cloudspanner://localhost;Project=[project-id];Instance=test-instance;Database=test-database;PvtKeyPath=[path-to-keyfile]

  3. Run the Java application (the main class is Application.class). The application is configured to automatically create the tables needed for the entities that are defined in the source code. This example project contains two entities (Customer and Invoice), and these tables will be created. Note that this process can take some time as Cloud Spanner is not very quick when it comes to DDL.

  4. The application will then try to insert and then select some records into Cloud Spanner

You can try to experiment with additional entities and also try to update some of them by changing the code. Please note that the DDL statement support of Google Cloud Spanner is somewhat limited. Adding nullable columns to existing tables and adding new tables should work without any hassle. More complex changes, such as changing an existing column, might produce errors and need to be changed manually through the web interface of Google Cloud Spanner.