Google Cloud Spanner with Entity Framework Core

Google Cloud Spanner is a fully managed, scalable, relational database service for regional and global application data. It is the first scalable, enterprise-grade, globally-distributed, and strongly consistent database service built for the cloud specifically to combine the benefits of relational database structure with non-relational horizontal scale.

Entity Framework (EF) Core is a lightweight, extensible, open source and cross-platform version of the popular Entity Framework data access technology. EF Core can now serve as an object-relational mapper (O/RM) for Google Cloud Spanner using its open source provider. This article will help you get started with Entity Framework Core for Spanner by creating a simple Console App that uses Spanner with EF Core.

Create Project and Add Provider

The source code of the sample project that is used by this tutorial can be found here.

First create an empty ConsoleApp in Visual Studio. Then add the Entity Framework Core provider for Google Cloud Spanner to the project by following the instructions in the readme.

Create Local NuGet Package

The Entity Framework Core provider for Google Cloud Spanner currently has preview release status and does not have production grade support.

Tip: You can also skip the below steps and clone the repository from GitHub and add the Entity Framework Core project as a Project Reference to your ConsoleApp.

1. Clone the dotnet-spanner-entity-framework repository to your local system.
2. Open the solution in Visual Studio, right-click on the Google.Cloud.EntityFrameworkCore.Spanner project and click on Pack. This will generate a nuget local package of the project that you can use in your ConsoleApp.
3. Download the NuGet executable and copy into your local feed (e.g. C:\local-nuget-feed).
4. Open the Command Prompt and go to your local feed path (e.g. C:\local-nuget-feed).
5. Run the command below to add the package to your local nuget feed:
   nuget add path\to\source\Google.Cloud.EntityFrameworkCore.Spanner\bin\Debug|Release\Google.Cloud.EntityFrameworkCore.Spanner.1.0.0-beta.nupkg -Source C:\local-nuget-feed
6. Go back to Visual Studio and add your local feed as a package source for nuget. Do this by clicking Tools | NuGet Package Manager | Package Manager Settings (the exact menu item might differ depending on your Visual Studio version). Select Package Sources and click Add. Select your local nuget feed (e.g. C:\local-nuget-feed) and give it a reasonable name.
7. Add the Package to your ConsoleApp project by clicking Tools | NuGet Package Manager | Manage NuGet Packages for Solution. Make sure to select your local nuget feed as Package Source and enable the Include Prereleases option. Select the Google.Cloud.EntityFrameworkCore.Spanner from the list.

Create a Model

In Entity Framework, data is accessed using a model. A model is made up of entity classes, additional configuration of your entities, and a context object that represents a session with the database. This tutorial uses the following model.

Sample Model for Entity Framework Core

The above sample model contains three entities; Singer, Album and Track. This model also shows the two possibilities you have when creating entities that are related to each other in Spanner:

• Album references Singer using a normal foreign key constraint. This will ensure that each Album references an existing Singer record, and that a Singer cannot be deleted without also deleting all Albums of that Singer.
• Track references Album by being interleaved in the parent entity Album. This will ensure that all Track records are stored physically together with the parent Album.

Note that you should only choose one of the two for a relationship between two specific entities, and not both.

Data Model

The corresponding data model that is used with this model is listed below.

Data Model

You can also let Entity Framework generate the data model for you using Migrations, or you can let Entity Framework generate the code from an existing database. See Managing Schemas for more information on this. This tutorial creates both manually in order to keep things as simple as possible.

Inserting Data

The context class that we defined in our model contains a DbSet for each entity that we have defined. Inserting data into the database is as simple as:

1. Create a context that will connect to the database.
2. Add new entities to the sets.
3. Call SaveChanges on the context.

Inserting Data using Entity Framework Core

Querying Data

We also use the DbSet to query data from the database. You can get single entities from a set by specifying the key of the entity, or you can use LINQ to query for a collection of entities.

Query Data using Entity Framework Core

Further Samples

The Cloud Spanner Entity Framework Core provider repository contains several additional samples for specific features of Entity Framework in combination with Cloud Spanner. These include amongst others:

• Manual read/write transactions
• Read-only transactions
• Using concurrency tokens in Entity Framework Core with Cloud Spanner
• Writing commit timestamps automatically when an entity is saved
• Working with Array data types

Please have a look at the repository for a complete list.

Runnable Code

A complete sample project based on this tutorial can be found here. It is a runnable application that does not require a Google Cloud Spanner database, as it uses the Cloud Spanner emulator. It can be found here: https://github.com/olavloite/spanner-efcore-tutorial