activerecord-spanner-adapter 1.0.0 → 1.2.0

data/acceptance/cases/models/insert_all_test.rb

@@ -0,0 +1,150 @@
+# Copyright 2022 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.
+
+# frozen_string_literal: true
+
+require "test_helper"
+require "models/author"
+
+module ActiveRecord
+  module Model
+    class InsertAllTest < SpannerAdapter::TestCase
+      include SpannerAdapter::Associations::TestHelper
+
+      def setup
+        super
+      end
+
+      def teardown
+        super
+        Author.destroy_all
+      end
+
+      def test_insert_all
+        values = [
+          { id: Author.next_sequence_value, name: "Alice" },
+          { id: Author.next_sequence_value, name: "Bob" },
+          { id: Author.next_sequence_value, name: "Carol" },
+        ]
+
+        assert_raise(NotImplementedError) { Author.insert_all(values) }
+      end
+
+      def test_insert_all!
+        values = [
+          { id: Author.next_sequence_value, name: "Alice" },
+          { id: Author.next_sequence_value, name: "Bob" },
+          { id: Author.next_sequence_value, name: "Carol" },
+        ]
+
+        Author.insert_all!(values)
+
+        authors = Author.all.order(:name)
+
+        assert_equal "Alice", authors[0].name
+        assert_equal "Bob", authors[1].name
+        assert_equal "Carol", authors[2].name
+      end
+
+      def test_insert_all_with_transaction
+        values = [
+          { id: Author.next_sequence_value, name: "Alice" },
+          { id: Author.next_sequence_value, name: "Bob" },
+          { id: Author.next_sequence_value, name: "Carol" },
+        ]
+
+        ActiveRecord::Base.transaction do
+          Author.insert_all!(values)
+        end
+
+        authors = Author.all.order(:name)
+
+        assert_equal "Alice", authors[0].name
+        assert_equal "Bob", authors[1].name
+        assert_equal "Carol", authors[2].name
+      end
+
+      def test_insert_all_with_buffered_mutation_transaction
+        values = [
+          { id: Author.next_sequence_value, name: "Alice" },
+          { id: Author.next_sequence_value, name: "Bob" },
+          { id: Author.next_sequence_value, name: "Carol" },
+        ]
+
+        ActiveRecord::Base.transaction isolation: :buffered_mutations do
+          Author.insert_all!(values)
+        end
+
+        authors = Author.all.order(:name)
+
+        assert_equal "Alice", authors[0].name
+        assert_equal "Bob", authors[1].name
+        assert_equal "Carol", authors[2].name
+      end
+
+      def test_upsert_all
+        Author.create id: 1, name: "David"
+        authors = Author.all.order(:name)
+        assert_equal 1, authors.length
+        assert_equal "David", authors[0].name
+
+        values = [
+          { id: 1, name: "Alice" },
+          { id: 2, name: "Bob" },
+          { id: 3, name: "Carol" },
+        ]
+
+        Author.upsert_all(values)
+
+        authors = Author.all.order(:name)
+
+        assert_equal 3, authors.length
+        assert_equal "Alice", authors[0].name
+        assert_equal "Bob", authors[1].name
+        assert_equal "Carol", authors[2].name
+      end
+
+      def test_upsert_all_with_transaction
+        values = [
+          { id: Author.next_sequence_value, name: "Alice" },
+          { id: Author.next_sequence_value, name: "Bob" },
+          { id: Author.next_sequence_value, name: "Carol" },
+        ]
+
+        err = assert_raise(NotImplementedError) do
+          ActiveRecord::Base.transaction do
+            Author.upsert_all(values)
+          end
+        end
+        assert_match "Use upsert outside a transaction block", err.message
+      end
+
+      def test_upsert_all_with_buffered_mutation_transaction
+        Author.create id: 1, name: "David"
+        authors = Author.all.order(:name)
+        assert_equal 1, authors.length
+        assert_equal "David", authors[0].name
+
+        values = [
+          { id: 1, name: "Alice" },
+          { id: 2, name: "Bob" },
+          { id: 3, name: "Carol" },
+        ]
+
+        ActiveRecord::Base.transaction isolation: :buffered_mutations do
+          Author.upsert_all(values)
+        end
+
+        authors = Author.all.order(:name)
+
+        assert_equal 3, authors.length
+        assert_equal "Alice", authors[0].name
+        assert_equal "Bob", authors[1].name
+        assert_equal "Carol", authors[2].name
+      end
+    end
+  end
+end

data/acceptance/cases/transactions/optimistic_locking_test.rb

@@ -19,6 +19,9 @@ module ActiveRecord
       def setup
         super
 
+        @original_verbosity = $VERBOSE
+        $VERBOSE = nil
+
         singer = Singer.create first_name: "Pete", last_name: "Allison"
         album = Album.create title: "Musical Jeans", singer: singer
         Track.create title: "Increased Headline", album: album, singer: singer
@@ -30,6 +33,8 @@ module ActiveRecord
         Track.delete_all
         Album.delete_all
         Singer.delete_all
+
+        $VERBOSE = @original_verbosity
       end
 
       # Runs the given block in a transaction with the given isolation level, or without a transaction if isolation is

data/acceptance/cases/type/all_types_test.rb

@@ -30,19 +30,19 @@ module ActiveRecord
         AllTypes.create col_string: "string", col_int64: 100, col_float64: 3.14, col_numeric: 6.626, col_bool: true,
           col_bytes: StringIO.new("bytes"), col_date: ::Date.new(2021, 6, 23),
           col_timestamp: ::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"),
-          col_json: ENV["SPANNER_EMULATOR_HOST"] ? "" : { kind: "user_renamed", change: %w[jack john]},
+          col_json: { kind: "user_renamed", change: %w[jack john]},
           col_array_string: ["string1", nil, "string2"],
-          col_array_int64: [100, nil, 200],
-          col_array_float64: [3.14, nil, 2.0/3.0],
-          col_array_numeric: [6.626, nil, 3.20],
-          col_array_bool: [true, nil, false],
+          col_array_int64: [100, nil, 200, "300"],
+          col_array_float64: [3.14, nil, 2.0/3.0, "3.14"],
+          col_array_numeric: [6.626, nil, 3.20, "400"],
+          col_array_bool: [true, nil, false, "false"],
           col_array_bytes: [StringIO.new("bytes1"), nil, StringIO.new("bytes2")],
-          col_array_date: [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24)],
+          col_array_date: [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24), "2021-06-25"],
           col_array_timestamp: [::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"), nil, \
-                                ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00")],
-          col_array_json: ENV["SPANNER_EMULATOR_HOST"] ? [""] : \
-                            [{ kind: "user_renamed", change: %w[jack john]}, nil, \
-                             { kind: "user_renamed", change: %w[alice meredith]}]
+                                ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00"), "2021-06-25 17:08:21 +02:00"],
+          col_array_json: [{ kind: "user_renamed", change: %w[jack john]}, nil, \
+                             { kind: "user_renamed", change: %w[alice meredith]},
+                             "{\"kind\":\"user_renamed\",\"change\":[\"bob\",\"carol\"]}"]
       end
 
       def test_create_record
@@ -66,24 +66,25 @@ module ActiveRecord
           assert_equal ::Date.new(2021, 6, 23), record.col_date
           assert_equal ::Time.new(2021, 6, 23, 17, 8, 21, "+02:00").utc, record.col_timestamp.utc
           assert_equal ({"kind" => "user_renamed", "change" => %w[jack john]}),
-                       record.col_json unless ENV["SPANNER_EMULATOR_HOST"]
+                       record.col_json
 
           assert_equal ["string1", nil, "string2"], record.col_array_string
-          assert_equal [100, nil, 200], record.col_array_int64
-          assert_equal [3.14, nil, 2.0/3.0], record.col_array_float64
-          assert_equal [6.626, nil, 3.20], record.col_array_numeric
-          assert_equal [true, nil, false], record.col_array_bool
+          assert_equal [100, nil, 200, 300], record.col_array_int64
+          assert_equal [3.14, nil, 2.0/3.0, 3.14], record.col_array_float64
+          assert_equal [6.626, nil, 3.20, 400], record.col_array_numeric
+          assert_equal [true, nil, false, false], record.col_array_bool
           assert_equal [StringIO.new("bytes1"), nil, StringIO.new("bytes2")].map { |bytes| bytes&.read },
                        record.col_array_bytes.map { |bytes| bytes&.read }
-          assert_equal [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24)], record.col_array_date
+          assert_equal [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24), ::Date.new(2021, 06, 25)], record.col_array_date
           assert_equal [::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"), \
                             nil, \
-                            ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00")].map { |timestamp| timestamp&.utc },
+                            ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00"), ::Time.new(2021, 6, 25, 17, 8, 21, "+02:00")].map { |timestamp| timestamp&.utc },
                        record.col_array_timestamp.map { |timestamp| timestamp&.utc}
           assert_equal [{"kind" => "user_renamed", "change" => %w[jack john]}, \
                         nil, \
-                        {"kind" => "user_renamed", "change" => %w[alice meredith]}],
-                       record.col_array_json unless ENV["SPANNER_EMULATOR_HOST"]
+                        {"kind" => "user_renamed", "change" => %w[alice meredith]}, \
+                        "{\"kind\":\"user_renamed\",\"change\":[\"bob\",\"carol\"]}"],
+                       record.col_array_json
         end
       end
 
@@ -98,7 +99,7 @@ module ActiveRecord
                           col_bool: false, col_bytes: StringIO.new("new bytes"),
                           col_date: ::Date.new(2021, 6, 28),
                           col_timestamp: ::Time.new(2021, 6, 28, 11, 22, 21, "+02:00"),
-                          col_json: ENV["SPANNER_EMULATOR_HOST"] ? "" : { kind: "user_created", change: %w[jack alice]},
+                          col_json: { kind: "user_created", change: %w[jack alice]},
                           col_array_string: ["new string 1", "new string 2"],
                           col_array_int64: [300, 200, 100],
                           col_array_float64: [1.1, 2.2, 3.3],
@@ -107,9 +108,7 @@ module ActiveRecord
                           col_array_bytes: [StringIO.new("new bytes 1"), StringIO.new("new bytes 2")],
                           col_array_date: [::Date.new(2021, 6, 28)],
                           col_array_timestamp: [::Time.utc(2020, 12, 31, 0, 0, 0)],
-                          col_array_json: ENV["SPANNER_EMULATOR_HOST"] ?
-                                            [""] : \
-                                            [{ kind: "user_created", change: %w[jack alice]}]
+                          col_array_json: [{ kind: "user_created", change: %w[jack alice]}]
           end
 
           # Verify that the record was updated.
@@ -123,7 +122,7 @@ module ActiveRecord
           assert_equal ::Date.new(2021, 6, 28), record.col_date
           assert_equal ::Time.new(2021, 6, 28, 11, 22, 21, "+02:00").utc, record.col_timestamp.utc
           assert_equal ({"kind" => "user_created", "change" => %w[jack alice]}),
-                       record.col_json unless ENV["SPANNER_EMULATOR_HOST"]
+                     record.col_json
 
           assert_equal ["new string 1", "new string 2"], record.col_array_string
           assert_equal [300, 200, 100], record.col_array_int64
@@ -135,7 +134,7 @@ module ActiveRecord
           assert_equal [::Date.new(2021, 6, 28)], record.col_array_date
           assert_equal [::Time.utc(2020, 12, 31, 0, 0, 0)], record.col_array_timestamp.map(&:utc)
           assert_equal [{"kind" => "user_created", "change" => %w[jack alice]}],
-                       record.col_array_json unless ENV["SPANNER_EMULATOR_HOST"]
+                       record.col_array_json
         end
       end
 

data/acceptance/cases/type/json_test.rb

@@ -18,8 +18,6 @@ module ActiveRecord
       end
 
       def test_set_json
-        return if ENV["SPANNER_EMULATOR_HOST"]
-
         expected_hash = {"key"=>"value", "array_key"=>%w[value1 value2]}
         record = TestTypeModel.new details: {key: "value", array_key: %w[value1 value2]}
 

data/acceptance/models/album.rb

@@ -4,9 +4,14 @@
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
+require "composite_primary_keys"
+
 class Album < ActiveRecord::Base
+  # Register both primary key columns with composite_primary_keys
+  self.primary_keys = :singerid, :albumid
+
   # The relationship with singer is not really a foreign key, but an INTERLEAVE IN relationship. We still need to
   # use the `foreign_key` attribute to indicate which column to use for the relationship.
-  belongs_to :singer, foreign_key: "singerid"
-  has_many :tracks, foreign_key: "albumid", dependent: :delete_all
+  belongs_to :singer, foreign_key: :singerid
+  has_many :tracks, foreign_key: [:singerid, :albumid], dependent: :delete_all
 end

data/acceptance/models/singer.rb

@@ -5,6 +5,6 @@
 # https://opensource.org/licenses/MIT.
 
 class Singer < ActiveRecord::Base
-  has_many :albums, foreign_key: "singerid", dependent: :delete_all
-  has_many :tracks, foreign_key: "singerid"
+  has_many :albums, foreign_key: :singerid, dependent: :delete_all
+  has_many :tracks, foreign_key: :singerid
 end

data/acceptance/models/track.rb

@@ -5,8 +5,11 @@
 # https://opensource.org/licenses/MIT.
 
 class Track < ActiveRecord::Base
-  belongs_to :album, foreign_key: "albumid"
-  belongs_to :singer, foreign_key: "singerid", counter_cache: true
+  # Register both primary key columns with composite_primary_keys
+  self.primary_keys = :singerid, :albumid, :trackid
+
+  belongs_to :album, foreign_key: [:singerid, :albumid]
+  belongs_to :singer, foreign_key: :singerid, counter_cache: true
 
   def initialize attributes = nil
     super

data/acceptance/schema/schema.rb

@@ -17,8 +17,7 @@ ActiveRecord::Schema.define do
       t.column :col_bytes, :binary
       t.column :col_date, :date
       t.column :col_timestamp, :datetime
-      t.column :col_json, :json unless ENV["SPANNER_EMULATOR_HOST"]
-      t.column :col_json, :string if ENV["SPANNER_EMULATOR_HOST"]
+      t.column :col_json, :json
 
       t.column :col_array_string, :string, array: true
       t.column :col_array_int64, :bigint, array: true
@@ -28,8 +27,7 @@ ActiveRecord::Schema.define do
       t.column :col_array_bytes, :binary, array: true
       t.column :col_array_date, :date, array: true
       t.column :col_array_timestamp, :datetime, array: true
-      t.column :col_array_json, :json, array: true unless ENV["SPANNER_EMULATOR_HOST"]
-      t.column :col_array_json, :string, array: true if ENV["SPANNER_EMULATOR_HOST"]
+      t.column :col_array_json, :json, array: true
     end
 
     create_table :firms do |t|

data/acceptance/test_helper.rb

@@ -208,7 +208,7 @@ module SpannerAdapter
           t.date :start_date
           t.datetime :start_datetime
           t.time :start_time
-          t.json :details unless ENV["SPANNER_EMULATOR_HOST"]
+          t.json :details
         end
       end
 

data/activerecord-spanner-adapter.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.5"
 
   spec.add_dependency "google-cloud-spanner", "~> 2.10"
-  spec.add_runtime_dependency "activerecord", "~> 6.1.4"
+  spec.add_runtime_dependency "activerecord", [">= 6.0.0", "< 7.1"]
 
   spec.add_development_dependency "autotest-suffix", "~> 1.1"
   spec.add_development_dependency "bundler", "~> 2.0"

data/examples/rails/README.md

@@ -142,17 +142,17 @@ Replace `[PROJECT_ID]` with the project id you are currently using.
 ### Create database
 
 You now can run the following command to create the database:
-    ```shell
-    ./bin/rails db:create
-    ```
-    You should see output like the following:
-    ```
-    Created database 'blog_dev'
-    ```
+
+```shell
+./bin/rails db:create
+```
+    
+You should see output like the following: `Created database 'blog_dev'`
+    
 ### Generate a Model and apply the migration
 1. Use the model generato to define a model:
     ```shell
-    bin/rails generate model Article title:string body:text
+    ./bin/rails generate model Article title:string body:text
     ```
 1. Apply the migration:
     ```shell

data/examples/snippets/interleaved-tables/README.md

@@ -0,0 +1,164 @@
+# Sample - Interleaved Tables
+
+This example shows how to use interleaved tables with the Spanner ActiveRecord adapter.
+Interleaved tables use composite primary keys. This is not natively supported by ActiveRecord.
+It is therefore necessary to use the `composite_primary_keys` (https://github.com/composite-primary-keys/composite_primary_keys)
+gem to enable the use of interleaved tables.
+
+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.
+
+## Example Data Model
+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
+  # Add `trackid` as the primary key in the table definition. Add the other key parts as
+  # a `parent_key`.
+  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
+The model definition for an interleaved table (a child table) must use the `primary_keys=col1, col2, ...`
+function from the `composite_primary_key` gem.
+
+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(s) 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`).
+  has_many :albums, foreign_key: :singerid
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`.
+  # The primary key of `tracks` is (`singerid`, `albumid`, `trackid`).
+  # The `singerid` column can 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
+  # Use the `composite_primary_key` gem to create a composite primary key definition for the model.
+  self.primary_keys = :singerid, :albumid
+
+  # `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`).
+  has_many :tracks, foreign_key: [:singerid, :albumid]
+end
+
+class Track < ActiveRecord::Base
+  # Use the `composite_primary_key` gem to create a composite primary key definition for the model.
+  self.primary_keys = :singerid, :albumid, :trackid
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`. The primary key of `albums` is (`singerid`, `albumid`).
+  belongs_to :album, foreign_key: [:singerid, :albumid]
+
+  # `tracks` also has a `singerid` column that can 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 2022 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