activerecord-spanner-adapter 0.3.0 → 0.5.0

data/examples/snippets/interleaved-tables/db/schema.rb

@@ -0,0 +1,32 @@
+# 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", primary_key: "albumid", force: :cascade do |t|
+    t.integer "singerid", limit: 8, null: false
+    t.string "title"
+  end
+
+  create_table "singers", primary_key: "singerid", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  create_table "tracks", primary_key: "trackid", force: :cascade do |t|
+    t.integer "singerid", limit: 8, null: false
+    t.integer "albumid", limit: 8, null: false
+    t.string "title"
+    t.decimal "duration"
+  end
+
+end

data/examples/snippets/interleaved-tables/db/seeds.rb

@@ -0,0 +1,40 @@
+# 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"
+require_relative "../models/track"
+
+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]
+
+verbs = %w[operate waste package chew yield express polish stress slip want cough campaign cultivate report park refer]
+adverbs = %w[directly right hopefully personally economically privately supposedly consequently fully later urgently]
+
+durations = [3.14, 5.4, 3.3, 4.1, 5.0, 3.2, 3.0, 3.5, 4.0, 4.5, 5.5, 6.0]
+
+# 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
+
+  200.times do
+    album = albums.sample
+    Track.create title: "#{verbs.sample} #{adverbs.sample}", duration: durations.sample, album: album
+  end
+end

data/examples/snippets/interleaved-tables/models/album.rb

@@ -0,0 +1,15 @@
+# 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
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`. The primary key of `singers` is `singerid`.
+  belongs_to :singer, foreign_key: "singerid"
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`. The primary key of `albums` is (`singerid`, `albumid`), but
+  # only `albumid` is used by ActiveRecord as the primary key. The `singerid` column is defined as a `parent_key` of
+  # `albums` (see also the `db/migrate/01_create_tables.rb` file).
+  has_many :tracks, foreign_key: "albumid"
+end

data/examples/snippets/interleaved-tables/models/singer.rb

@@ -0,0 +1,20 @@
+# 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
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`. The primary key of `albums` is (`singerid`, `albumid`), but
+  # only `albumid` is used by ActiveRecord as the primary key. The `singerid` column is defined as a `parent_key` of
+  # `albums` (see also the `db/migrate/01_create_tables.rb` file).
+  has_many :albums, foreign_key: "singerid"
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`. The primary key of `tracks` is
+  # (`singerid`, `albumid`, `trackid`), but only `trackid` is used by ActiveRecord as the primary key. The `singerid`
+  # and `albumid` columns are defined as `parent_key` of `tracks` (see also the `db/migrate/01_create_tables.rb` file).
+  # The `singerid` column can therefore be used to associate tracks with a singer without the need to go through albums.
+  # Note also that the inclusion of `singerid` as a column in `tracks` is required in order to make `tracks` a child
+  # table of `albums` which has primary key (`singerid`, `albumid`).
+  has_many :tracks, foreign_key: "singerid"
+end

data/examples/snippets/interleaved-tables/models/track.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.
+
+class Track < ActiveRecord::Base
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`. The primary key of `albums` is ()`singerid`, `albumid`).
+  belongs_to :album, foreign_key: "albumid"
+
+  # `tracks` also has a `singerid` column should be used to associate a Track with a Singer.
+  belongs_to :singer, foreign_key: "singerid"
+
+  # Override the default initialize method to automatically set the singer attribute when an album is given.
+  def initialize attributes = nil
+    super
+    self.singer ||= album&.singer
+  end
+
+  def album=value
+    super
+    # Ensure the singer of this track is equal to the singer of the album that is set.
+    self.singer = value&.singer
+  end
+end

data/examples/snippets/migrations/README.md

@@ -0,0 +1,43 @@
+# Sample - Migrations
+
+This example shows the best way to execute migrations with the Spanner ActiveRecord adapter.
+
+It is [strongly recommended](https://cloud.google.com/spanner/docs/schema-updates#best-practices) that you limit the
+frequency of schema updates in Cloud Spanner, and that schema changes are batched together whenever possible. The
+Spanner ActiveRecord adapter supports batching DDL statements together using the `connection.ddl_batch` method. This
+method accepts a block of DDL statements that will be sent to Cloud Spanner as one batch. It is recommended that
+migrations are grouped together in one or in a limited number of batches for optimal performance.
+
+This example shows how to create three tables in one batch:
+
+```ruby
+# Execute the entire migration as one DDL batch.
+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 :singers
+  end
+
+  create_table :tracks do |t|
+    t.string :title
+    t.numeric :duration
+    t.references :albums
+  end
+end
+```
+
+## 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/migrations/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 the best practice for executing migrations (schema updates) on Cloud Spanner in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[migrations]" }
+end

data/examples/snippets/migrations/application.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.
+
+require "io/console"
+require_relative "../config/environment"
+
+class Application
+  def self.run
+    puts ""
+    puts "Created database with the following tables:"
+    sql = "SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_CATALOG='' AND TABLE_SCHEMA=''"
+    tables = ActiveRecord::Base.connection.raw_connection.execute_query sql
+    tables.rows.each do |row|
+      puts row[:TABLE_NAME]
+    end
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

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

@@ -0,0 +1,28 @@
+# 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
+    # Execute the entire migration as one DDL batch.
+    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 :singers
+      end
+
+      create_table :tracks do |t|
+        t.string :title
+        t.numeric :duration
+        t.references :albums
+      end
+    end
+  end
+end

data/examples/snippets/migrations/db/schema.rb

@@ -0,0 +1,33 @@
+# 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 "singers_id", limit: 8
+    t.index ["singers_id"], name: "index_albums_on_singers_id", order: { singers_id: :asc }
+  end
+
+  create_table "singers", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  create_table "tracks", force: :cascade do |t|
+    t.string "title"
+    t.decimal "duration"
+    t.integer "albums_id", limit: 8
+    t.index ["albums_id"], name: "index_tracks_on_albums_id", order: { albums_id: :asc }
+  end
+
+end

data/examples/snippets/migrations/db/seeds.rb

@@ -0,0 +1,5 @@
+# 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.

data/examples/snippets/migrations/models/album.rb

@@ -0,0 +1,10 @@
+# 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
+  has_many :tracks
+end

data/examples/snippets/migrations/models/singer.rb

@@ -0,0 +1,10 @@
+# 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
+  has_many :tracks, through: :albums
+end

data/examples/snippets/migrations/models/track.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 Track < ActiveRecord::Base
+  belongs_to :album
+end

data/examples/snippets/mutations/README.md

@@ -0,0 +1,34 @@
+# Sample - Mutations
+
+Writing data to a Cloud Spanner database can be done using two different features:
+* Data Modification Language (DML)
+* Mutations
+
+Changes that are written using DML can be read back during the same read/write transaction. Changes that are
+written using Mutations are however buffered locally in the client and only sent to Cloud Spanner when the
+transaction is committed. Mutations are therefore not readable during the same read/write transaction. The
+Spanner ActiveRecord adapter will use DML by default when modifications are made during a read/write transaction.
+Mutations can however be executed more efficiently by Cloud Spanner, which can significantly reduce the execution
+time for read/write transactions that modify a large number of records. The Spanner ActiveRecord adapter will
+therefore use Mutations in the following cases:
+
+1. No explicit transaction block: When entities are modified outside of an explicit transaction block, ActiveRecord
+   will automatically create an implicit transaction and save the data to the database. This means that the data can
+   never be read back during the same transaction. The Spanner ActiveRecord adapter recognizes this situation and
+   automatically switches to using Mutations for these transactions to optimize the execution speed.
+2. Using a custom isolation level: The Spanner ActiveRecord adapter supports the custom isolation level
+   `:buffered_mutations` that will instruct the underlying Spanner transaction to use Mutations instead
+   of DML for all data operations in the transaction that can be executed using Mutations. Transactions with this
+   isolation level do not support read-your-writes.
+   
+This sample shows how to use the `:buffered_mutations` isolation level to instruct the Spanner ActiveRecord
+adapter to use mutations instead of DML during a 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/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