activerecord-spanner-adapter 2.0.0 → 2.2.0

data/examples/snippets/auto-generated-primary-key/README.md

@@ -0,0 +1,140 @@
+# Sample - Auto-generated Primary Keys
+
+This example shows how to use an IDENTITY column to generate the primary key of a model.
+
+See https://cloud.google.com/spanner/docs/primary-key-default-value#identity-columns for more information
+about IDENTITY columns in Cloud Spanner.
+
+## Requirements
+Using IDENTITY for generating primary key values in ActiveRecord has the following requirements:
+1. You must use __ActiveRecord version 7.1 or higher__.
+2. Your database configuration must include a `default_sequence_kind` value like this:
+
+```yaml
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  default_sequence_kind: BIT_REVERSED_POSITIVE
+  pool: 5
+  timeout: 5000
+  schema_dump: false
+```
+
+## Creating Tables with IDENTITY in ActiveRecord
+You can create an IDENTITY column using migrations in ActiveRecord by using the `:primary_key` type
+for the column. Note that this only generates an IDENTITY column if you have included the option
+`default_sequence_kind: BIT_REVERSED_POSITIVE` as shown above.
+
+Any default `id` column that is added by ActiveRecord will also use the `:primary_key` type and use
+an IDENTITY column.
+
+```ruby
+# The default `id` column that is added by ActiveRecord will automatically use
+# an IDENTITY column.
+create_table :singers do |t|
+  t.string :first_name
+  t.string :last_name
+end
+
+# You can also explicitly create a primary key column with a different name. Use
+# the :primary_key type to generate an IDENTITY column.
+create_table :singers, id: false, primary_key: :singerid do |t|
+  # Use the ':primary_key' data type to create an auto-generated primary key column.
+  t.column :singerid, :primary_key, primary_key: true, null: false
+  t.string :first_name
+  t.string :last_name
+end
+```
+
+## Example Data Model
+This example uses the following table schema:
+
+```sql
+CREATE TABLE `singers` (
+    `singerid` INT64 NOT NULL GENERATED BY DEFAULT AS IDENTITY (BIT_REVERSED_POSITIVE),
+    `first_name` STRING(MAX),
+    `last_name` STRING(MAX)
+) PRIMARY KEY (`singerid`)
+
+CREATE TABLE `albums` (
+    `singerid` INT64 NOT NULL,
+    `albumid` INT64 NOT NULL GENERATED BY DEFAULT AS IDENTITY (BIT_REVERSED_POSITIVE),
+    `title` STRING(MAX)
+) PRIMARY KEY (`singerid`, `albumid`), INTERLEAVE IN PARENT `singers`
+```
+
+This schema can be created in ActiveRecord 7.1 and later as follows:
+
+```ruby
+# Execute the entire migration as one DDL batch.
+connection.ddl_batch do
+  create_table :singers, id: false, primary_key: :singerid do |t|
+    # Use the ':primary_key' data type to create an auto-generated primary key column.
+    t.column :singerid, :primary_key, primary_key: true, null: false
+    t.string :first_name
+    t.string :last_name
+  end
+
+  create_table :albums, primary_key: [:singerid, :albumid], id: false do |t|
+    # Interleave the `albums` table in the parent table `singers`.
+    t.interleave_in :singers
+    t.integer :singerid, null: false
+    # Use the ':primary_key' data type to create an auto-generated primary key column.
+    t.column :albumid, :primary_key, null: false
+    t.string :title
+  end
+end
+```
+
+## Auto-generated Primary Keys and Mutations
+
+Using primary keys that are auto-generated by an IDENTITY column is not
+supported in combination with mutations, because Spanner must return the
+generated primary key value after a row was inserted using a `THEN RETURN`
+clause. This is not supported for mutations.
+
+A workaround for this is to explicitly set a value for the primary key of
+a row before inserting it:
+
+```ruby
+ActiveRecord::Base.transaction isolation: :buffered_mutations do
+  # Assign the singer a random id value. This value will be included in the insert mutation.
+  singer = Singer.create id: SecureRandom.uuid.gsub("-", "").hex & 0x7FFFFFFFFFFFFFFF,
+                         first_name: "Melissa", last_name: "Garcia"
+end
+```
+
+You can also instruct the Spanner ActiveRecord provider to automatically include a
+primary key value when you use mutations. The primary key value assignment can then
+be omitted from your code. Add `use_client_side_id_for_mutations: true` to your
+configuration for this:
+
+```yaml
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  default_sequence_kind: BIT_REVERSED_POSITIVE
+  use_client_side_id_for_mutations: true
+  pool: 5
+  timeout: 5000
+  schema_dump: false
+```
+
+## 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 following commands:
+
+```bash
+export AR_VERSION="~> 7.1.2"
+bundle install
+bundle exec rake run
+```

data/examples/snippets/auto-generated-primary-key/Rakefile

@@ -0,0 +1,13 @@
+# Copyright 2025 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 auto-generated-primary keys."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[auto-generated-primary-key]" }
+end

data/examples/snippets/auto-generated-primary-key/application.rb

@@ -0,0 +1,86 @@
+# Copyright 2025 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
+    # Create a new singer.
+    singer = create_new_singer
+
+    # Create a new album.
+    album = create_new_album singer
+
+    # Verify that the album exists.
+    find_album singer.singerid, album.albumid
+
+    # List all singers, albums and tracks.
+    list_singers_albums
+
+    # Create a new singer using mutations.
+    # This requires us to set a primary key value manually.
+    # You can also instruct the Spanner Ruby ActiveRecord provider to that automatically
+    # by including this in your database configuration:
+    #   use_client_side_id_for_mutations: true
+    create_new_singer_using_mutations
+  end
+
+  def self.find_album singerid, albumid
+    album = Album.find [singerid, albumid]
+    puts "Found album: #{album.title}"
+  end
+
+  def self.list_singers_albums
+    puts ""
+    puts "Listing all singers with corresponding albums"
+    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}"
+      end
+    end
+  end
+
+  def self.create_new_singer
+    # Create a new singer. The singerid is generated by an IDENTITY column in the database and returned.
+    puts ""
+    singer = Singer.create first_name: "Melissa", last_name: "Garcia"
+    puts "Created a new singer '#{singer.first_name} #{singer.last_name}' with id #{singer.singerid}"
+
+    singer
+  end
+
+  def self.create_new_album singer
+    # Create a new album.
+    puts ""
+    puts "Creating a new album for #{singer.first_name} #{singer.last_name}"
+    # The albumid is not generated by the database.
+    album = singer.albums.build albumid: 1, title: "New Title"
+    album.save!
+
+    album
+  end
+
+  def self.create_new_singer_using_mutations
+    # Create a new singer using mutations. Mutations do not support THEN RETURN clauses,
+    # so we must specify a value for the primary key before inserting the row.
+    puts ""
+    singer = nil
+    ActiveRecord::Base.transaction isolation: :buffered_mutations do
+      # Assign the singer a random id value. This value will be included in the insert mutation.
+      singer = Singer.create id: SecureRandom.uuid.gsub("-", "").hex & 0x7FFFFFFFFFFFFFFF,
+                             first_name: "Melissa", last_name: "Garcia"
+    end
+    puts "Inserted a new singer '#{singer.first_name} #{singer.last_name}' using mutations with id #{singer.singerid}"
+
+    singer
+  end
+end
+
+Application.run

data/examples/snippets/auto-generated-primary-key/config/database.yml

@@ -0,0 +1,10 @@
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  default_sequence_kind: BIT_REVERSED_POSITIVE
+  pool: 5
+  timeout: 5000
+  schema_dump: false

data/examples/snippets/auto-generated-primary-key/db/migrate/01_create_tables.rb

@@ -0,0 +1,29 @@
+# Copyright 2025 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[7.1]
+  def change
+    connection.default_sequence_kind = "BIT_REVERSED_POSITIVE"
+    # Execute the entire migration as one DDL batch.
+    connection.ddl_batch do
+      create_table :singers, id: false, primary_key: :singerid do |t|
+        # Use the ':primary_key' data type to create an auto-generated primary key column.
+        t.column :singerid, :primary_key, primary_key: true, null: false
+        t.string :first_name
+        t.string :last_name
+      end
+
+      create_table :albums, primary_key: [:singerid, :albumid], id: false do |t|
+        # Interleave the `albums` table in the parent table `singers`.
+        t.interleave_in :singers
+        t.integer :singerid, null: false
+        # Use the ':primary_key' data type to create an auto-generated primary key column.
+        t.column :albumid, :primary_key, null: false
+        t.string :title
+      end
+    end
+  end
+end

data/examples/snippets/auto-generated-primary-key/db/seeds.rb

@@ -0,0 +1,31 @@
+# Copyright 2023 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_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]
+
+# NOTE: We do not use mutations to insert these rows, because letting the database generate the primary key means that
+# we rely on a `THEN RETURN id` clause in the insert statement. This is only supported for DML statements, and not for
+# mutations.
+ActiveRecord::Base.transaction 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/auto-generated-primary-key/models/album.rb

@@ -0,0 +1,11 @@
+# Copyright 2025 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+class Album < ActiveRecord::Base
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`.
+  # The primary key of `singers` is `singerid`.
+  belongs_to :singer, foreign_key: :singerid
+end

data/examples/snippets/auto-generated-primary-key/models/singer.rb

@@ -0,0 +1,11 @@
+# Copyright 2025 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
+end

data/examples/snippets/isolation-level/README.md

@@ -0,0 +1,39 @@
+# Sample - Isolation Level
+
+This example shows how to use a specific isolation level for read/write transactions
+using the Spanner ActiveRecord adapter.
+
+You can specify the isolation level in two ways:
+
+1. Set a default in the database configuration:
+
+```yaml
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  isolation_level: :serializable,
+  pool: 5
+  timeout: 5000
+  schema_dump: false
+```
+
+2. Specify the isolation level for a specific transaction. This will override any
+   default that is set in the database configuration.
+
+```ruby
+ActiveRecord::Base.transaction isolation: :repeatable_read do
+  # Execute transaction code...
+end
+```
+
+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/isolation-level/Rakefile

@@ -0,0 +1,13 @@
+# Copyright 2025 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 specify a transaction isolation level for Spanner with ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[isolation-level]" }
+end

data/examples/snippets/isolation-level/application.rb

@@ -0,0 +1,36 @@
+# Copyright 2025 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require "io/console"
+require_relative "../config/environment"
+require_relative "models/singer"
+require_relative "models/album"
+
+class Application
+  def self.run # rubocop:disable Metrics/AbcSize
+    from_album = nil
+    to_album = nil
+    # Execute a read/write transaction using isolation level repeatable read.
+    puts "Executing a read/write transaction using isolation level repeatable read"
+    ActiveRecord::Base.transaction isolation: :repeatable_read do
+      # Transfer a marketing budget of 10,000 from one album to another.
+      from_album = Album.all.sample
+      to_album = Album.where.not(id: from_album.id).sample
+
+      puts ""
+      puts "Transferring 10,000 marketing budget from #{from_album.title} (#{from_album.marketing_budget}) " \
+           "to #{to_album.title} (#{to_album.marketing_budget})"
+      from_album.update marketing_budget: from_album.marketing_budget - 10000
+      to_album.update marketing_budget: to_album.marketing_budget + 10000
+    end
+    puts ""
+    puts "Budgets after update:"
+    puts "Marketing budget #{from_album.title}: #{from_album.reload.marketing_budget}"
+    puts "Marketing budget #{to_album.title}: #{to_album.reload.marketing_budget}"
+  end
+end
+
+Application.run

data/examples/snippets/isolation-level/config/database.yml

@@ -0,0 +1,10 @@
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  isolation_level: :serializable,
+  pool: 5
+  timeout: 5000
+  schema_dump: false

data/examples/snippets/isolation-level/db/migrate/01_create_tables.rb

@@ -0,0 +1,22 @@
+# 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
+        t.string :last_name
+      end
+
+      create_table :albums do |t|
+        t.string :title
+        t.numeric :marketing_budget
+        t.references :singer, index: false, foreign_key: true
+      end
+    end
+  end
+end

data/examples/snippets/isolation-level/db/seeds.rb

@@ -0,0 +1,25 @@
+# Copyright 2021 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require_relative "../../config/environment"
+require_relative "../models/singer"
+require_relative "../models/album"
+
+first_names = ["Pete", "Alice", "John", "Ethel", "Trudy", "Naomi", "Wendy", "Ruben", "Thomas", "Elly"]
+last_names = ["Wendelson", "Allison", "Peterson", "Johnson", "Henderson", "Ericsson", "Aronson", "Tennet", "Courtou"]
+
+adjectives = ["daily", "happy", "blue", "generous", "cooked", "bad", "open"]
+nouns = ["windows", "potatoes", "bank", "street", "tree", "glass", "bottle"]
+budgets = [15000, 25000, 10000, 20000, 30000, 12000, 13000]
+
+5.times do
+  Singer.create first_name: first_names.sample, last_name: last_names.sample
+end
+
+20.times do
+  singer_id = Singer.all.sample.id
+  Album.create title: "#{adjectives.sample} #{nouns.sample}", marketing_budget: budgets.sample, singer_id: singer_id
+end

data/examples/snippets/isolation-level/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/isolation-level/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/lib/active_record/connection_adapters/spanner/column.rb

@@ -19,6 +19,10 @@ module ActiveRecord
           @primary_key = primary_key
         end
 
+        def auto_incremented_by_db?
+          sql_type_metadata.is_identity
+        end
+
         def has_default?
           super && !virtual?
         end

data/lib/active_record/connection_adapters/spanner/database_statements.rb

@@ -292,7 +292,7 @@ module ActiveRecord
               if isolation.count != 1
           else
             raise "Unsupported isolation level: #{isolation}" unless
-              [:serializable, :read_only, :buffered_mutations, :pdml].include? isolation
+              [:serializable, :repeatable_read, :read_only, :buffered_mutations, :pdml].include? isolation
           end
 
           log "BEGIN #{isolation}" do

data/lib/active_record/connection_adapters/spanner/schema_creation.rb

@@ -8,6 +8,11 @@ module ActiveRecord
   module ConnectionAdapters
     module Spanner
       class SchemaCreation < SchemaCreation
+        def initialize connection
+          super
+          @connection = connection
+        end
+
         private
 
         # rubocop:disable Naming/MethodName, Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
@@ -128,14 +133,18 @@ module ActiveRecord
           sql
         end
 
-        # rubocop:enable Naming/MethodName, Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
-
         def add_column_options! column, sql, options
           if options[:null] == false || options[:primary_key] == true
             sql << " NOT NULL"
           end
           if options.key? :default
             sql << " DEFAULT (#{quote_default_expression options[:default], column})"
+          elsif column.type == :primary_key
+            if @connection.use_auto_increment?
+              sql << " AUTO_INCREMENT"
+            elsif @connection.use_identity?
+              sql << " GENERATED BY DEFAULT AS IDENTITY (#{@connection.default_sequence_kind})"
+            end
           end
 
           if !options[:allow_commit_timestamp].nil? &&
@@ -158,6 +167,8 @@ module ActiveRecord
 
           sql
         end
+
+        # rubocop:enable Naming/MethodName, Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
       end
     end
   end

data/lib/active_record/connection_adapters/spanner/schema_statements.rb

@@ -21,8 +21,6 @@ module ActiveRecord
       # [Schema Doc](https://cloud.google.com/spanner/docs/information-schema)
       #
       module SchemaStatements
-        VERSION_6_1_0 = Gem::Version.create "6.1.0"
-        VERSION_6_0_3 = Gem::Version.create "6.0.3"
         VERSION_7_2 = Gem::Version.create "7.2.0"
 
         def current_database
@@ -125,18 +123,20 @@ module ActiveRecord
             fetch_type_metadata(field.spanner_type,
                                 field.ordinal_position,
                                 field.allow_commit_timestamp,
-                                field.generated),
+                                field.generated,
+                                is_identity: field.is_identity),
             field.nullable,
             field.default_function,
             primary_key: field.primary_key
         end
 
-        def fetch_type_metadata sql_type, ordinal_position = nil, allow_commit_timestamp = nil, generated = nil
+        def fetch_type_metadata sql_type, ordinal_position = nil, allow_commit_timestamp = nil, generated = nil,
+                                is_identity: false
           Spanner::TypeMetadata.new \
             super(sql_type),
             ordinal_position: ordinal_position,
             allow_commit_timestamp: allow_commit_timestamp,
-            generated: generated
+            generated: generated, is_identity: is_identity
         end
 
         def add_column table_name, column_name, type, **options

data/lib/active_record/connection_adapters/spanner/type_metadata.rb

@@ -17,12 +17,15 @@ module ActiveRecord
         attr_reader :ordinal_position
         attr_reader :allow_commit_timestamp
         attr_reader :generated
+        attr_reader :is_identity
 
-        def initialize type_metadata, ordinal_position: nil, allow_commit_timestamp: nil, generated: nil
+        def initialize type_metadata, ordinal_position: nil, allow_commit_timestamp: nil, generated: nil,
+                       is_identity: false
           super type_metadata
           @ordinal_position = ordinal_position
           @allow_commit_timestamp = allow_commit_timestamp
           @generated = generated
+          @is_identity = is_identity
         end
 
         def == other
@@ -30,12 +33,13 @@ module ActiveRecord
             __getobj__ == other.__getobj__ &&
             ordinal_position == other.ordinal_position &&
             allow_commit_timestamp == other.allow_commit_timestamp &&
-            generated == other.generated
+            generated == other.generated &&
+            is_identity == other.is_identity
         end
         alias eql? ==
 
         def hash
-          [TypeMetadata.name, __getobj__, ordinal_position, allow_commit_timestamp, generated].hash
+          [TypeMetadata.name, __getobj__, ordinal_position, allow_commit_timestamp, generated, is_identity].hash
         end
 
         private