activerecord-spanner-adapter 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3761fdcb057da7fcec3150ec38e865bdb61d50eff368634146eefff6fb2bea27
-  data.tar.gz: cebbacfbbce4943f0d4cc799dfa2abc6deb352c2069059e6aac869293063eb6c
+  metadata.gz: 55f265a14ddd7a176378a49090cbb3277aae66ce2c74913978ec9614289759fc
+  data.tar.gz: ae48998a381c0142063ac4499c8a0c13ece58bded34a72cbcc0371541ee02231
 SHA512:
-  metadata.gz: 6aeefe0da3b1c627a2e5319b84f7d1519630421d773420197810b3e619e3f766e02ccd67cc89e9daf7ddee14985eb7aec371d1a685a5ff27004a57864f5e7ef4
-  data.tar.gz: 0c807717d9d42ee7624a4e0710626718a89f0a51a2e3c968001f3d01587dd13448ac57c5569af3d82d417305bfa63f46cb932cae8d007735f68fde080d4e119e
+  metadata.gz: fa104b38f89edc91eb78d05b5f89e232fb50847953061eae4e3c9eb12bf307f9a0cf69545eb06a0682c92b2ac7bce065b8d88f8fa148570b4720b47ccccad0d5
+  data.tar.gz: 3de12a8b087940d6234ecd902ea7b109a8319960700dd323c363da266aa299f211b003e50fb01e24ff5e4632e4372b5451e0d129168cacfa3541771263dc2703

data/.github/workflows/acceptance-tests-on-production.yaml

@@ -5,7 +5,20 @@ on:
   pull_request:
 name: acceptance tests on production
 jobs:
+  check-env:
+    outputs:
+      has-key: ${{ steps.project-id.outputs.defined }}
+    runs-on: ubuntu-latest
+    steps:
+    - id: project-id
+      env:
+        GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
+      if: "${{ env.GCP_PROJECT_ID != '' }}"
+      run: echo "::set-output name=defined::true"
+
   test:
+    needs: [check-env]
+    if: needs.check-env.outputs.has-key == 'true'
     runs-on: ubuntu-latest
 
     strategy:

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.6.0](https://www.github.com/googleapis/ruby-spanner-activerecord/compare/activerecord-spanner-adapter/v0.5.0...activerecord-spanner-adapter/v0.6.0) (2021-09-09)
+
+
+### Features
+
+* support JSON data type ([#123](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/123)) ([d177ddf](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/d177ddfc7326f02189bd4054571564b94d162b02))
+* support single stale reads ([#127](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/127)) ([a600628](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/a600628267355b808f478ed543bc505e73f95d4a))
+* support stale reads in read-only transactions ([#126](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/126)) ([8bf7730](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/8bf77300283c01e951725dd5e457270db20e98d2))
+
 ## 0.5.0 (2021-08-31)
 
 

data/acceptance/cases/transactions/read_only_transactions_test.rb

@@ -35,6 +35,69 @@ module ActiveRecord
         end
       end
 
+      def test_read_in_snapshot_at_timestamp
+        # Get a valid timestamp from the server to use for the transaction.
+        timestamp = ActiveRecord::Base.connection.select_all("SELECT CURRENT_TIMESTAMP AS ts")[0]["ts"]
+        Base.transaction isolation: { timestamp: timestamp } do
+          org = Organization.find @organization.id
+          assert_equal "Organization 1", org.name
+        end
+      end
+
+      def test_read_in_snapshot_with_staleness
+        Base.transaction isolation: { staleness: 1 } do
+          begin
+            # It could be that the record or even the table cannot be found, as the read timestamp could be
+            # before either of them were created, but the record could also be found, all depending on the execution
+            # speed of the test. All those scenarios are valid.
+            org = Organization.find @organization.id
+            assert_equal "Organization 1", org.name
+          rescue => e
+            assert e.message.include?("Table not found") || e.message.include?("Couldn't find Organization"), e.message
+          end
+        end
+      end
+
+      def test_single_read_at_timestamp
+        # Get a valid timestamp from the server to use for the transaction.
+        timestamp = ActiveRecord::Base.connection.select_all("SELECT CURRENT_TIMESTAMP AS ts")[0]["ts"]
+
+        org = Organization.optimizer_hints("read_timestamp:#{timestamp.xmlschema(9)}").find @organization.id
+        assert_equal "Organization 1", org.name
+      end
+
+      def test_single_read_at_min_read_timestamp
+        # Get a valid timestamp from the server to use for the transaction.
+        timestamp = ActiveRecord::Base.connection.select_all("SELECT CURRENT_TIMESTAMP AS ts")[0]["ts"]
+
+        org = Organization.optimizer_hints("min_read_timestamp:#{timestamp.xmlschema(9)}").find @organization.id
+        assert_equal "Organization 1", org.name
+      end
+
+      def test_single_read_with_max_staleness
+        begin
+          # It could be that the record or even the table cannot be found, as the read timestamp could be
+          # before either of them were created, but the record could also be found, all depending on the execution
+          # speed of the test. All those scenarios are valid.
+          org = Organization.optimizer_hints("max_staleness: 1").find @organization.id
+          assert_equal "Organization 1", org.name
+        rescue => e
+          assert e.message.include?("Table not found") || e.message.include?("Couldn't find Organization"), e.message
+        end
+      end
+
+      def test_single_read_with_exact_staleness
+        begin
+          # It could be that the record or even the table cannot be found, as the read timestamp could be
+          # before either of them were created, but the record could also be found, all depending on the execution
+          # speed of the test. All those scenarios are valid.
+          org = Organization.optimizer_hints("exact_staleness: 1").find @organization.id
+          assert_equal "Organization 1", org.name
+        rescue => e
+          assert e.message.include?("Table not found") || e.message.include?("Couldn't find Organization"), e.message
+        end
+      end
+
       def test_snapshot_does_not_see_new_changes
         Base.transaction isolation: :read_only do
           org = Organization.find @organization.id

data/acceptance/cases/type/all_types_test.rb

@@ -30,6 +30,7 @@ module ActiveRecord
         AllTypes.create col_string: "string", col_int64: 100, col_float64: 3.14, col_numeric: 6.626, col_bool: true,
           col_bytes: StringIO.new("bytes"), col_date: ::Date.new(2021, 6, 23),
           col_timestamp: ::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"),
+          col_json: ENV["SPANNER_EMULATOR_HOST"] ? "" : { kind: "user_renamed", change: %w[jack john]},
           col_array_string: ["string1", nil, "string2"],
           col_array_int64: [100, nil, 200],
           col_array_float64: [3.14, nil, 2.0/3.0],
@@ -38,7 +39,10 @@ module ActiveRecord
           col_array_bytes: [StringIO.new("bytes1"), nil, StringIO.new("bytes2")],
           col_array_date: [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24)],
           col_array_timestamp: [::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"), nil, \
-                                ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00")]
+                                ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00")],
+          col_array_json: ENV["SPANNER_EMULATOR_HOST"] ? [""] : \
+                            [{ kind: "user_renamed", change: %w[jack john]}, nil, \
+                             { kind: "user_renamed", change: %w[alice meredith]}]
       end
 
       def test_create_record
@@ -61,6 +65,8 @@ module ActiveRecord
           assert_equal StringIO.new("bytes").read, record.col_bytes.read
           assert_equal ::Date.new(2021, 6, 23), record.col_date
           assert_equal ::Time.new(2021, 6, 23, 17, 8, 21, "+02:00").utc, record.col_timestamp.utc
+          assert_equal ({"kind" => "user_renamed", "change" => %w[jack john]}),
+                       record.col_json unless ENV["SPANNER_EMULATOR_HOST"]
 
           assert_equal ["string1", nil, "string2"], record.col_array_string
           assert_equal [100, nil, 200], record.col_array_int64
@@ -74,6 +80,10 @@ module ActiveRecord
                             nil, \
                             ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00")].map { |timestamp| timestamp&.utc },
                        record.col_array_timestamp.map { |timestamp| timestamp&.utc}
+          assert_equal [{"kind" => "user_renamed", "change" => %w[jack john]}, \
+                        nil, \
+                        {"kind" => "user_renamed", "change" => %w[alice meredith]}],
+                       record.col_array_json unless ENV["SPANNER_EMULATOR_HOST"]
         end
       end
 
@@ -88,6 +98,7 @@ module ActiveRecord
                           col_bool: false, col_bytes: StringIO.new("new bytes"),
                           col_date: ::Date.new(2021, 6, 28),
                           col_timestamp: ::Time.new(2021, 6, 28, 11, 22, 21, "+02:00"),
+                          col_json: ENV["SPANNER_EMULATOR_HOST"] ? "" : { kind: "user_created", change: %w[jack alice]},
                           col_array_string: ["new string 1", "new string 2"],
                           col_array_int64: [300, 200, 100],
                           col_array_float64: [1.1, 2.2, 3.3],
@@ -95,7 +106,10 @@ module ActiveRecord
                           col_array_bool: [false, true, false],
                           col_array_bytes: [StringIO.new("new bytes 1"), StringIO.new("new bytes 2")],
                           col_array_date: [::Date.new(2021, 6, 28)],
-                          col_array_timestamp: [::Time.utc(2020, 12, 31, 0, 0, 0)]
+                          col_array_timestamp: [::Time.utc(2020, 12, 31, 0, 0, 0)],
+                          col_array_json: ENV["SPANNER_EMULATOR_HOST"] ?
+                                            [""] : \
+                                            [{ kind: "user_created", change: %w[jack alice]}]
           end
 
           # Verify that the record was updated.
@@ -108,6 +122,8 @@ module ActiveRecord
           assert_equal StringIO.new("new bytes").read, record.col_bytes.read
           assert_equal ::Date.new(2021, 6, 28), record.col_date
           assert_equal ::Time.new(2021, 6, 28, 11, 22, 21, "+02:00").utc, record.col_timestamp.utc
+          assert_equal ({"kind" => "user_created", "change" => %w[jack alice]}),
+                       record.col_json unless ENV["SPANNER_EMULATOR_HOST"]
 
           assert_equal ["new string 1", "new string 2"], record.col_array_string
           assert_equal [300, 200, 100], record.col_array_int64
@@ -118,6 +134,8 @@ module ActiveRecord
                        record.col_array_bytes.map(&:read)
           assert_equal [::Date.new(2021, 6, 28)], record.col_array_date
           assert_equal [::Time.utc(2020, 12, 31, 0, 0, 0)], record.col_array_timestamp.map(&:utc)
+          assert_equal [{"kind" => "user_created", "change" => %w[jack alice]}],
+                       record.col_array_json unless ENV["SPANNER_EMULATOR_HOST"]
         end
       end
 
@@ -133,7 +151,8 @@ module ActiveRecord
               col_array_bool: [],
               col_array_bytes: [],
               col_array_date: [],
-              col_array_timestamp: []
+              col_array_timestamp: [],
+              col_array_json: []
           end
 
           record = AllTypes.find record.id
@@ -145,6 +164,7 @@ module ActiveRecord
           assert_equal [], record.col_array_bytes
           assert_equal [], record.col_array_date
           assert_equal [], record.col_array_timestamp
+          assert_equal [], record.col_array_json
         end
       end
     end

data/acceptance/cases/type/json_test.rb

@@ -0,0 +1,34 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+# frozen_string_literal: true
+
+require "test_helper"
+
+module ActiveRecord
+  module Type
+    class DateTest < SpannerAdapter::TestCase
+      include SpannerAdapter::Types::TestHelper
+
+      def test_convert_to_sql_type
+        assert_equal "JSON", connection.type_to_sql(:json)
+      end
+
+      def test_set_json
+        return if ENV["SPANNER_EMULATOR_HOST"]
+
+        expected_hash = {"key"=>"value", "array_key"=>%w[value1 value2]}
+        record = TestTypeModel.new details: {key: "value", array_key: %w[value1 value2]}
+
+        assert_equal expected_hash, record.details
+
+        record.save!
+        record.reload
+        assert_equal expected_hash, record.details
+      end
+    end
+  end
+end

data/acceptance/schema/schema.rb

@@ -17,6 +17,8 @@ ActiveRecord::Schema.define do
       t.column :col_bytes, :binary
       t.column :col_date, :date
       t.column :col_timestamp, :datetime
+      t.column :col_json, :json unless ENV["SPANNER_EMULATOR_HOST"]
+      t.column :col_json, :string if ENV["SPANNER_EMULATOR_HOST"]
 
       t.column :col_array_string, :string, array: true
       t.column :col_array_int64, :bigint, array: true
@@ -26,6 +28,8 @@ ActiveRecord::Schema.define do
       t.column :col_array_bytes, :binary, array: true
       t.column :col_array_date, :date, array: true
       t.column :col_array_timestamp, :datetime, array: true
+      t.column :col_array_json, :json, array: true unless ENV["SPANNER_EMULATOR_HOST"]
+      t.column :col_array_json, :string, array: true if ENV["SPANNER_EMULATOR_HOST"]
     end
 
     create_table :firms do |t|

data/acceptance/test_helper.rb

@@ -208,6 +208,7 @@ module SpannerAdapter
           t.date :start_date
           t.datetime :start_datetime
           t.time :start_time
+          t.json :details unless ENV["SPANNER_EMULATOR_HOST"]
         end
       end
 

data/activerecord-spanner-adapter.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 2.5"
 
-  spec.add_dependency "google-cloud-spanner", "~> 2.4"
+  spec.add_dependency "google-cloud-spanner", "~> 2.10"
   spec.add_runtime_dependency "activerecord", "~> 6.1.4"
 
   spec.add_development_dependency "autotest-suffix", "~> 1.1"

data/examples/snippets/read-only-transactions/application.rb

@@ -10,7 +10,7 @@ require_relative "models/singer"
 require_relative "models/album"
 
 class Application
-  def self.run # rubocop:disable Metrics/AbcSize
+  def self.run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     # Use a read-only transaction to execute multiple reads at the same commit timestamp.
     # The Spanner ActiveRecord adapter supports the custom isolation level :read_only that
     # will start a read-only Spanner transaction with a strong timestamp bound.
@@ -40,6 +40,34 @@ class Application
     puts "Album title 1: #{album1.reload.title}"
     puts "Album title 2: #{album2.reload.title}"
 
+    # You can also execute a stale read with ActiveRecord. Specify a hash as the isolation level with one of
+    # the following options:
+    # * timestamp: Read data at a specific timestamp.
+    # * staleness: Read data at a specific staleness measured in seconds.
+
+    # Get a valid timestamp from the server to use for the transaction.
+    timestamp = ActiveRecord::Base.connection.select_all("SELECT CURRENT_TIMESTAMP AS ts")[0]["ts"]
+    puts ""
+    puts "Read data at timestamp #{timestamp}"
+    ActiveRecord::Base.transaction isolation: { timestamp: timestamp } do
+      puts "Album title 1: #{album1.reload.title}"
+      puts "Album title 2: #{album2.reload.title}"
+    end
+
+    puts ""
+    puts "Read data with staleness 30 seconds"
+    ActiveRecord::Base.transaction isolation: { staleness: 30 } do
+      begin
+        puts "Album title 1: #{album1.reload.title}"
+      rescue StandardError => e
+        # The table will (in almost all cases) not be found, because the timestamp that is being used to read
+        # the data will be before the table was created. This will therefore cause a 'Table not found' error.
+        puts "Reading data with 30 seconds staleness failed with error: #{e.message}"
+        puts ""
+        puts "This error is expected."
+      end
+    end
+
     puts ""
     puts "Press any key to end the application"
     STDIN.getch

data/examples/snippets/read-only-transactions/db/schema.rb

@@ -2,8 +2,8 @@
 # of editing this file, please use the migrations feature of Active Record to
 # incrementally modify your database, and then regenerate this schema definition.
 #
-# This file is the source Rails uses to define your schema when running `rails
-# db:schema:load`. When creating a new database, `rails db:schema:load` tends to
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
 # be faster and is potentially less error prone than running all of your
 # migrations from scratch. Old migrations may fail to apply correctly if those
 # migrations use external dependencies or application code.
@@ -12,12 +12,12 @@
 
 ActiveRecord::Schema.define(version: 1) do
 
-  create_table "albums", force: :cascade do |t|
+  create_table "albums", id: { limit: 8 }, force: :cascade do |t|
     t.string "title"
     t.integer "singer_id", limit: 8
   end
 
-  create_table "singers", force: :cascade do |t|
+  create_table "singers", id: { limit: 8 }, force: :cascade do |t|
     t.string "first_name"
     t.string "last_name"
   end

data/examples/snippets/stale-reads/README.md

@@ -0,0 +1,27 @@
+# Sample - Stale reads
+
+Read and query operations outside of a transaction block will by default be executed using a
+single-use read-only transaction with strong timestamp bound. This means that the read is
+guaranteed to return all data that has been committed at the time of the read. It is also possible
+to specify that the Spanner ActiveRecord provider should execute a stale read. This is done by
+specifying an optimizer hint for the read or query operation. The hints that are available are:
+
+* `max_staleness: <seconds>`
+* `exact_staleness: <seconds>`
+* `min_read_timestamp: <timestamp>`
+* `read_timestamp: <timestamp>`
+
+See https://cloud.google.com/spanner/docs/timestamp-bounds for more information on what the
+different timestamp bounds in Cloud Spanner mean.
+
+NOTE: These optimizer hints ONLY work OUTSIDE transactions. See the read-only-transactions
+samples for more information on how to specify a timestamp bound for a read-only transaction.
+
+The sample will automatically start a Spanner Emulator in a docker container and execute the sample
+against that emulator. The emulator will automatically be stopped when the application finishes.
+
+Run the application with the command
+
+```bash
+bundle exec rake run
+```

data/examples/snippets/stale-reads/Rakefile

@@ -0,0 +1,13 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require_relative "../config/environment"
+require "sinatra/activerecord/rake"
+
+desc "Sample showing how to execute stale reads on Spanner with ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[stale-reads]" }
+end

data/examples/snippets/stale-reads/application.rb

@@ -0,0 +1,63 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require "io/console"
+require_relative "../config/environment"
+require_relative "models/singer"
+require_relative "models/album"
+
+class Application
+  def self.run # rubocop:disable Metrics/AbcSize
+    # Get a random album.
+    album = Album.all.sample
+
+    # Get a valid timestamp from the Cloud Spanner server that we can use to specify a timestamp bound.
+    timestamp = ActiveRecord::Base.connection.select_all("SELECT CURRENT_TIMESTAMP AS ts")[0]["ts"]
+
+    # Update the name of the album and then read the version of the album before the update.
+    album.update title: "New title"
+
+    # The timestamp should be specified in the format '2021-09-07T15:22:10.123456789Z'
+    timestamp_string = timestamp.xmlschema 9
+
+    # Read the album at a specific timestamp.
+    album_previous_version = Album.optimizer_hints("read_timestamp: #{timestamp_string}").find_by id: album.id
+    album = album.reload
+
+    puts ""
+    puts "Updated album title: #{album.title}"
+    puts "Previous album version title: #{album_previous_version.title}"
+
+    # Read the same album using a minimum read timestamp. It could be that we get the first version
+    # of the row, but it could also be that we get the updated row.
+    album_min_read_timestamp = Album.optimizer_hints("min_read_timestamp: #{timestamp_string}").find_by id: album.id
+    puts ""
+    puts "Updated album title: #{album.title}"
+    puts "Min-read timestamp title: #{album_min_read_timestamp.title}"
+
+    # Staleness can also be specified as a number of seconds. The number of seconds may contain a fraction.
+    # The following reads the album version at exactly 1.5 seconds ago. That will normally be nil, as the
+    # row did not yet exist at that moment.
+    album_exact_staleness = Album.optimizer_hints("exact_staleness: 1.5").find_by id: album.id
+
+    puts ""
+    puts "Updated album title: #{album.title}"
+    puts "Title 1.5 seconds ago: #{album_exact_staleness&.title}"
+
+    # You can also specify a max staleness. The server will determine the best timestamp to use for the read.
+    album_max_staleness = Album.optimizer_hints("max_staleness: 10").find_by id: album.id
+
+    puts ""
+    puts "Updated album title: #{album.title}"
+    puts "Title somewhere during the last 10 seconds: #{album_max_staleness&.title}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/stale-reads/config/database.yml

@@ -0,0 +1,8 @@
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  pool: 5
+  timeout: 5000

data/examples/snippets/stale-reads/db/migrate/01_create_tables.rb

@@ -0,0 +1,21 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+class CreateTables < ActiveRecord::Migration[6.0]
+  def change
+    connection.ddl_batch do
+      create_table :singers do |t|
+        t.string :first_name
+        t.string :last_name
+      end
+
+      create_table :albums do |t|
+        t.string :title
+        t.references :singer, index: false, foreign_key: true
+      end
+    end
+  end
+end

data/examples/snippets/stale-reads/db/schema.rb

@@ -0,0 +1,26 @@
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema.define(version: 1) do
+
+  create_table "albums", id: { limit: 8 }, force: :cascade do |t|
+    t.string "title"
+    t.integer "singer_id", limit: 8
+  end
+
+  create_table "singers", id: { limit: 8 }, force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/stale-reads/db/seeds.rb

@@ -0,0 +1,24 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require_relative "../../config/environment.rb"
+require_relative "../models/singer"
+require_relative "../models/album"
+
+first_names = ["Pete", "Alice", "John", "Ethel", "Trudy", "Naomi", "Wendy", "Ruben", "Thomas", "Elly"]
+last_names = ["Wendelson", "Allison", "Peterson", "Johnson", "Henderson", "Ericsson", "Aronson", "Tennet", "Courtou"]
+
+adjectives = ["daily", "happy", "blue", "generous", "cooked", "bad", "open"]
+nouns = ["windows", "potatoes", "bank", "street", "tree", "glass", "bottle"]
+
+5.times do
+  Singer.create first_name: first_names.sample, last_name: last_names.sample
+end
+
+20.times do
+  singer_id = Singer.all.sample.id
+  Album.create title: "#{adjectives.sample} #{nouns.sample}", singer_id: singer_id
+end

data/examples/snippets/stale-reads/models/album.rb

@@ -0,0 +1,9 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+class Album < ActiveRecord::Base
+  belongs_to :singer
+end

data/examples/snippets/stale-reads/models/singer.rb

@@ -0,0 +1,9 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+class Singer < ActiveRecord::Base
+  has_many :albums
+end

data/lib/active_record/connection_adapters/spanner/database_statements.rb

@@ -27,6 +27,14 @@ module ActiveRecord
             transaction_required = statement_type == :dml
             materialize_transactions
 
+            # First process and remove any hints in the binds that indicate that
+            # a different read staleness should be used than the default.
+            staleness_hint = binds.find { |b| b.is_a? Arel::Visitors::StalenessHint }
+            if staleness_hint
+              selector = Google::Cloud::Spanner::Session.single_use_transaction staleness_hint.value
+              binds.delete staleness_hint
+            end
+
             log sql, name do
               types, params = to_types_and_params binds
               ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
@@ -35,7 +43,7 @@ module ActiveRecord
                     @connection.execute_query sql, params: params, types: types
                   end
                 else
-                  @connection.execute_query sql, params: params, types: types
+                  @connection.execute_query sql, params: params, types: types, single_use_selector: selector
                 end
               end
             end
@@ -149,7 +157,7 @@ module ActiveRecord
         end
 
         # Begins a transaction on the database with the specified isolation level. Cloud Spanner only supports
-        # isolation level :serializable, but also defines two additional 'isolation levels' that can be used
+        # isolation level :serializable, but also defines three additional 'isolation levels' that can be used
         # to start specific types of Spanner transactions:
         # * :read_only: Starts a read-only snapshot transaction using a strong timestamp bound.
         # * :buffered_mutations: Starts a read/write transaction that will use mutations instead of DML for single-row
@@ -158,9 +166,24 @@ module ActiveRecord
         # * :pdml: Starts a Partitioned DML transaction. Executing multiple DML statements in one PDML transaction
         #          block is NOT supported A PDML transaction is not guaranteed to be atomic.
         #          See https://cloud.google.com/spanner/docs/dml-partitioned for more information.
+        #
+        # In addition to the above, a Hash containing read-only snapshot options may be used to start a specific
+        # read-only snapshot:
+        # * { timestamp: Time } Starts a read-only snapshot at the given timestamp.
+        # * { staleness: Integer } Starts a read-only snapshot with the given staleness in seconds.
+        # * { strong: <any value>} Starts a read-only snapshot with strong timestamp bound
+        #                          (this is the same as :read_only)
+        #
         def begin_isolated_db_transaction isolation
-          raise "Unsupported isolation level: #{isolation}" unless \
+          if isolation.is_a? Hash
+            raise "Unsupported isolation level: #{isolation}" unless \
+              isolation[:timestamp] || isolation[:staleness] || isolation[:strong]
+            raise "Only one option is supported. It must be one of `timestamp`, `staleness` or `strong`." \
+              if isolation.count != 1
+          else
+            raise "Unsupported isolation level: #{isolation}" unless \
               [:serializable, :read_only, :buffered_mutations, :pdml].include? isolation
+          end
 
           log "BEGIN #{isolation}" do
             @connection.begin_transaction isolation

data/lib/active_record/connection_adapters/spanner_adapter.rb

@@ -65,7 +65,8 @@ module ActiveRecord
         time:         { name: "TIMESTAMP" },
         date:         { name: "DATE" },
         binary:       { name: "BYTES", limit: "MAX" },
-        boolean:      { name: "BOOL" }
+        boolean:      { name: "BOOL" },
+        json:         { name: "JSON" }
       }.freeze
 
       include Spanner::Quoting
@@ -190,6 +191,7 @@ module ActiveRecord
         m.register_type "INT64", Type::Integer.new(limit: 8)
         register_class_with_limit m, %r{^STRING}i, Type::String
         m.register_type "TIMESTAMP", ActiveRecord::Type::Spanner::Time.new
+        m.register_type "JSON", ActiveRecord::Type::Json.new
 
         register_array_types m
       end
@@ -203,6 +205,7 @@ module ActiveRecord
         m.register_type %r{^ARRAY<INT64>}i, Type::Spanner::Array.new(Type::Integer.new(limit: 8))
         m.register_type %r{^ARRAY<STRING\((MAX|d+)\)>}i, Type::Spanner::Array.new(Type::String.new)
         m.register_type %r{^ARRAY<TIMESTAMP>}i, Type::Spanner::Array.new(ActiveRecord::Type::Spanner::Time.new)
+        m.register_type %r{^ARRAY<JSON>}i, Type::Spanner::Array.new(ActiveRecord::Type::Json.new)
       end
 
       def extract_limit sql_type

data/lib/active_record/type/spanner/spanner_active_record_converter.rb

@@ -23,6 +23,7 @@ module ActiveRecord
           when ActiveModel::Type::Decimal then :NUMERIC
           when ActiveModel::Type::DateTime, ActiveModel::Type::Time, ActiveRecord::Type::Spanner::Time then :TIMESTAMP
           when ActiveModel::Type::Date then :DATE
+          when ActiveRecord::Type::Json then :JSON
           when ActiveRecord::Type::Spanner::Array then [convert_active_model_type_to_spanner(type.element_type)]
           end
         end

data/lib/activerecord_spanner_adapter/connection.rb

@@ -195,7 +195,7 @@ module ActiveRecordSpannerAdapter
 
     # DQL, DML Statements
 
-    def execute_query sql, params: nil, types: nil
+    def execute_query sql, params: nil, types: nil, single_use_selector: nil
       if params
         converted_params, types = \
           Google::Cloud::Spanner::Convert.to_input_params_and_types(
@@ -213,7 +213,7 @@ module ActiveRecordSpannerAdapter
           sql,
           params: converted_params,
           types: types,
-          transaction: transaction_selector,
+          transaction: transaction_selector || single_use_selector,
           seqno: (current_transaction&.next_sequence_number)
       rescue Google::Cloud::AbortedError
         # Mark the current transaction as aborted to prevent any unnecessary further requests on the transaction.

data/lib/activerecord_spanner_adapter/transaction.rb

@@ -11,6 +11,7 @@ module ActiveRecordSpannerAdapter
     def initialize connection, isolation
       @connection = connection
       @isolation = isolation
+      @committable = ![:read_only, :pdml].include?(isolation) && !isolation.is_a?(Hash)
       @state = :INITIALIZED
       @sequence_number = 0
       @mutations = []
@@ -34,6 +35,16 @@ module ActiveRecordSpannerAdapter
       begin
         @grpc_transaction =
           case @isolation
+          when Hash
+            if @isolation[:timestamp]
+              @connection.session.create_snapshot timestamp: @isolation[:timestamp]
+            elsif @isolation[:staleness]
+              @connection.session.create_snapshot staleness: @isolation[:staleness]
+            elsif @isolation[:strong]
+              @connection.session.create_snapshot strong: true
+            else
+              raise "Invalid snapshot argument: #{@isolation}"
+            end
           when :read_only
             @connection.session.create_snapshot strong: true
           when :pdml
@@ -56,15 +67,14 @@ module ActiveRecordSpannerAdapter
     end
 
     def next_sequence_number
-      @sequence_number += 1 unless @isolation == :read_only
+      @sequence_number += 1 if @committable
     end
 
     def commit
       raise "This transaction is not active" unless active?
 
       begin
-        @connection.session.commit_transaction @grpc_transaction, @mutations \
-            unless [:read_only, :pdml].include? @isolation
+        @connection.session.commit_transaction @grpc_transaction, @mutations if @committable
         @state = :COMMITTED
       rescue Google::Cloud::NotFoundError => e
         if @connection.session_not_found? e
@@ -94,7 +104,7 @@ module ActiveRecordSpannerAdapter
     end
 
     def shoot_and_forget_rollback
-      @connection.session.rollback @grpc_transaction.transaction_id unless @isolation == :read_only
+      @connection.session.rollback @grpc_transaction.transaction_id if @committable
     rescue StandardError # rubocop:disable Lint/HandleExceptions
       # Ignored
     end

data/lib/activerecord_spanner_adapter/version.rb

@@ -5,5 +5,5 @@
 # https://opensource.org/licenses/MIT.
 
 module ActiveRecordSpannerAdapter
-  VERSION = "0.5.0".freeze
+  VERSION = "0.6.0".freeze
 end

data/lib/arel/visitors/spanner.rb

@@ -6,10 +6,21 @@
 
 module Arel # :nodoc: all
   module Visitors
+    class StalenessHint
+      attr_reader :value
+
+      def initialize value
+        @value = value
+      end
+    end
+
     class Spanner < Arel::Visitors::ToSql
       def compile node, collector = Arel::Collectors::SQLString.new
-        @index = 0
-        accept(node, collector).value
+        collector.class.module_eval { attr_accessor :hints }
+        collector.hints = {}
+        sql, binds = accept(node, collector).value
+        binds << collector.hints[:staleness] if collector.hints[:staleness]
+        [sql, binds]
       end
 
       private
@@ -22,6 +33,32 @@ module Arel # :nodoc: all
       end
 
       # rubocop:disable Naming/MethodName
+      def visit_Arel_Nodes_OptimizerHints o, collector
+        o.expr.each do |v|
+          if v.start_with? "max_staleness:"
+            collector.hints[:staleness] = \
+              StalenessHint.new max_staleness: v.delete_prefix("max_staleness:").to_f
+            next
+          end
+          if v.start_with? "exact_staleness:"
+            collector.hints[:staleness] = \
+              StalenessHint.new exact_staleness: v.delete_prefix("exact_staleness:").to_f
+            next
+          end
+          if v.start_with? "min_read_timestamp:"
+            time = Time.xmlschema v.delete_prefix("min_read_timestamp:")
+            collector.hints[:staleness] = \
+              StalenessHint.new min_read_timestamp: time
+            next
+          end
+          next unless v.start_with? "read_timestamp:"
+          time = Time.xmlschema v.delete_prefix("read_timestamp:")
+          collector.hints[:staleness] = \
+            StalenessHint.new read_timestamp: time
+        end
+        collector
+      end
+
       def visit_Arel_Nodes_BindParam o, collector
         # Do not generate a query parameter if the value should be set to the PENDING_COMMIT_TIMESTAMP(), as that is
         # not supported as a parameter value by Cloud Spanner.

data/lib/spanner_client_ext.rb

@@ -35,6 +35,27 @@ module Google
           Convert.timestamp_to_time resp.commit_timestamp
         end
 
+        # Create a single-use transaction selector.
+        def self.single_use_transaction opts
+          return nil if opts.nil? || opts.empty?
+
+          exact_timestamp = Convert.time_to_timestamp opts[:read_timestamp]
+          exact_staleness = Convert.number_to_duration opts[:exact_staleness]
+          min_read_timestamp = Convert.time_to_timestamp opts[:min_read_timestamp]
+          max_staleness = Convert.number_to_duration opts[:max_staleness]
+
+          V1::TransactionSelector.new(single_use:
+            V1::TransactionOptions.new(read_only:
+              V1::TransactionOptions::ReadOnly.new({
+                strong: opts[:strong],
+                read_timestamp: exact_timestamp,
+                exact_staleness: exact_staleness,
+                min_read_timestamp: min_read_timestamp,
+                max_staleness: max_staleness,
+                return_read_timestamp: true
+              }.delete_if { |_, v| v.nil? })))
+        end
+
         def create_snapshot strong: nil,
                             timestamp: nil, read_timestamp: nil,
                             staleness: nil, exact_staleness: nil

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-spanner-adapter
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Google LLC
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-08-31 00:00:00.000000000 Z
+date: 2021-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-spanner
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.10'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -275,6 +275,7 @@ files:
 - acceptance/cases/type/date_time_test.rb
 - acceptance/cases/type/float_test.rb
 - acceptance/cases/type/integer_test.rb
+- acceptance/cases/type/json_test.rb
 - acceptance/cases/type/numeric_test.rb
 - acceptance/cases/type/string_test.rb
 - acceptance/cases/type/text_test.rb
@@ -433,6 +434,15 @@ files:
 - examples/snippets/read-write-transactions/db/seeds.rb
 - examples/snippets/read-write-transactions/models/album.rb
 - examples/snippets/read-write-transactions/models/singer.rb
+- examples/snippets/stale-reads/README.md
+- examples/snippets/stale-reads/Rakefile
+- examples/snippets/stale-reads/application.rb
+- examples/snippets/stale-reads/config/database.yml
+- examples/snippets/stale-reads/db/migrate/01_create_tables.rb
+- examples/snippets/stale-reads/db/schema.rb
+- examples/snippets/stale-reads/db/seeds.rb
+- examples/snippets/stale-reads/models/album.rb
+- examples/snippets/stale-reads/models/singer.rb
 - examples/snippets/timestamp-data-type/README.md
 - examples/snippets/timestamp-data-type/Rakefile
 - examples/snippets/timestamp-data-type/application.rb