activerecord-spanner-adapter 0.3.0 → 1.0.0

data/examples/snippets/date-data-type/db/schema.rb

@@ -0,0 +1,21 @@
+# 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 "singers", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+    t.date "birth_date"
+  end
+
+end

data/examples/snippets/date-data-type/db/seeds.rb

@@ -0,0 +1,16 @@
+# 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"
+
+first_names = %w[Nelson Todd William Alex Dominique Adenoid Steve Nathan Beverly Annie Amy Norma Diana Regan Phyllis]
+last_names = %w[Thornton Morgan Lawson Collins Frost Maxwell Sanders Fleming Jones Webb Walker French Montgomery Quinn]
+
+30.times do
+  Singer.create first_name: first_names.sample, last_name: last_names.sample,
+                birth_date: Date.new(rand(1920...2010), rand(1...12), rand(1...28))
+end

data/examples/snippets/date-data-type/models/singer.rb

@@ -0,0 +1,8 @@
+# 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
+end

data/examples/snippets/generated-column/README.md

@@ -0,0 +1,41 @@
+# Sample - Generated Columns
+
+This example shows how to use generated columns with the Spanner ActiveRecord adapter.
+
+See https://cloud.google.com/spanner/docs/generated-column/how-to for more information on generated columns.
+
+This example uses the following table schema:
+
+```sql
+CREATE TABLE singers (
+    id         INT64 NOT NULL,
+    first_name STRING(100),
+    last_name  STRING(200) NOT NULL,
+    full_name  STRING(300) NOT NULL AS (COALESCE(first_name || ' ', '') || last_name) STORED,
+) PRIMARY KEY (id);
+```
+
+This schema can be created in ActiveRecord as follows:
+
+```ruby
+create_table :singers do |t|
+  t.string :first_name, limit: 100
+  t.string :last_name, limit: 200, null: false
+  t.string :full_name, limit: 300, null: false, as: "COALESCE(first_name || ' ', '') || last_name", stored: true
+end
+```
+
+The `full_name` attribute will automatically be set by Cloud Spanner, and it is not allowed to set a value for the
+attribute when creating a record in ActiveRecord, or to update the value of an existing record. Instead, only the
+`first_name` and `last_name` attributes should be set.
+
+## 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/generated-column/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 generated columns in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[generated-column]" }
+end

data/examples/snippets/generated-column/application.rb

@@ -0,0 +1,37 @@
+# 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"
+
+class Application
+  def self.run
+    puts ""
+    puts "Listing all singers:"
+    Singer.all.order("last_name, first_name").each do |singer|
+      puts singer.full_name
+    end
+
+    # Create a new singer and print out the full name.
+    singer = Singer.create first_name: "Alice", last_name: "Rees"
+    singer.reload
+    puts ""
+    puts "Singer created: #{singer.full_name}"
+
+    # Update the last name of the singer and print out the full name.
+    singer.update last_name: "Rees-Goodwin"
+    singer.reload
+    puts ""
+    puts "Singer updated: #{singer.full_name}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

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

@@ -0,0 +1,23 @@
+# 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
+
+        # Create a generated column that contains the full name of the singer. This will be the concatenated first name
+        # and last name of the singer, or only the last name if the first name is null. The `as` keyword is what
+        # instructs the Spanner ActiveRecord adapter to create a generated column. Note the `stored` option that is set
+        # to true. This is required, as Cloud Spanner (currently) does not support non-stored generated columns.
+        # See also https://cloud.google.com/spanner/docs/generated-column/how-to for more information.
+        t.string :full_name, limit: 300, null: false, as: "COALESCE(first_name || ' ', '') || last_name", stored: true
+      end
+    end
+  end
+end

data/examples/snippets/generated-column/db/schema.rb

@@ -0,0 +1,21 @@
+# 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 "singers", id: { limit: 8 }, force: :cascade do |t|
+    t.string "first_name", limit: 100
+    t.string "last_name", limit: 200, null: false
+    t.string "full_name", limit: 300, null: false
+  end
+
+end

data/examples/snippets/generated-column/db/seeds.rb

@@ -0,0 +1,18 @@
+# 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"
+
+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]
+
+# 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
+  10.times do
+    Singer.create first_name: first_names.sample, last_name: last_names.sample
+  end
+end

data/examples/snippets/generated-column/models/singer.rb

@@ -0,0 +1,8 @@
+# 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
+end

data/examples/snippets/hints/README.md

@@ -0,0 +1,19 @@
+# Sample - Query Hints
+
+This example shows how to use query hints Spanner ActiveRecord adapter. Statement hints and
+table hints can be specified using the optimizer_hints method. Join hints must be specified
+in a join string.
+
+See https://cloud.google.com/spanner/docs/query-syntax#sql_syntax for more information on
+the supported query hints.
+
+## 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/hints/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 generated columns in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[hints]" }
+end

data/examples/snippets/hints/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
+    puts ""
+    puts "Listing all singers using additional parallelism:"
+    # A statement hint must be prefixed with 'statement_hint:'
+    Singer.optimizer_hints("statement_hint: @{USE_ADDITIONAL_PARALLELISM=TRUE}")
+          .order("last_name, first_name").each do |singer|
+      puts singer.full_name
+    end
+
+    puts ""
+    puts "Listing all singers using the index on full_name:"
+    # All table hints must be prefixed with 'table_hint:'.
+    # Queries may contain multiple table hints.
+    Singer.optimizer_hints("table_hint: singers@{FORCE_INDEX=index_singers_on_full_name}")
+          .order("full_name").each do |singer|
+      puts singer.full_name
+    end
+
+    puts ""
+    puts "Listing all singers with at least one album that starts with 'blue':"
+    # Join hints cannot be specified using an optimizer_hint. Instead, the join can
+    # be specified using a string that includes the join hint.
+    Singer.joins("INNER JOIN @{JOIN_METHOD=HASH_JOIN} albums " \
+                 "on singers.id=albums.singer_id AND albums.title LIKE 'blue%'")
+          .distinct.order("last_name, first_name").each do |singer|
+      puts singer.full_name
+    end
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

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

@@ -0,0 +1,23 @@
+# 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
+        t.string :full_name, limit: 300, null: false, as: "COALESCE(first_name || ' ', '') || last_name", stored: true
+        t.index [:full_name], name: "index_singers_on_full_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/hints/db/schema.rb

@@ -0,0 +1,28 @@
+# 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
+    t.string "full_name", limit: 300, null: false
+    t.index ["full_name"], name: "index_singers_on_full_name", order: { full_name: :asc }
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/hints/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/hints/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/hints/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/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
+```