activerecord-spanner-adapter 1.8.0 → 2.1.0

data/benchmarks/application.rb

@@ -63,7 +63,7 @@ class Application
 
     puts ""
     puts "Press any key to end the application"
-    STDIN.getch
+    $stdin.getch
   end
 
   def self.execute_individual_benchmarks singer, client
@@ -120,9 +120,7 @@ class Application
       sql = "SELECT * FROM Singers WHERE id=@id"
       params = { id: singer[:id] }
       param_types = { id: :INT64 }
-      client.execute(sql, params: params, types: param_types).rows.each do |row|
-        return row
-      end
+      client.execute(sql, params: params, types: param_types).rows.first(1)
     else
       Singer.find singer.id
     end
@@ -134,9 +132,7 @@ class Application
       sql = "SELECT * FROM Singers WHERE id=@id"
       params = { id: singer[:id] }
       param_types = { id: :INT64 }
-      client.execute(sql, params: params, types: param_types).rows.each do |row|
-        return row
-      end
+      client.execute(sql, params: params, types: param_types).rows.first(1)
     else
       singer.reload
     end

data/examples/snippets/Rakefile

@@ -7,19 +7,38 @@
 require_relative "config/environment"
 require "docker"
 
-desc "Lists all available samples."
-task :list do
-  samples = Dir.entries(".").select do |entry|
+def fetch_samples
+  Dir.entries(".").select do |entry|
     File.directory?(File.join(".", entry)) \
-     && !%w[. ..].include?(entry) \
-     && File.exist?(File.join(".", entry, "application.rb"))
+      && !%w[. ..].include?(entry) \
+      && File.exist?(File.join(".", entry, "application.rb"))
   end
+end
+
+desc "Lists all available samples."
+task :list do
+  samples = fetch_samples
   puts "Available samples: "
   samples.sort.each { |dir| puts "  #{dir}" }
   puts ""
   puts "Run a sample with the command `bundle exec rake run\\[<sample-name>\\]`"
 end
 
+desc "Runs all samples."
+task :all do
+  samples = fetch_samples
+  ar_version = ENV.fetch "AR_VERSION", "~> 7.1.0"
+  less_than_7_1 = ar_version.dup.to_s.sub("~>", "").strip < "7.1.0"
+  samples.delete "interleaved-tables" if less_than_7_1
+  samples.delete "interleaved-tables-before-7.1" unless less_than_7_1
+  samples.delete "bit-reversed-sequence" if less_than_7_1
+  samples.delete "auto-generated-primary-key" if less_than_7_1
+  samples.delete "query-logs" if less_than_7_1
+  samples.each do |sample|
+    run_sample sample
+  end
+end
+
 desc "Runs a simple ActiveRecord tutorial on a Spanner emulator."
 task :run, [:sample] do |_t, args|
   sample = args[:sample]
@@ -28,7 +47,11 @@ task :run, [:sample] do |_t, args|
     puts ""
     sample = "quickstart"
   end
+  run_sample sample
+end
 
+def run_sample sample
+  puts "Running #{sample}"
   puts "Downloading Spanner emulator image..."
   Docker::Image.create "fromImage" => "gcr.io/cloud-spanner-emulator/emulator:latest"
   puts "Creating Spanner emulator container..."

data/examples/snippets/array-data-type/application.rb

@@ -9,7 +9,7 @@ require_relative "../config/environment"
 require_relative "models/entity_with_array_types"
 
 class Application
-  def self.run # rubocop:disable Metrics/AbcSize
+  def self.run
     # Create a record with all array types.
     record = EntityWithArrayTypes.create \
       col_array_string: ["value1", "value2", "value3"],
@@ -35,10 +35,6 @@ class Application
     puts "Bytes array: #{record.col_array_bytes.map(&:read)}"
     puts "Date array: #{record.col_array_date}"
     puts "Timestamp array: #{record.col_array_timestamp}"
-
-    puts ""
-    puts "Press any key to end the application"
-    STDIN.getch
   end
 end
 

data/examples/snippets/array-data-type/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false

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/bit-reversed-sequence/application.rb

@@ -22,10 +22,6 @@ class Application
 
     # List all singers, albums and tracks.
     list_singers_albums
-
-    puts ""
-    puts "Press any key to end the application"
-    STDIN.getch
   end
 
   def self.find_album singerid, albumid

data/examples/snippets/bit-reversed-sequence/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false

data/examples/snippets/bit-reversed-sequence/db/seeds.rb

@@ -4,7 +4,7 @@
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
-require_relative "../../config/environment.rb"
+require_relative "../../config/environment"
 require_relative "../models/singer"
 require_relative "../models/album"
 
@@ -14,7 +14,7 @@ last_names = %w[Wendelson Allison Peterson Johnson Henderson Ericsson Aronson Te
 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
+# 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

data/examples/snippets/bulk-insert/application.rb

@@ -46,7 +46,7 @@ class Application
       ]
     end
     puts ""
-    puts "Created a batch of #{singers.length} singers and #{albums.length} "\
+    puts "Created a batch of #{singers.length} singers and #{albums.length} " \
          "albums using a transaction with buffered mutations:"
     singers.each do |s|
       puts "  Created singer #{s.first_name} #{s.last_name} with id #{s.id}"
@@ -54,10 +54,6 @@ class Application
         puts "    with album #{a.title} with id #{a.id}"
       end
     end
-
-    puts ""
-    puts "Press any key to end the application"
-    STDIN.getch
   end
 end
 

data/examples/snippets/bulk-insert/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false

data/examples/snippets/commit-timestamp/application.rb

@@ -43,10 +43,6 @@ class Application
     puts "Singer and album updated:"
     puts "#{singer.first_name} #{singer.last_name} (Last updated: #{singer.last_updated.strftime format})"
     puts "   #{album.title} (Last updated: #{album.last_updated.strftime format})"
-
-    puts ""
-    puts "Press any key to end the application"
-    STDIN.getch
   end
 end
 

data/examples/snippets/commit-timestamp/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false

data/examples/snippets/config/environment.rb

@@ -4,11 +4,16 @@
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
+require "logger" # https://github.com/rails/rails/issues/54260
 require "active_record"
 require "bundler"
 
 Dir["../../lib/*.rb"].each { |file| require file }
 
+if ActiveRecord.version >= Gem::Version.create("7.2.0")
+  ActiveRecord::ConnectionAdapters.register "spanner", "ActiveRecord::ConnectionAdapters::SpannerAdapter"
+end
+
 Bundler.require
 
 ActiveRecord::Base.establish_connection(

data/examples/snippets/create-records/application.rb

@@ -13,7 +13,7 @@ class Application
   def self.run
     # Creating a single record without an explicit transaction will automatically save it to the database.
     # It is not recommended to call Entity.create repeatedly to insert multiple records, as each call will
-    # use a separate Spanner transaction. Instead multiple records should be created by passing an array of
+    # use a separate Spanner transaction. Instead, multiple records should be created by passing an array of
     # entities to the Entity.create method.
     singer = Singer.create first_name: "Dave", last_name: "Allison"
     puts ""
@@ -32,10 +32,6 @@ class Application
     singers.each do |s|
       puts "  Created singer #{s.first_name} #{s.last_name} with id #{s.id}"
     end
-
-    puts ""
-    puts "Press any key to end the application"
-    STDIN.getch
   end
 end
 

data/examples/snippets/create-records/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false

data/examples/snippets/date-data-type/application.rb

@@ -17,7 +17,7 @@ class Application
       puts "#{"#{singer.first_name} #{singer.last_name}".ljust 30}#{singer.birth_date}"
     end
 
-    # Update the birth date of a random singer using the current system time. Any time and timezone information will be
+    # Update the birthdate of a random singer using the current system time. Any time and timezone information will be
     # lost after saving the record as a DATE only contains the year, month and day-of-month information.
     singer = Singer.all.sample
     singer.update birth_date: Time.now
@@ -25,10 +25,6 @@ class Application
     puts ""
     puts "Updated birth date to current system time:"
     puts "#{"#{singer.first_name} #{singer.last_name}".ljust 30}#{singer.birth_date}"
-
-    puts ""
-    puts "Press any key to end the application"
-    STDIN.getch
   end
 end
 

data/examples/snippets/date-data-type/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false

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

@@ -4,7 +4,7 @@
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 #
-require_relative "../../config/environment.rb"
+require_relative "../../config/environment"
 require_relative "../models/singer"
 
 first_names = %w[Nelson Todd William Alex Dominique Adenoid Steve Nathan Beverly Annie Amy Norma Diana Regan Phyllis]

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

@@ -27,10 +27,6 @@ class Application
     singer.reload
     puts ""
     puts "Singer updated: #{singer.full_name}"
-
-    puts ""
-    puts "Press any key to end the application"
-    STDIN.getch
   end
 end
 

data/examples/snippets/generated-column/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false

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

@@ -4,7 +4,7 @@
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
-require_relative "../../config/environment.rb"
+require_relative "../../config/environment"
 require_relative "../models/singer"
 
 first_names = %w[Pete Alice John Ethel Trudy Naomi Wendy Ruben Thomas Elly]

data/examples/snippets/hints/application.rb

@@ -37,10 +37,6 @@ class Application
           .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
 

data/examples/snippets/hints/config/database.yml

@@ -6,3 +6,4 @@ development:
   database: testdb
   pool: 5
   timeout: 5000
+  schema_dump: false