ActiveRecord Cloud Spanner Adapter
Google Cloud Spanner adapter for ActiveRecord.
This adapter only supports GoogleSQL-dialect Spanner databases. PostgreSQL-dialectdatabases are not supported. You can use the standard PostgreSQL ActiveRecord adapter incombination with PGAdapterfor Spanner PostgreSQL-dialect databases.
This project provides a Spanner adapter for ActiveRecord. It supports the following versions:
- ActiveRecord 7.0.x with Ruby 3.1 and higher.
- ActiveRecord 7.1.x with Ruby 3.1 and higher.
- ActiveRecord 7.2.x with Ruby 3.1 and higher.
- ActiveRecord 8.0.x with Ruby 3.2 and higher.
Known limitations are listed in theLimitations section.Please report any problems that you might encounter bycreating a new issue.
Installation
Add this line to your application's Gemfile:
gem'activerecord-spanner-adapter'
If you would like to use latest adapter version from github then specify
gem'activerecord-spanner-adapter',:git=>'git@github.com:googleapis/ruby-spanner-activerecord.git'
And then execute:
$ bundleUsage
Migrations
Use DDL batching when executing migrations for the best possible performance.
Executing multiple schema changes on Spanner can take a long time. It is thereforestrongly recommended that you limit the number of schema change operations. You can dothis by using DDL batching in your migrations. Seethe migrations examplesfor how to do this.
Database Connection
In Rails applicationconfig/database.yml, make the change as the following:
development: adapter: "spanner" project: "<google project name>" instance: "<google instance name>" credentials: "<google credentails file path>" database: "app-dev"Examples
To get started with Rails, read the tutorial underexamples/rails/README.md.
You can also find a list of short self-contained code examples that show howto use ActiveRecord with Spanner under the directoryexamples/snippets. Each example is directly runnable without the need to setup a Spannerdatabase, as all samples will automatically start a Spanner emulator in a Docker container and execute the samplecode against that emulator. All samples can be executed by navigating to the sample directory on your local machine andthen executing the commandbundle exec rake run. Example:
cd ruby-spanner-activerecord/examples/snippets/quickstartbundle exec rake runNOTE: You do need to haveDocker installed on your local system to run these examples.
Some noteworthy examples in the snippets directory:
- quickstart: A simple application that shows how to create and query a simple database containing two tables.
- migrations: Shows a best-practice for executing migrations on Spanner.
- auto-generated-primary-key: Shows how to use IDENTITY columns for primary keys.
- bit-reversed-sequences: Shows how to use bit-reversed sequences for primary keys.
- read-write-transactions: Shows how to execute transactions on Spanner.
- read-only-transactions: Shows how to execute read-only transactions on Spanner.
- bulk-insert: Shows the best way to insert a large number of new records.
- mutations: Shows how you can usemutations instead of DMLfor inserting, updating and deleting data in a Spanner database. Mutations can have a significant performanceadvantage compared to DML statements, but do not allow read-your-writes semantics during a transaction.
- array-data-type: Shows how to work with
ARRAYdata types. - interleaved-tables: Shows how to work withInterleaved Tables.
Limitations
| Limitation | Comment | Resolution |
|---|---|---|
| Interleaved tables require composite primary keys | Spanner requires composite primary keys for interleaved tables. Seethis example for an example on how to use interleaved tables with ActiveRecord | Use composite primary keys. |
| Lack of sequential IDs | Spanner uses either bit-reversed IDENTITY columns or sequences to generated primary keys to avoidhotspotting so you SHOULD NOT rely on IDs being sorted | Use either IDENTITY columns or bit-reversed sequences to automatically generate primary keys. |
| Table without Primary Key | Spanner support does not support tables without a primary key. | Always define a primary key for your table. |
| Table names CANNOT have spaces within them whether back-ticked or not | Spanner DOES NOT support tables with spaces in them for exampleEntity ID | Ensure that your table names don't contain spaces. |
| Table names CANNOT have punctuation marks and MUST contain valid UTF-8 | Spanner DOES NOT support punctuation marks e.g. periods ".", question marks "?" in table names | Ensure that your table names don't contain punctuation marks. |
| Index with fields lengthadd_index | Spanner does not support index with fields length | Ensure that your database definition does not include index definitions with field lengths. |
| Only GoogleSQL-dialect databases | Spanner supports both GoogleSQL- and PostgreSQL-dialect databases. This adapter only supports GoogleSQL-dialect databases. You can use thePostgreSQL ActiveRecord provider in combination with PGAdapter for Spanner PostgreSQL databases. | |
rails dbconsole is not supported. | Therails dbconsole is not supported for Spanner databases. |
Contributing
Bug reports and pull requests are welcome on GitHub athttps://github.com/googleapis/ruby-spanner-activerecord. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to theContributor Covenant code of conduct.
License
The gem is available as open source under the terms of theMIT License.
Code of Conduct
Everyone interacting in the Activerecord::Spanner project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow thecode of conduct.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-10-30 UTC.