activerecord-spanner-adapter 1.0.0 → 1.2.0

data/examples/snippets/interleaved-tables/application.rb

@@ -0,0 +1,126 @@
+# 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 "io/console"
+require_relative "../config/environment"
+require_relative "models/singer"
+require_relative "models/album"
+require_relative "models/track"
+
+class Application
+  def self.run
+    # List all singers, albums and tracks.
+    list_singers_albums_tracks
+
+    # Create a new album with some tracks.
+    create_new_album
+
+    # Try to update the singer of an album. This is not possible as albums are interleaved in singers.
+    update_singer_of_album
+
+    # Try to delete a singer that has at least one album. This is NOT possible as albums is NOT marked with
+    # ON DELETE CASCADE.
+    delete_singer_with_albums
+
+    # Try to delete an album that has at least one track. This IS possible as tracks IS marked with
+    # ON DELETE CASCADE.
+    delete_album_with_tracks
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+
+  def self.find_singer
+    singerid = Singer.all.sample.singerid
+
+    singer = Singer.find singerid
+    puts "Found singer: #{singer.first_name} #{singer.last_name}"
+  end
+
+  def self.find_album
+    singer = Singer.all.sample
+    albumid = singer.albums.sample.albumid
+
+    album = Album.find [singer.singerid, albumid]
+    puts "Found album: #{album.title}"
+  end
+
+  def self.list_singers_albums_tracks
+    puts ""
+    puts "Listing all singers with corresponding albums and tracks"
+    Singer.all.order("last_name, first_name").each do |singer|
+      puts "#{singer.first_name} #{singer.last_name} has #{singer.albums.count} albums:"
+      singer.albums.order("title").each do |album|
+        puts "  #{album.title} has #{album.tracks.count} tracks:"
+        album.tracks.each do |track|
+          puts "    #{track.title}"
+        end
+      end
+    end
+  end
+
+  def self.create_new_album
+    # Create a new album with some tracks.
+    puts ""
+    singer = Singer.all.sample
+    puts "Creating a new album for #{singer.first_name} #{singer.last_name}"
+    album = singer.albums.build title: "New Title"
+    # NOTE: When adding multiple elements to a collection, you *MUST* set the primary key value (i.e. trackid).
+    # Otherwise, ActiveRecord thinks that you are adding the same record multiple times and will only add one.
+    album.tracks.build title: "Track 1", duration: 3.5, singer: singer, trackid: Track.next_sequence_value
+    album.tracks.build title: "Track 2", duration: 3.6, singer: singer, trackid: Track.next_sequence_value
+    # This will save the album and corresponding tracks in one transaction.
+    album.save!
+
+    album.reload
+    puts "Album #{album.title} has #{album.tracks.count} tracks:"
+    album.tracks.order("title").each do |track|
+      puts "  #{track.title} with duration #{track.duration}"
+    end
+  end
+
+  def self.update_singer_of_album
+    # It is not possible to change the singer of an album or the album of a track. This is because the associations
+    # between these are not traditional foreign keys, but an immutable parent-child relationship.
+    album = Album.all.sample
+    new_singer = Singer.all.where.not(singerid: album.singer).sample
+    # This will fail as we cannot assign a new singer to an album as it is an INTERLEAVE IN PARENT relationship.
+    begin
+      album.update! singer: new_singer
+      raise StandardError, "Unexpected error: Updating the singer of an album should not be possible."
+    rescue ActiveRecord::StatementInvalid
+      puts ""
+      puts "Failed to update the singer of an album. This is expected."
+    end
+  end
+
+  def self.delete_singer_with_albums
+    # Deleting a singer that has albums is not possible, as the INTERLEAVE IN PARENT of albums is not marked with
+    # ON DELETE CASCADE.
+    singer = Album.all.sample.singer
+    begin
+      singer.delete
+      raise StandardError, "Unexpected error: Updating the singer of an album should not be possible."
+    rescue ActiveRecord::StatementInvalid
+      puts ""
+      puts "Failed to delete a singer that has #{singer.albums.count} albums. This is expected."
+    end
+  end
+
+  def self.delete_album_with_tracks
+    # Deleting an album with tracks is supported, as the INTERLEAVE IN PARENT relationship between tracks and albums is
+    # marked with ON DELETE CASCADE.
+    puts ""
+    puts "Total track count: #{Track.count}"
+    album = Track.all.sample.album
+    puts "Deleting album #{album.title} with #{album.tracks.count} tracks"
+    album.delete
+    puts "Total track count after deletion: #{Track.count}"
+  end
+end
+
+Application.run

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

@@ -0,0 +1,44 @@
+# 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.
+
+class CreateTables < ActiveRecord::Migration[6.0]
+  def change
+    # Execute the entire migration as one DDL batch.
+    connection.ddl_batch do
+      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
+    end
+  end
+end

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 `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", primary_key: "albumid", id: { limit: 8 }, force: :cascade do |t|
+    t.integer "singerid", limit: 8, null: false
+    t.string "title"
+  end
+
+  create_table "singers", primary_key: "singerid", id: { limit: 8 }, force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  create_table "tracks", primary_key: "trackid", id: { limit: 8 }, 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 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.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,20 @@
+# 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 "composite_primary_keys"
+
+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

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

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

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

@@ -0,0 +1,28 @@
+# 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.
+
+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 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/lib/active_record/connection_adapters/spanner/schema_creation.rb

@@ -10,14 +10,20 @@ module ActiveRecord
       class SchemaCreation < SchemaCreation
         private
 
-        # rubocop:disable Naming/MethodName, Metrics/AbcSize
+        # rubocop:disable Naming/MethodName, Metrics/AbcSize, Metrics/PerceivedComplexity
 
         def visit_TableDefinition o
           create_sql = +"CREATE TABLE #{quote_table_name o.name} "
           statements = o.columns.map { |c| accept c }
 
-          o.foreign_keys.each do |to_table, options|
-            statements << foreign_key_in_create(o.name, to_table, options)
+          if ActiveRecord::VERSION::MAJOR >= 7
+            o.foreign_keys.each do |fk|
+              statements << accept(fk)
+            end
+          else
+            o.foreign_keys.each do |to_table, options|
+              statements << foreign_key_in_create(o.name, to_table, options)
+            end
           end
 
           create_sql << "(#{statements.join ', '}) " if statements.any?
@@ -106,7 +112,7 @@ module ActiveRecord
           sql
         end
 
-        # rubocop:enable Naming/MethodName, Metrics/AbcSize
+        # rubocop:enable Naming/MethodName, Metrics/AbcSize, Metrics/PerceivedComplexity
 
         def add_column_options! sql, options
           if options[:null] == false || options[:primary_key] == true

data/lib/active_record/connection_adapters/spanner_adapter.rb

@@ -8,6 +8,7 @@ require "securerandom"
 require "google/cloud/spanner"
 require "spanner_client_ext"
 require "active_record/connection_adapters/abstract_adapter"
+require "active_record/connection_adapters/abstract/connection_pool"
 require "active_record/connection_adapters/spanner/database_statements"
 require "active_record/connection_adapters/spanner/schema_statements"
 require "active_record/connection_adapters/spanner/schema_cache"
@@ -43,9 +44,9 @@ module ActiveRecord
   module ConnectionAdapters
     module AbstractPool
       def get_schema_cache connection
-        @schema_cache ||= SpannerSchemaCache.new connection
-        @schema_cache.connection = connection
-        @schema_cache
+        self.schema_cache ||= SpannerSchemaCache.new connection
+        schema_cache.connection = connection
+        schema_cache
       end
     end
 
@@ -178,41 +179,73 @@ module ActiveRecord
         Arel::Visitors::Spanner.new self
       end
 
-      private
+      def build_insert_sql insert
+        if current_spanner_transaction&.isolation == :buffered_mutations
+          raise "ActiveRecordSpannerAdapter does not support insert_sql with buffered_mutations transaction."
+        end
 
-      def initialize_type_map m = type_map
-        m.register_type "BOOL", Type::Boolean.new
-        register_class_with_limit(
-          m, %r{^BYTES}i, ActiveRecord::Type::Spanner::Bytes
-        )
-        m.register_type "DATE", Type::Date.new
-        m.register_type "FLOAT64", Type::Float.new
-        m.register_type "NUMERIC", Type::Decimal.new
-        m.register_type "INT64", Type::Integer.new(limit: 8)
-        register_class_with_limit m, %r{^STRING}i, Type::String
-        m.register_type "TIMESTAMP", ActiveRecord::Type::Spanner::Time.new
-        m.register_type "JSON", ActiveRecord::Type::Json.new
+        if insert.skip_duplicates? || insert.update_duplicates?
+          raise NotImplementedError, "CloudSpanner does not support skip_duplicates and update_duplicates."
+        end
 
-        register_array_types m
+        values_list, = insert.values_list
+        "INSERT #{insert.into} #{values_list}"
       end
 
-      def register_array_types m
-        m.register_type %r{^ARRAY<BOOL>}i, Type::Spanner::Array.new(Type::Boolean.new)
-        m.register_type %r{^ARRAY<BYTES\((MAX|d+)\)>}i, Type::Spanner::Array.new(Type::Binary.new)
-        m.register_type %r{^ARRAY<DATE>}i, Type::Spanner::Array.new(Type::Date.new)
-        m.register_type %r{^ARRAY<FLOAT64>}i, Type::Spanner::Array.new(Type::Float.new)
-        m.register_type %r{^ARRAY<NUMERIC>}i, Type::Spanner::Array.new(Type::Decimal.new)
-        m.register_type %r{^ARRAY<INT64>}i, Type::Spanner::Array.new(Type::Integer.new(limit: 8))
-        m.register_type %r{^ARRAY<STRING\((MAX|d+)\)>}i, Type::Spanner::Array.new(Type::String.new)
-        m.register_type %r{^ARRAY<TIMESTAMP>}i, Type::Spanner::Array.new(ActiveRecord::Type::Spanner::Time.new)
-        m.register_type %r{^ARRAY<JSON>}i, Type::Spanner::Array.new(ActiveRecord::Type::Json.new)
+      module TypeMapBuilder
+        private
+
+        def initialize_type_map m = type_map
+          m.register_type "BOOL", Type::Boolean.new
+          register_class_with_limit(
+            m, %r{^BYTES}i, ActiveRecord::Type::Spanner::Bytes
+          )
+          m.register_type "DATE", Type::Date.new
+          m.register_type "FLOAT64", Type::Float.new
+          m.register_type "NUMERIC", Type::Decimal.new
+          m.register_type "INT64", Type::Integer.new(limit: 8)
+          register_class_with_limit m, %r{^STRING}i, Type::String
+          m.register_type "TIMESTAMP", ActiveRecord::Type::Spanner::Time.new
+          m.register_type "JSON", ActiveRecord::Type::Json.new
+
+          register_array_types m
+        end
+
+        def register_array_types m
+          m.register_type %r{^ARRAY<BOOL>}i, Type::Spanner::Array.new(Type::Boolean.new)
+          m.register_type %r{^ARRAY<BYTES\((MAX|d+)\)>}i,
+                          Type::Spanner::Array.new(ActiveRecord::Type::Spanner::Bytes.new)
+          m.register_type %r{^ARRAY<DATE>}i, Type::Spanner::Array.new(Type::Date.new)
+          m.register_type %r{^ARRAY<FLOAT64>}i, Type::Spanner::Array.new(Type::Float.new)
+          m.register_type %r{^ARRAY<NUMERIC>}i, Type::Spanner::Array.new(Type::Decimal.new)
+          m.register_type %r{^ARRAY<INT64>}i, Type::Spanner::Array.new(Type::Integer.new(limit: 8))
+          m.register_type %r{^ARRAY<STRING\((MAX|d+)\)>}i, Type::Spanner::Array.new(Type::String.new)
+          m.register_type %r{^ARRAY<TIMESTAMP>}i, Type::Spanner::Array.new(ActiveRecord::Type::Spanner::Time.new)
+          m.register_type %r{^ARRAY<JSON>}i, Type::Spanner::Array.new(ActiveRecord::Type::Json.new)
+        end
+
+        def extract_limit sql_type
+          value = /\((.*)\)/.match sql_type
+          return unless value
+
+          value[1] == "MAX" ? "MAX" : value[1].to_i
+        end
       end
 
-      def extract_limit sql_type
-        value = /\((.*)\)/.match sql_type
-        return unless value
+      if ActiveRecord::VERSION::MAJOR >= 7
+        class << self
+          include TypeMapBuilder
+        end
+
+        TYPE_MAP = Type::TypeMap.new.tap { |m| initialize_type_map m }
+
+        private
 
-        value[1] == "MAX" ? "MAX" : value[1].to_i
+        def type_map
+          TYPE_MAP
+        end
+      else
+        include TypeMapBuilder
       end
 
       def translate_exception exception, message:, sql:, binds:

data/lib/active_record/type/spanner/array.rb

@@ -15,15 +15,29 @@ module ActiveRecord
           @element_type = element_type
         end
 
-        def serialize value
+        def cast value
           return super if value.nil?
-          return super unless @element_type.is_a? Type::Decimal
           return super unless value.respond_to? :map
 
-          # Convert a decimal (NUMERIC) array to a String array to prevent it from being encoded as a FLOAT64 array.
           value.map do |v|
-            next if v.nil?
-            v.to_s
+            @element_type.cast v
+          end
+        end
+
+        def serialize value
+          return super if value.nil?
+          return super unless value.respond_to? :map
+
+          if @element_type.is_a? ActiveRecord::Type::Decimal
+            # Convert a decimal (NUMERIC) array to a String array to prevent it from being encoded as a FLOAT64 array.
+            value.map do |v|
+              next if v.nil?
+              v.to_s
+            end
+          else
+            value.map do |v|
+              @element_type.serialize v
+            end
           end
         end
       end