We’re very excited to announce the final availability of the Ruby Lively Report Adapter for Google Cloud Spanner. Ruby Lively Report is a strong Object-Relational Mapping(ORM) library bundled with Ruby on Rails. Lively Report gives an abstraction over the underlying database, and consists of capabilities equivalent to mechanically producing schema modifications and managing schema model historical past.
Regardless that Lively Report is often used with a Rails undertaking, it may be used with different frameworks like Sinatra or as a standalone library in your Ruby utility. With the GA of the adapter, Ruby purposes can now reap the benefits of Cloud Spanner’s excessive availability and exterior consistency at scale by means of an ORM.
The adapter is launched because the Ruby gem ruby-spanner-activerecord. Presently, it helps:
ActiveRecord 6.zero.x with Ruby 2.6 and a couple of.7.
ActiveRecord 6.1.x with Ruby 2.6 and better.
On this submit, we are going to cowl how one can begin with the adapter with a Rails utility and spotlight the supported options.
To make use of Lively Report with a Cloud Spanner database, you want an energetic Google Cloud undertaking with the Cloud Spanner API enabled. For extra particulars on getting began with Cloud Spanner, see the Cloud Spanner getting began information.
You should use your current Cloud Spanner occasion within the undertaking. In case you do not have already got one, or wish to begin from scratch for a brand new Ruby utility, you possibly can create a Cloud Spanner occasion utilizing the Google Cloud SDK, for instance:
To put in the adaptor, edit the `Gemfile` of your
Rails utility and add the
Subsequent, run bundle to put in the gem:
In a Rails app, it’s good to configure the database adapter by setting the Spanner undertaking, occasion, and database names. Since Cloud Spanner makes use of Cloud Id and Entry Administration to regulate person and group entry to its sources, you should utilize a Cloud Service Account with correct permissions to entry the databases. The configuration modifications might be made within the
config/database.yml file for a Rails undertaking.
To run your code regionally throughout improvement and testing for a Cloud Spanner database, you possibly can authenticate with Software Default Credentials, or set the
GOOGLE_APPLICATION_CREDENTIALS setting variable to authenticate utilizing a service account. This adapter delegates authentication to the Cloud Spanner Ruby shopper library. In case you’re already utilizing this or one other shopper library efficiently, you should not need to do something new to authenticate out of your Ruby utility. For extra data, see the shopper library’s documentation on establishing authentication.
In addition to utilizing a database within the Cloud, you may as well use Google’s Cloud Spanner Emulator. The acceptance checks for the adapter run in opposition to the emulator. If wanted, you should utilize the configuration within the Rakefile for instance.
Within the instance beneath, a service account secret’s used for the event setting. For the manufacturing setting, the applying makes use of the applying default credential.
Working with the Spanner Adapter
Upon getting configured the adapter, you should utilize the usual Rails tooling to create and handle databases. Following the Rails tutorial within the adapter repository, you’ll see how the shopper interacts with the Cloud Spanner API.
Create a database with tables
First, you possibly can create a database by working the next command:
Subsequent, you possibly can generate a knowledge mannequin, for instance:
The command above will generate a database migration file as the next:
Lively Report gives a strong schema model management system generally known as migrations. Every migration describes a change to an Lively Report knowledge mannequin that ends in a schema change. Lively Report tracks migrations in an inner `schema_migrations` desk, and consists of instruments for migrating knowledge between schema variations and producing migrations mechanically from an app’s fashions.
In case you run migration with the file above, it should certainly create an `articles` desk with two columns, `title` and `physique’:
After migration completes, you possibly can see the tables Lively Report created within the GCP Cloud Spanner Console:
Alternatively, you possibly can examine `information_schema.tables` to show the tables Ruby created utilizing the Google Cloud SDK:
Work together with the database utilizing Rails
After the database and tables are created, you possibly can work together with them out of your code or use the Rails CLI. To begin with the CLI, you
This command will begin a command immediate and you may run Ruby code inside it. For instance, to question the `articles` desk:
You’ll be able to see a `SELECT` SQL question runs beneath the hood. As anticipated, no file is returned for the reason that desk continues to be empty.
On the immediate, you possibly can initialize a brand new `Article` object and save the article to the database:
You’ll be able to see the adapter creates a SQL question to start out a transaction and insert a brand new file into the database desk.
In case you evaluation the article, you possibly can see the sphere `id`, `created_at`, and `updated_at` have been set:
You may also modify current information within the database. For instance, you possibly can change the `article` physique to one thing else and save the change:
This code ends in an `UPDATE` SQL assertion to vary the worth within the database. You’ll be able to confirm the end result from the Spanner console beneath the `Knowledge` web page:
The adapter helps the Lively Report Question Interface to retrieve knowledge from the database. For instance, you possibly can question by the `title` or `id` utilizing the next code. Each generate corresponding SQL statements to get the information again:
Migrating an Current Database
The Cloud Spanner Lively Report adapter additionally helps migrations for current databases.
For example, if you wish to add two new columns to an current desk, you possibly can create a migration file utilizing the `rails generate migration` command:
The command will produce a migration file like the next one:
Lastly, you possibly can run the `rails db:migrate` command to commit the schema change:
Once more, you may confirm the change from the Spanner console:
If you wish to rollback the migration, you possibly can run `rails db:rollback`. For extra particulars about migration, you possibly can learn the Lively Report Migrations doc. We additionally advocate you evaluation theSpanner schema replace documentation earlier than you implement any migration.
Generally when it’s good to learn and replace the database, you wish to group a number of statements in a single transaction. For these sorts of use instances, you possibly can manually management the learn/write transactions following this instance.
If it’s good to execute a number of constant reads and no write operations, it’s preferable to make use of a read-only transaction, as proven on this instance.
Commit timestamp columns might be configured throughout mannequin creation utilizing the `:commit_timestamp` image, as proven on this instance. The commit timestamps might be learn after an insert and/or an replace transaction is accomplished.
Relying on the transaction sort, the adapter mechanically chooses between mutations and DML for executing updates. For effectivity, it makes use of mutations as an alternative of DML the place doable. If you wish to know how one can use the `:buffered_mutations` isolation stage to instruct the adapter to make use of mutations explicitly, you possibly can learn this instance.
Cloud Spanner helps varied assertion hints and desk hints, that are additionally supported by the adapter. This instance exhibits how one can use the `optimizer_hints` technique to specify assertion and desk hints. You may also discover a be part of trace within the instance, which can’t use the tactic however a be part of string as an alternative.
Cloud Spanner gives two learn varieties. By default, all read-only transactions will default to performing robust reads. You’ll be able to decide into performing a stale learn when querying knowledge through the use of an express timestamp certain as proven on this instance.
Cloud Spanner helps generated columns, which might be configured within the migration lessons utilizing the `as` key phrase. This instance exhibits how a generated column is used, and the `as` key phrase is used within the class.
The adapter has a number of limitations. For instance, it doesn’t auto-generate values for major keys as a consequence of Cloud Spanner not supporting sequences, identification columns, or different worth mills within the database. In case your desk doesn’t include a pure major key, a great apply is to make use of a client-side UUID generator for a major key.
We advocate that you simply undergo the listing of limitations earlier than deploying any initiatives utilizing this adapter. These limitations are documented right here.
Prospects utilizing the Cloud Spanner Emulator might even see totally different conduct than the Cloud Spanner service. For example, the emulator does not assist concurrent transactions. See the Cloud Spanner Emulator documentation for a listing of limitations and variations from the Cloud Spanner service.
We would love to listen to from you, particularly in the event you’re a Rails person contemplating Cloud Spanner or an current Cloud Spanner buyer who’s contemplating utilizing Ruby for brand spanking new initiatives. The undertaking is open-source, and you may remark, report bugs, and open pull requests on Github.
We want to thank Knut Olav Løite and Jiren Patelfor their work on this undertaking.
Earlier than you get began, it’s good to have a Rails undertaking. For an entire instance, you will discover it within the gem’s GitHub repo or
Ruby Cloud Spanner Lively Report adapter documentation
Cloud Spanner Ruby shopper library documentation
Cloud Spanner product documentation
Ruby Lively Report Fundamentals
Neighborhood tutorial for Spanner and Lively Report on Medium.