activerecord-spanner-adapter 0.3.0 → 1.0.0

data/examples/snippets/quickstart/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/quickstart/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 `rails
+# db:schema:load`. When creating a new database, `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", force: :cascade do |t|
+    t.string "title"
+    t.integer "singer_id", limit: 8
+  end
+
+  create_table "singers", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/quickstart/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"]
+last_names = ["Wendelson", "Allison", "Peterson", "Johnson", "Henderson", "Ericsson", "Aronson"]
+
+adjectives = ["daily", "happy", "blue", "generous", "cooked", "bad", "open"]
+nouns = ["windows", "potatoes", "bank", "street", "tree", "glass", "bottle"]
+
+10.times do
+  Singer.create first_name: first_names.sample, last_name: last_names.sample
+end
+
+30.times do
+  singer_id = Singer.all.sample.id
+  Album.create title: "#{adjectives.sample} #{nouns.sample}", singer_id: singer_id
+end

data/examples/snippets/quickstart/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/quickstart/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/examples/snippets/read-only-transactions/README.md

@@ -0,0 +1,13 @@
+# Sample - Read-only transactions
+
+In addition to locking read-write transactions, Cloud Spanner offers read-only transactions.
+Use a read-only transaction when you need to execute more than one read at the same timestamp.
+
+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/read-only-transactions/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 a read-only transaction on Spanner with ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[read-only-transactions]" }
+end

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

@@ -0,0 +1,77 @@
+# 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, 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.
+    album1 = nil
+    album2 = nil
+    ActiveRecord::Base.transaction isolation: :read_only do
+      # Read two random titles.
+      album1 = Album.all.sample
+      album2 = Album.where.not(id: album1.id).sample
+      puts ""
+      puts "Album title 1: #{album1.title}"
+      puts "Album title 2: #{album2.title}"
+
+      # Update the title of one of the albums in a separate transaction.
+      puts ""
+      puts "Updating the title of #{album1.title} in a separate transaction"
+      t = Thread.new { album1.update title: "New title" }
+      t.join
+
+      puts ""
+      puts "Reloading the albums in the read-only transaction. The updated title is not visible."
+      puts "Album title 1: #{album1.reload.title}"
+      puts "Album title 2: #{album2.reload.title}"
+    end
+    puts ""
+    puts "Reloading the albums **AFTER** the read-only transaction. The updated title is now visible."
+    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
+  end
+end
+
+Application.run

data/examples/snippets/read-only-transactions/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/read-only-transactions/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/read-only-transactions/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/read-only-transactions/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/read-only-transactions/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/read-only-transactions/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/examples/snippets/read-write-transactions/README.md

@@ -0,0 +1,12 @@
+# Sample - Read/Write transactions
+
+This example shows how to use read/write transactions using the Spanner ActiveRecord adapter.
+
+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/read-write-transactions/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 a read/write transaction on Spanner with ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[read-write-transactions]" }
+end

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

@@ -0,0 +1,39 @@
+# 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
+    from_album = nil
+    to_album = nil
+    # Use a read/write transaction to execute multiple statements as an atomic unit.
+    ActiveRecord::Base.transaction do
+      # Transfer a marketing budget of 10,000 from one album to another.
+      from_album = Album.all.sample
+      to_album = Album.where.not(id: from_album.id).sample
+
+      puts ""
+      puts "Transferring 10,000 marketing budget from #{from_album.title} (#{from_album.marketing_budget}) "\
+           "to #{to_album.title} (#{to_album.marketing_budget})"
+      from_album.update marketing_budget: from_album.marketing_budget - 10000
+      to_album.update marketing_budget: to_album.marketing_budget + 10000
+    end
+    puts ""
+    puts "Budgets after update:"
+    puts "Marketing budget #{from_album.title}: #{from_album.reload.marketing_budget}"
+    puts "Marketing budget #{to_album.title}: #{to_album.reload.marketing_budget}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/read-write-transactions/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/read-write-transactions/db/migrate/01_create_tables.rb

@@ -0,0 +1,22 @@
+# 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.numeric :marketing_budget
+        t.references :singer, index: false, foreign_key: true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# 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 `rails
+# db:schema:load`. When creating a new database, `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", force: :cascade do |t|
+    t.string "title"
+    t.decimal "marketing_budget"
+    t.integer "singer_id", limit: 8
+  end
+
+  create_table "singers", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/read-write-transactions/db/seeds.rb

@@ -0,0 +1,25 @@
+# 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"]
+budgets = [15000, 25000, 10000, 20000, 30000, 12000, 13000]
+
+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}", marketing_budget: budgets.sample, singer_id: singer_id
+end

data/examples/snippets/read-write-transactions/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/read-write-transactions/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/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