Jump to Content

Golang’s GORM support for Cloud Spanner is now Generally Available

November 7, 2023
Rahul Yadav

Software Engineer, Google Cloud


GORM is an Object Relational Mapping (ORM) library for Golang. ORM converts data between incompatible type systems using object-oriented programming languages. An ORM library is a library that implements this technique and provides an object-oriented layer between relational databases and object-oriented programming languages. Do you have an application that you developed with GORM and now you want to migrate to a cloud database? Google Cloud Spanner now supports the GORM Object Relational Mapper. You can reuse existing GORM code with the Cloud Spanner, or write new features while leveraging existing knowledge.

The Cloud Spanner Go ORM implements all the classes and interfaces that are needed to use Cloud Spanner with GORM. Add the spanner GORM module to your project and connect to Cloud Spanner as follows:


Simple install the package to your $GOPATH with the go tool from shell:



Connect to Cloud Spanner with GORM:


Note that as GORM implementation uses the Go client to connect to Spanner, it is not necessary to specify a custom endpoint to connect to the Spanner emulator(a local, in-memory emulator, which you can use to develop and test your applications for free without creating a GCP Project or a billing account). The driver will automatically connect to the emulator if the SPANNER_EMULATOR_HOST environment variable has been set.


The Cloud Spanner GORM supports standard GORM features, like querying data using both positional and named parameters, managing associations and executing transactions. GORM also supports specific Spanner features such as interleaved tables, mutations, and stale reads by unwrapping the underlying connection. This means that you can use GORM to write code that is both powerful and scalable.

For example, the following code snippet shows a simple write and read operation to Spanner, backed by Spanner's infinite scalability. If your product takes off, you don't have to rewrite anything for sharding, etc. Just add more nodes!


Interleaved Tables

Using interleaved tables for parent-child relationships in your schema can improve performance. Interleaving a child table with a parent means that the child records will be stored physically together with the parent. These relationships can be modeled and used as any other association in GORM.



GORM will use Data Manipulation Language (DML) by default. You can run mutations by unwrapping the Spanner connection:


Further samples

The GitHub repository contains a directory with multiple samples for common use cases for working with GORM and/or Cloud Spanner.


Cloud Spanner features that are not supported in the GORM are listed here.

Getting involved

We'd love to hear from you, especially if you're a Golang developer considering Cloud Spanner or an existing Cloud Spanner customer who is considering using database/sql for new projects. The project is open-source, and you can comment, report bugs, and open pull requests on Github.

We would like to thank Knut Olav Løite for their work on this project.

See also

Before you get started, you need to have a golang project. For a complete set of examples, you can find them in the examples directory for the driver. You can additionally refer:

Posted in