activerecord-spanner-adapter 0.1.0 → 0.7.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/interleaved-tables/README.md

@@ -0,0 +1,152 @@
+# Sample - Interleaved Tables
+
+This example shows how to use interleaved tables with the Spanner ActiveRecord adapter.
+
+See https://cloud.google.com/spanner/docs/schema-and-data-model#creating-interleaved-tables for more information
+on interleaved tables if you are not familiar with this concept.
+
+## Creating Interleaved Tables in ActiveRecord
+You can create interleaved tables using migrations in ActiveRecord by using the following Spanner ActiveRecord specific
+methods that are defined on `TableDefinition`:
+* `interleave_in`: Specifies which parent table a child table should be interleaved in and optionally whether
+  deletes of a parent record should automatically cascade delete all child records. 
+* `parent_key`: Creates a column that is a reference to (a part of) the primary key of the parent table. Each child
+  table must include all the primary key columns of the parent table as a `parent_key`.
+  
+Cloud Spanner requires a child table to include the exact same primary key columns as the parent table in addition to
+the primary key column(s) of the child table. This means that the default `id` primary key column of ActiveRecord is
+not usable in combination with interleaved tables. Instead each primary key column should be prefixed with the table
+name of the table that it references, or use some other unique name.
+
+This example uses the following table schema:
+
+```sql
+CREATE TABLE singers (
+    singerid INT64 NOT NULL,
+    first_name STRING(MAX),
+    last_name STRING(MAX)
+) PRIMARY KEY (singerid);
+
+CREATE TABLE albums (
+    albumid INT64 NOT NULL,
+    singerid INT64 NOT NULL,
+    title STRING(MAX)
+) PRIMARY KEY (singerid, albumid), INTERLEAVE IN PARENT singers;
+
+CREATE TABLE tracks (
+    trackid INT64 NOT NULL,
+    singerid INT64 NOT NULL,
+    albumid INT64 NOT NULL,
+    title STRING(MAX),
+    duration NUMERIC
+) PRIMARY KEY (singerid, albumid, trackid), INTERLEAVE IN PARENT albums ON DELETE CASCADE;
+```
+
+This schema can be created in ActiveRecord as follows:
+
+```ruby
+create_table :singers, id: false do |t|
+    # Explicitly define the primary key with a custom name to prevent all primary key columns from being named `id`.
+    t.primary_key :singerid
+    t.string :first_name
+    t.string :last_name
+end
+
+create_table :albums, id: false do |t|
+    # Interleave the `albums` table in the parent table `singers`.
+    t.interleave_in :singers
+    t.primary_key :albumid
+    # `singerid` is defined as a `parent_key` which makes it a part of the primary key in the table definition, but
+    # it is not presented to ActiveRecord as part of the primary key, to prevent ActiveRecord from considering this
+    # to be an entity with a composite primary key (which is not supported by ActiveRecord).
+    t.parent_key :singerid
+    t.string :title
+end
+
+create_table :tracks, id: false do |t|
+    # Interleave the `tracks` table in the parent table `albums` and cascade delete all tracks that belong to an
+    # album when an album is deleted.
+    t.interleave_in :albums, :cascade
+    # `trackid` is considered the only primary key column by ActiveRecord.
+    t.primary_key :trackid
+    # `singerid` and `albumid` form the parent key of `tracks`. These are part of the primary key definition in the
+    # database, but are presented as parent keys to ActiveRecord.
+    t.parent_key :singerid
+    t.parent_key :albumid
+    t.string :title
+    t.numeric :duration
+end
+```
+
+## Models for Interleaved Tables
+An interleaved table parent/child relationship must be modelled as a `belongs_to`/`has_many` association in
+ActiveRecord. As the columns that are used to reference a parent record use a custom column name, it is required to also
+include the custom column name in the `belongs_to` and `has_many` definitions.
+
+Instances of these models can be used in the same way as any other association in ActiveRecord, but with a couple of
+inherent limitations:
+* It is not possible to change the parent record of a child record. For instance, changing the singer of an album in the
+  above example is impossible, as Cloud Spanner does not allow such an update.
+* It is not possible to de-reference a parent record by setting it to null.
+* It is only possible to delete a parent record with existing child records, if the child records are also deleted. This
+  can be done by enabling ON DELETE CASCADE in Cloud Spanner, or by deleting the child records using ActiveRecord.
+
+### Example Models
+
+```ruby
+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
+
+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
+
+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
+```
+
+## 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/interleaved-tables/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 interleaved tables in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[interleaved-tables]" }
+end