activerecord-spanner-adapter 0.3.0 → 1.0.0

data/examples/snippets/mutations/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 using Mutations instead of DML with ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[mutations]" }
+end

data/examples/snippets/mutations/application.rb

@@ -0,0 +1,47 @@
+# 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
+    # This transaction uses Mutations instead of DML. That means that any data changes are not readable during
+    # the transaction itself, as the mutations are buffered locally in the client and only sent to Spanner
+    # when the transaction is committed.
+    ActiveRecord::Base.transaction isolation: :buffered_mutations 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
+
+      # The above change is not sent to the database before the transaction is committed.
+      puts ""
+      puts "Budgets before commit:"
+      puts "Marketing budget #{from_album.title}: #{from_album.reload.marketing_budget}"
+      puts "Marketing budget #{to_album.title}: #{to_album.reload.marketing_budget}"
+    end
+    puts ""
+    puts "Budgets after commit:"
+    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/mutations/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/mutations/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/mutations/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/mutations/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/mutations/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/mutations/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/optimistic-locking/README.md

@@ -0,0 +1,12 @@
+# Sample - Optimistic Locking
+
+This example shows how to use optimistic locking with 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/optimistic-locking/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 use optimistic locking with the Cloud Spanner ActiveRecord adapter."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[optimistic-locking]" }
+end

data/examples/snippets/optimistic-locking/application.rb

@@ -0,0 +1,48 @@
+# 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
+    # Get a random singer and then update the singer in a separate thread.
+    # This simulates a concurrent update of the same record by two different processes.
+    singer = Singer.all.sample
+
+    puts ""
+    puts "Singer #{singer.first_name} #{singer.last_name} with version #{singer.lock_version} loaded"
+
+    t = Thread.new do
+      # Load the singer in the separate thread into a separate variable.
+      singer2 = Singer.find singer.id
+      singer2.update last_name: "Rashford"
+      puts ""
+      puts "Updated the last name of the singer to #{singer2.last_name}"
+    end
+    t.join
+
+    # Now try to update the singer in the main thread. This will fail, as the lock_version number has been increased
+    # by the update in the separate thread.
+    begin
+      singer.update last_name: "Drake"
+    rescue ActiveRecord::StaleObjectError
+      puts ""
+      puts "Updating the singer in the main thread failed with a StaleObjectError"
+    end
+
+    singer.reload
+    puts "Reloaded singer data: #{singer.first_name} #{singer.last_name}, version: #{singer.lock_version}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/optimistic-locking/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/optimistic-locking/db/migrate/01_create_tables.rb

@@ -0,0 +1,26 @@
+# 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
+        # `lock_version` is the default name for an optimistic lock version column in ActiveRecord.
+        t.integer :lock_version
+      end
+
+      create_table :albums do |t|
+        t.string :title
+        t.numeric :marketing_budget
+        t.references :singer, index: false, foreign_key: true
+        # `lock_version` is the default name for an optimistic lock version column in ActiveRecord.
+        t.integer :lock_version
+      end
+    end
+  end
+end

data/examples/snippets/optimistic-locking/db/schema.rb

@@ -0,0 +1,29 @@
+# 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
+    t.integer "lock_version", limit: 8
+  end
+
+  create_table "singers", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+    t.integer "lock_version", limit: 8
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/optimistic-locking/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/optimistic-locking/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/optimistic-locking/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/partitioned-dml/README.md

@@ -0,0 +1,16 @@
+# Sample - Partitioned DML
+
+This example shows how to use Partitioned DML with the Spanner ActiveRecord adapter.
+
+See https://cloud.google.com/spanner/docs/dml-partitioned for more information on Partitioned DML.
+
+## Running the Sample
+
+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/partitioned-dml/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 work with Partitioned DML in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[partitioned-dml]" }
+end

data/examples/snippets/partitioned-dml/application.rb

@@ -0,0 +1,48 @@
+# 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
+    singer_count = Singer.all.count
+    album_count = Album.all.count
+    puts ""
+    puts "Singers in the database: #{singer_count}"
+    puts "Albums in the database: #{album_count}"
+
+    puts ""
+    puts "Deleting all albums in the database using Partitioned DML"
+    # Note that a Partitioned DML transaction can contain ONLY ONE DML statement.
+    # If we want to delete all data in two different tables, we need to do so in two different PDML transactions.
+    Album.transaction isolation: :pdml do
+      count = Album.delete_all
+      puts "Deleted #{count} albums"
+    end
+
+    puts ""
+    puts "Deleting all singers in the database using Partitioned DML"
+    Singer.transaction isolation: :pdml do
+      count = Singer.delete_all
+      puts "Deleted #{count} singers"
+    end
+
+    singer_count = Singer.all.count
+    album_count = Album.all.count
+    puts ""
+    puts "Singers in the database: #{singer_count}"
+    puts "Albums in the database: #{album_count}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/partitioned-dml/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/partitioned-dml/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, limit: 100
+        t.string :last_name, limit: 200, null: false
+      end
+
+      create_table :albums do |t|
+        t.string :title
+        t.references :singer, index: false, foreign_key: true
+      end
+    end
+  end
+end

data/examples/snippets/partitioned-dml/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", limit: 100
+    t.string "last_name", limit: 200, null: false
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/partitioned-dml/db/seeds.rb

@@ -0,0 +1,29 @@
+# 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 = %w[Pete Alice John Ethel Trudy Naomi Wendy Ruben Thomas Elly]
+last_names = %w[Wendelson Allison Peterson Johnson Henderson Ericsson Aronson Tennet Courtou]
+
+adjectives = %w[daily happy blue generous cooked bad open]
+nouns = %w[windows potatoes bank street tree glass bottle]
+
+# This ensures all the records are inserted using one read/write transaction that will use mutations instead of DML.
+ActiveRecord::Base.transaction isolation: :buffered_mutations do
+  singers = []
+  5.times do
+    singers << Singer.create(first_name: first_names.sample, last_name: last_names.sample)
+  end
+
+  albums = []
+  20.times do
+    singer = singers.sample
+    albums << Album.create(title: "#{adjectives.sample} #{nouns.sample}", singer: singer)
+  end
+end

data/examples/snippets/partitioned-dml/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/partitioned-dml/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/quickstart/README.md

@@ -0,0 +1,26 @@
+# Sample - Quickstart
+
+This sample shows how to create and use a very simple Cloud Spanner database with ActiveRecord.
+The database consists of two tables:
+- Singers
+- Albums
+
+Albums references Singers with a [foreign key](https://cloud.google.com/spanner/docs/foreign-keys/overview).
+
+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.
+
+This sample will:
+1. Create the sample database by calling `rake db:migrate`. This will execute the migrations in the folder `db/migrate`.
+2. Fill the sample database with some data by calling `rake db:seed`. This will execute the script in `db/seeds.rb`.
+The seed script fills the database with 10 random singers and 30 random albums.
+3. Run the `application.rb` file. This application will:
+   1. List all known singers and albums.
+   2. Select a random singer and update the name of this singer.
+   3. Select all singers whose last names start with an 'A'.
+
+Run the application with the command
+
+```bash
+bundle exec rake run
+```

data/examples/snippets/quickstart/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 "Runs a simple ActiveRecord tutorial application on a Spanner emulator."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[quickstart]" }
+end

data/examples/snippets/quickstart/application.rb

@@ -0,0 +1,51 @@
+# 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
+    # Fetch all singers and albums from the database. The database has been pre-filled by the `db/seeds.rb` script.
+    puts "Known singers and their albums:"
+    puts ""
+    Singer.all.each do |singer|
+      puts "#{singer.first_name} #{singer.last_name}"
+      singer.albums.each do |album|
+        puts "   #{album.title}"
+      end
+    end
+
+    # Select a random singer and update the name of this singer.
+    puts ""
+    singer = Singer.all.sample
+    puts "Current name of singer #{singer.id} is '#{singer.first_name} #{singer.last_name}'"
+    puts "Updating name to 'Dave Anderson'"
+    singer.first_name = "Dave"
+    singer.last_name = "Anderson"
+    singer.save!
+    singer.reload
+    puts "New name of singer #{singer.id}: #{singer.first_name} #{singer.last_name}"
+
+    # Select all singers whose last name start with 'A'. This should include at least the singer that was updated
+    # in the previous step, but probably also a number of other singers.
+    puts ""
+    puts "Getting all singers with a last name that starts with 'A'"
+
+    last_name = Singer.arel_table["last_name"]
+    Singer.where(last_name.matches("A%")).each do |s|
+      puts "#{s.first_name} #{s.last_name}"
+    end
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/quickstart/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