activerecord-spanner-adapter 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35016d190d27c935b9a004570e326d7cdc75af064f877bd619334ea967cf4d7a
-  data.tar.gz: 1cf91b818edc4d594fcf623f0a3218927406b47523931641fb6e844c88b578ff
+  metadata.gz: cb3f5f2106d42a64cf32616e119f188cc13a1b81acfa040765ae4b5cb2838cf1
+  data.tar.gz: 5ff65bbec67470ddc479f6ba985e9d31c0562848b9f0739e697ceb1d6715e3dc
 SHA512:
-  metadata.gz: 96dfb48e59b278093e118006e393e03b8981fd370605664830a73ad09873ead412a726a838407595fb903194e64f7b368dc940a443d774847679c316742eefc3
-  data.tar.gz: 5aa61e971ad3b21f9a9dee3476e7ce9fe5b52f080c2bd507e39cd2aa90719802d0ba5bcd024c3fa521feabc1e8756a249757dda5d3d432c67111ea3479d50e17
+  metadata.gz: 939b508009ff79969637045e526dab1a73ed2f9b979fc6812447b2b98e673dce42e2d55bbf924fc6b372c35e481a374f8fc556c853b7861b8344735549ca3521
+  data.tar.gz: f9c2dc8d41a7748a12daa8e342ae020c5109f793f62f0d2c506842d7030cac9d9578e169e356728f80e7c590e0a48bfa75fd05c235b121c25c9858e84cd25463

data/.github/workflows/acceptance-tests-on-emulator.yaml

@@ -33,7 +33,7 @@ jobs:
     env:
       AR_VERSION: ${{ matrix.ar }}
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
     # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby
     # (see https://github.com/ruby/setup-ruby#versioning):

data/.github/workflows/acceptance-tests-on-production.yaml

@@ -26,7 +26,7 @@ jobs:
       matrix:
         ruby: [3.3]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
     # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby
     # (see https://github.com/ruby/setup-ruby#versioning):
@@ -35,17 +35,17 @@ jobs:
         bundler-cache: true
         ruby-version: ${{ matrix.ruby }}
     - name: Authenticate Google Cloud
-      uses: google-github-actions/auth@v2
+      uses: google-github-actions/auth@v3
       with:
         credentials_json: ${{ secrets.GCP_SA_KEY }}
     - name: Setup GCloud
-      uses: google-github-actions/setup-gcloud@v2
+      uses: google-github-actions/setup-gcloud@v3
       with:
         project_id: ${{ secrets.GCP_PROJECT_ID }}
     - name: Install dependencies
       run: bundle install
     - name: Run acceptance tests on production
-      run: bundle exec rake acceptance\[,,,"exclude cases/migration"\]
+      run: bundle exec rake acceptance\[,,,"exclude cases/migration"\] TESTOPTS="-v"
       env:
         SPANNER_TEST_PROJECT: ${{ secrets.GCP_PROJECT_ID }}
         SPANNER_TEST_INSTANCE: ruby-activerecord-test

data/.github/workflows/ci.yaml

@@ -25,7 +25,7 @@ jobs:
     env:
       AR_VERSION: ${{ matrix.ar }}
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
     # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby
     # (see https://github.com/ruby/setup-ruby#versioning):

data/.github/workflows/nightly-acceptance-tests-on-emulator.yaml

@@ -33,7 +33,7 @@ jobs:
     env:
       AR_VERSION: ${{ matrix.ar }}
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.github/workflows/nightly-acceptance-tests-on-production.yaml

@@ -12,7 +12,7 @@ jobs:
       matrix:
         ruby: [3.3]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
     # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby
     # (see https://github.com/ruby/setup-ruby#versioning):
@@ -21,11 +21,11 @@ jobs:
         bundler-cache: true
         ruby-version: ${{ matrix.ruby }}
     - name: Authenticate Google Cloud
-      uses: google-github-actions/auth@v2
+      uses: google-github-actions/auth@v3
       with:
         credentials_json: ${{ secrets.GCP_SA_KEY }}
     - name: Setup GCloud
-      uses: google-github-actions/setup-gcloud@v2
+      uses: google-github-actions/setup-gcloud@v3
       with:
         project_id: ${{ secrets.GCP_PROJECT_ID }}
     - name: Install dependencies

data/.github/workflows/nightly-unit-tests.yaml

@@ -26,7 +26,7 @@ jobs:
     env:
       AR_VERSION: ${{ matrix.ar }}
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.github/workflows/rubocop.yaml

@@ -12,13 +12,13 @@ jobs:
     timeout-minutes: 10
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: setup ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3'
+        ruby-version: '3.4.8'
     - name: cache gems
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: vendor/bundle
         key: ${{ runner.os }}-rubocop-${{ hashFiles('**/Gemfile.lock') }}

data/.github/workflows/samples.yaml

@@ -23,7 +23,7 @@ jobs:
     env:
       AR_VERSION: ${{ matrix.ar }}
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.3.0"
+  ".": "2.4.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+### 2.4.0 (2026-02-04)
+
+#### Features
+
+* Add automatic PDML fallback for mutation limit errors ([#369](https://github.com/googleapis/ruby-spanner-activerecord/issues/369)) 
+* Adding support for exclude_txn_from_change_streams option ([#368](https://github.com/googleapis/ruby-spanner-activerecord/issues/368)) ([1b04c70](https://github.com/googleapis/ruby-spanner-activerecord/commit/1b04c70b4ecec62403449af11827d0f3587acfd0)), closes [#367](https://github.com/googleapis/ruby-spanner-activerecord/issues/367)
+* Batch DML support ([#370](https://github.com/googleapis/ruby-spanner-activerecord/issues/370)) 
+* support commit_options ([#364](https://github.com/googleapis/ruby-spanner-activerecord/issues/364)) ([0a1020a](https://github.com/googleapis/ruby-spanner-activerecord/commit/0a1020ac60ff9ddaae1634a2178a71bc0de9480c)), closes [#365](https://github.com/googleapis/ruby-spanner-activerecord/issues/365)
+
 ### 2.3.0 (2025-05-30)
 
 #### Features

data/Gemfile

@@ -6,10 +6,11 @@ gemspec
 ar_version = ENV.fetch("AR_VERSION", "~> 7.1.0")
 gem "activerecord", ar_version
 gem "ostruct"
-gem "minitest", "~> 5.25.0"
+gem "minitest", "~> 5.27.0"
 gem "minitest-rg", "~> 5.3.0"
 gem "pry", "~> 0.14.2"
 gem "pry-byebug", "~> 3.11.0"
+gem "mutex_m"
 # Add sqlite3 for testing for compatibility with other adapters.
 gem 'sqlite3'
 

data/acceptance/cases/tasks/database_tasks_test.rb

@@ -86,6 +86,8 @@ module ActiveRecord
           filename = ActiveRecord::Tasks::DatabaseTasks.dump_filename(config_name, :sql)
         elsif ActiveRecord::Tasks::DatabaseTasks.respond_to?(:schema_dump_path)
           filename = ActiveRecord::Tasks::DatabaseTasks.schema_dump_path(db_config, :sql)
+        else
+          raise "No schema file specified"
         end
         ActiveRecord::Tasks::DatabaseTasks.dump_schema db_config, :sql
         sql = File.read(filename)
@@ -98,10 +100,21 @@ module ActiveRecord
         else
           assert_equal expected_schema_sql_on_production, sql, msg = sql
         end
-        drop_database
-        create_database
-        ActiveRecord::Tasks::DatabaseTasks.load_schema db_config, :sql
-        assert_equal tables, connection.tables.sort
+
+        # Skip the drop-and-recreate test on production, for two reasons:
+        # 1. It is relatively slow.
+        # 2. Dropping and re-creating a database with the same name while keeping the connection open
+        #    causes 'Database not found' errors to be returned (by the session that is used?)
+        if ENV["SPANNER_EMULATOR_HOST"]
+          drop_database
+          create_database
+          begin
+            ActiveRecord::Tasks::DatabaseTasks.load_schema db_config, :sql, file = filename
+          rescue StandardError => e
+            puts "Loading schema failed: #{e}"
+          end
+          assert_equal tables, connection.tables.sort
+        end
       end
 
       def expected_schema_sql_on_emulator

data/acceptance/cases/transactions/read_write_transactions_test.rb

@@ -273,6 +273,35 @@ module ActiveRecord
           TableWithSequence.connection.use_client_side_id_for_mutations = reset_value
         end
       end
+
+      def test_single_dml_succeeds_with_fallback_to_pdml_enabled
+        # This test verifies that a normal, successful DML statement works as
+        # expected when the fallback isolation is enabled. Because no mutation
+        # limit error occurs, the fallback to PDML should NOT be triggered.
+        create_test_records
+        assert_equal 1, Author.count
+
+        Author.transaction isolation: :fallback_to_pdml do
+          Author.where(name: "David").delete_all
+        end
+
+        assert_equal 0, Author.count, "The record should have been deleted"
+      end
+
+      def test_other_errors_do_not_trigger_fallback
+        # This test ensures that if a transaction with fallback enabled fails
+        # for a reason OTHER than the mutation limit, it fails normally and
+        # does not attempt to fall back to PDML.
+        create_test_records
+        initial_author_count = Author.count
+
+        assert_raises ActiveRecord::StatementInvalid do
+          Author.transaction isolation: :fallback_to_pdml do
+            Author.create! name: nil
+          end
+        end
+        assert_equal initial_author_count, Author.count, "Transaction should have rolled back"
+      end
     end
   end
 end

data/examples/snippets/batch-dml/README.md

@@ -0,0 +1,13 @@
+# Sample - Batch DML
+
+This example shows how to use [Batch DML](https://cloud.google.com/spanner/docs/dml-tasks#use-batch)
+with the Spanner ActiveRecord adapter.
+
+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/batch-dml/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 use Batch DML with the Spanner ActiveRecord provider."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[batch-dml]" }
+end

data/examples/snippets/batch-dml/application.rb

@@ -0,0 +1,54 @@
+# 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
+    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]
+
+    # Insert 5 new singers using Batch DML.
+    ActiveRecord::Base.transaction do
+      # The Base.dml_batch function starts a DML batch. All DML statements that are
+      # generated by ActiveRecord inside the block that is given will be added to
+      # the current batch. The batch is executed at the end of the block. The data
+      # that has been written is readable after the block ends.
+      ActiveRecord::Base.dml_batch do
+        5.times do
+          Singer.create first_name: first_names.sample, last_name: last_names.sample
+        end
+      end
+      # Data that has been inserted/update using Batch DML can be read in the same
+      # transaction as the one that added/updated the data. This is different from
+      # mutations, as mutations do not support read-your-writes.
+      singers = Singer.all
+      puts "Inserted #{singers.count} singers in one batch"
+    end
+
+    # Batch DML can also be used to update existing data.
+    ActiveRecord::Base.transaction do
+      # Start a DML batch.
+      singers = nil
+      ActiveRecord::Base.dml_batch do
+        # Queries can be executed inside a DML batch.
+        # These are executed directly and do not affect the DML batch.
+        singers = Singer.all
+        singers.each do |singer|
+          singer.picture = Base64.encode64 SecureRandom.alphanumeric(SecureRandom.random_number(10..200))
+          singer.save
+        end
+      end
+      puts "Updated #{singers.count} singers in one batch"
+    end
+  end
+end
+
+
+Application.run

data/examples/snippets/batch-dml/config/database.yml

@@ -0,0 +1,11 @@
+# Batch DML Example Configuration File
+# This file is used to configure the database connection for the batch DML example.
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  pool: 5
+  timeout: 5000
+  schema_dump: false

data/examples/snippets/batch-dml/db/migrate/01_create_tables.rb

@@ -0,0 +1,23 @@
+# 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[6.0]
+  def change
+    connection.ddl_batch do
+      create_table :singers do |t|
+        t.string :first_name
+        t.string :last_name
+        t.binary :picture
+      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/batch-dml/db/seeds.rb

@@ -0,0 +1,8 @@
+# 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.
+
+# This file is intentionally kept empty, as this sample
+# does not need any initial data.

data/examples/snippets/batch-dml/models/album.rb

@@ -0,0 +1,9 @@
+# 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
+  belongs_to :singer
+end

data/examples/snippets/batch-dml/models/singer.rb

@@ -0,0 +1,9 @@
+# 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
+  has_many :albums
+end

data/examples/snippets/partitioned-dml/application.rb

@@ -26,6 +26,37 @@ class Application
       puts "Deleted #{count} albums"
     end
 
+    puts ""
+    puts "Deleting all singers in the database using normal Read-Write transaction with PDML fallback"
+    #
+    # This example demonstrates using `isolation: :fallback_to_pdml`.
+    #
+    # --- HOW IT WORKS ---
+    # 1. Initial Attempt: The transaction starts as a normal, atomic, read-write transaction.
+    #
+    # 2. The Trigger: If that transaction fails with a `TransactionMutationLimitExceededError`,
+    #    the adapter automatically catches the error.
+    #
+    # 3. The Fallback: The adapter then retries the ENTIRE code block in a new,
+    #    non-atomic Partitioned DML (PDML) transaction.
+    #
+    # --- USAGE REQUIREMENTS ---
+    # This implementation retries the whole transaction block without checking its contents.
+    # The user of this feature is responsible for ensuring the following:
+    #
+    # 1. SINGLE DML STATEMENT: The block should contain only ONE DML statement.
+    #    If it contains more, the PDML retry will fail with a low-level `seqno` error.
+    #
+    # 2. IDEMPOTENCY: The DML statement must be idempotent. See https://cloud.google.com/spanner/docs/dml-partitioned#partitionable-idempotent for more information. # rubocop:disable Layout/LineLength
+    #
+    # 3. NON-ATOMIC: The retried PDML transaction is NOT atomic. Do not use this
+    #    for multi-step operations that must all succeed or fail together.
+    #
+    Singer.transaction isolation: :fallback_to_pdml do
+      count = Singer.delete_all
+      puts "Deleted #{count} singers"
+    end
+
     puts ""
     puts "Deleting all singers in the database using Partitioned DML"
     Singer.transaction isolation: :pdml do

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

@@ -7,6 +7,7 @@
 # frozen_string_literal: true
 
 require "active_record/gem_version"
+require "active_record/connection_adapters/spanner/errors/transaction_mutation_limit_exceeded_error"
 
 module ActiveRecord
   module ConnectionAdapters
@@ -14,6 +15,7 @@ module ActiveRecord
       module DatabaseStatements
         VERSION_7_1_0 = Gem::Version.create "7.1.0"
         RequestOptions = Google::Cloud::Spanner::V1::RequestOptions
+        TransactionMutationLimitExceededError = Google::Cloud::Spanner::Errors::TransactionMutationLimitExceededError
 
         # DDL, DML and DQL Statements
 
@@ -23,9 +25,13 @@ module ActiveRecord
 
         def internal_exec_query sql, name = "SQL", binds = [], prepare: false, async: false, allow_retry: false
           result = internal_execute sql, name, binds, prepare: prepare, async: async, allow_retry: allow_retry
-          ActiveRecord::Result.new(
-            result.fields.keys.map(&:to_s), result.rows.map(&:values)
-          )
+          if result
+            ActiveRecord::Result.new(
+              result.fields.keys.map(&:to_s), result.rows.map(&:values)
+            )
+          else
+            ActiveRecord::Result.new [], []
+          end
         end
 
         def internal_execute sql, name = "SQL", binds = [],
@@ -72,11 +78,19 @@ module ActiveRecord
             ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
               if transaction_required
                 transaction do
-                  @connection.execute_query sql, params: params, types: types, request_options: request_options
+                  @connection.execute_query sql,
+                                            params: params,
+                                            types: types,
+                                            request_options: request_options,
+                                            statement_type: statement_type
                 end
               else
-                @connection.execute_query sql, params: params, types: types, single_use_selector: selector,
-                                          request_options: request_options
+                @connection.execute_query sql,
+                                          params: params,
+                                          types: types,
+                                          single_use_selector: selector,
+                                          request_options: request_options,
+                                          statement_type: statement_type
               end
             end
           end
@@ -142,9 +156,13 @@ module ActiveRecord
 
           def exec_query sql, name = "SQL", binds = [], prepare: false # rubocop:disable Lint/UnusedMethodArgument
             result = execute sql, name, binds
-            ActiveRecord::Result.new(
-              result.fields.keys.map(&:to_s), result.rows.map(&:values)
-            )
+            if result.respond_to? :fields
+              ActiveRecord::Result.new(
+                result.fields.keys.map(&:to_s), result.rows.map(&:values)
+              )
+            else
+              ActiveRecord::Result.new [], []
+            end
           end
 
           def sql_for_insert sql, pk, binds
@@ -190,6 +208,12 @@ module ActiveRecord
         alias delete update
 
         def exec_update sql, name = "SQL", binds = []
+          # Check if a DML batch is active on the connection.
+          if @connection.dml_batch?
+            # This call buffers the SQL.
+            execute sql, name, binds
+            return
+          end
           result = execute sql, name, binds
           # Make sure that we consume the entire result stream before trying to get the stats.
           # This is required because the ExecuteStreamingSql RPC is also used for (Partitioned) DML,
@@ -229,20 +253,45 @@ module ActiveRecord
 
         # Transaction
 
-        def transaction requires_new: nil, isolation: nil, joinable: true
+        def transaction requires_new: nil, isolation: nil, joinable: true, **kwargs, &block # rubocop:disable Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
+          commit_options = kwargs.delete :commit_options
+          exclude_from_streams = kwargs.delete :exclude_txn_from_change_streams
+          @_spanner_begin_transaction_options = {
+            exclude_txn_from_change_streams: exclude_from_streams
+          }
           if !requires_new && current_transaction.joinable?
             return super
           end
 
           backoff = 0.2
           begin
-            super
+            super do
+              # Once the transaction has been started by `super`, apply your custom options
+              # to the Spanner transaction object.
+              if commit_options && @connection.current_transaction
+                @connection.current_transaction.set_commit_options commit_options
+              end
+
+              yield
+            end
           rescue ActiveRecord::StatementInvalid => err
             if err.cause.is_a? Google::Cloud::AbortedError
-              sleep(delay_from_aborted(err) || backoff *= 1.3)
+              sleep(delay_from_aborted(err) || (backoff *= 1.3))
+              retry
+            elsif TransactionMutationLimitExceededError.is_mutation_limit_error? err.cause
+              is_fallback_enabled = isolation == :fallback_to_pdml
+              raise unless is_fallback_enabled
+              @_spanner_begin_transaction_options[:isolation] = :pdml
               retry
+            else
+              raise
             end
-            raise
+          rescue Google::Cloud::AbortedError => err
+            sleep(delay_from_aborted(err) || backoff *= 1.3)
+            retry
+          ensure
+            # Clean up the instance variable to avoid leaking options.
+            @_spanner_begin_transaction_options = nil
           end
         end
 
@@ -256,13 +305,15 @@ module ActiveRecord
             # These are not really isolation levels, but it is the only (best) way to pass in additional
             # transaction options to the connection.
             read_only:          "READ_ONLY",
-            buffered_mutations: "BUFFERED_MUTATIONS"
+            buffered_mutations: "BUFFERED_MUTATIONS",
+            fallback_to_pdml: "FALLBACK_TO_PDML"
           }
         end
 
         def begin_db_transaction
           log "BEGIN" do
-            @connection.begin_transaction
+            opts = @_spanner_begin_transaction_options || {}
+            @connection.begin_transaction nil, **opts
           end
         end
 
@@ -285,18 +336,22 @@ module ActiveRecord
         #                          (this is the same as :read_only)
         #
         def begin_isolated_db_transaction isolation
-          if isolation.is_a? Hash
-            raise "Unsupported isolation level: #{isolation}" unless
-              isolation[:timestamp] || isolation[:staleness] || isolation[:strong]
+          opts = @_spanner_begin_transaction_options || {}
+          # If isolation level is specified in the options, use that instead of the default isolation level.
+          isolation_option = opts[:isolation] || isolation
+          if isolation_option.is_a? Hash
+            raise "Unsupported isolation level: #{isolation_option}" unless
+              isolation_option[:timestamp] || isolation_option[:staleness] || isolation_option[:strong]
             raise "Only one option is supported. It must be one of `timestamp`, `staleness` or `strong`." \
-              if isolation.count != 1
+              if isolation_option.count != 1
           else
-            raise "Unsupported isolation level: #{isolation}" unless
-              [:serializable, :repeatable_read, :read_only, :buffered_mutations, :pdml].include? isolation
+            raise "Unsupported isolation level: #{isolation_option}" unless
+              [:serializable, :repeatable_read, :read_only, :buffered_mutations, :pdml,
+               :fallback_to_pdml].include? isolation_option
           end
 
-          log "BEGIN #{isolation}" do
-            @connection.begin_transaction isolation
+          log "BEGIN #{isolation_option}" do
+            @connection.begin_transaction isolation_option, **opts.except(:isolation)
           end
         end
 
@@ -402,7 +457,7 @@ module ActiveRecord
 
         private_class_method def self.build_sql_statement_regexp *parts # :nodoc:
           parts = parts.map { |part| /#{part}/i }
-          /\A(?:[\(\s]|#{COMMENT_REGEX})*#{Regexp.union(*parts)}/
+          /\A(?:[(\s]|#{COMMENT_REGEX})*#{Regexp.union(*parts)}/
         end
 
         DDL_REGX = build_sql_statement_regexp(:create, :alter, :drop).freeze

data/lib/active_record/connection_adapters/spanner/errors/transaction_mutation_limit_exceeded_error.rb

@@ -0,0 +1,25 @@
+# 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.
+
+module Google
+  module Cloud
+    module Spanner
+      module Errors
+        # Custom exception raised when a transaction exceeds the mutation limit in Google Cloud Spanner.
+        # This provides a specific error class for a common, recoverable scenario.
+        class TransactionMutationLimitExceededError < ActiveRecord::StatementInvalid
+          ERROR_MESSAGE = "The transaction contains too many mutations".freeze
+
+          def self.is_mutation_limit_error? error
+            return false if error.nil?
+            error.is_a?(Google::Cloud::InvalidArgumentError) &&
+              error.message&.include?(ERROR_MESSAGE)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/spanner_adapter.rb

@@ -150,7 +150,8 @@ module ActiveRecord
       end
 
       # Spanner Connection API
-      delegate :ddl_batch, :ddl_batch?, :start_batch_ddl, :abort_batch, :run_batch,
+      delegate :dml_batch, :dml_batch?, :start_batch_dml,
+               :ddl_batch, :ddl_batch?, :start_batch_ddl, :abort_batch, :run_batch,
                :isolation_level, :isolation_level=, to: :@connection
 
       def current_spanner_transaction

data/lib/activerecord_spanner_adapter/base.rb

@@ -49,6 +49,10 @@ module ActiveRecord
       spanner_adapter? && connection&.current_spanner_transaction&.isolation == :buffered_mutations
     end
 
+    def self.dml_batch(&)
+      connection.dml_batch(&)
+    end
+
     def self._should_use_standard_insert_record? values
       !(buffered_mutations? || (primary_key && values.is_a?(Hash))) || !spanner_adapter?
     end

data/lib/activerecord_spanner_adapter/connection.rb

@@ -7,8 +7,11 @@
 require "google/cloud/spanner"
 require "spanner_client_ext"
 require "activerecord_spanner_adapter/information_schema"
+require_relative "../active_record/connection_adapters/spanner/errors/transaction_mutation_limit_exceeded_error"
 
 module ActiveRecordSpannerAdapter
+  TransactionMutationLimitExceededError = Google::Cloud::Spanner::Errors::TransactionMutationLimitExceededError
+
   class Connection
     attr_reader :instance_id
     attr_reader :database_id
@@ -44,6 +47,8 @@ module ActiveRecordSpannerAdapter
     # Call this method if you drop and recreate a database with the same name
     # to prevent the cached information to be used for the new database.
     def self.reset_information_schemas!
+      return unless @database
+
       @information_schemas.each_value do |info_schema|
         info_schema.connection.disconnect!
       end
@@ -159,6 +164,12 @@ module ActiveRecordSpannerAdapter
       false
     end
 
+    # Returns true if this connection is currently executing a DML batch, and otherwise false.
+    def dml_batch?
+      return true if @dml_batch
+      false
+    end
+
     ##
     # Starts a manual DDL batch. The batch must be ended by calling either run_batch or abort_batch.
     #
@@ -173,18 +184,39 @@ module ActiveRecordSpannerAdapter
     #     raise
     #   end
     def start_batch_ddl
-      if @ddl_batch
-        raise Google::Cloud::FailedPreconditionError, "A DDL batch is already active on this connection"
+      if @ddl_batch && @dml_batch
+        raise Google::Cloud::FailedPreconditionError, "Batch is already active on this connection"
       end
       @ddl_batch = []
     end
 
+    ##
+    # Starts a manual DML batch. The batch must be ended by calling either run_batch or abort_batch.
+    #
+    # @example
+    #   begin
+    #     connection.start_batch_dml
+    #     connection.execute_query "insert into `Users` (Id, Name) VALUES (1, 'Test 1')"
+    #     connection.execute_query "insert into `Users` (Id, Name) VALUES (2, 'Test 2')"
+    #     connection.run_batch
+    #   rescue StandardError
+    #     connection.abort_batch
+    #     raise
+    #   end
+    def start_batch_dml
+      if @ddl_batch || @dml_batch
+        raise Google::Cloud::FailedPreconditionError, "A batch is already active on this connection"
+      end
+      @dml_batch = []
+    end
+
     ##
     # Aborts the current batch on this connection. This is a no-op if there is no batch on this connection.
     #
     # @see start_batch_ddl
     def abort_batch
       @ddl_batch = nil
+      @dml_batch = nil
     end
 
     ##
@@ -193,10 +225,21 @@ module ActiveRecordSpannerAdapter
     #
     # @see start_batch_ddl
     def run_batch
-      unless @ddl_batch
+      unless @ddl_batch || @dml_batch
         raise Google::Cloud::FailedPreconditionError, "There is no batch active on this connection"
       end
       # Just return if the batch is empty.
+      return true if @ddl_batch&.empty? || @dml_batch&.empty?
+      begin
+        if @ddl_batch
+          run_ddl_batch
+        else
+          run_dml_batch
+        end
+      end
+    end
+
+    def run_ddl_batch
       return true if @ddl_batch.empty?
       begin
         execute_ddl_statements @ddl_batch, nil, true
@@ -205,9 +248,43 @@ module ActiveRecordSpannerAdapter
       end
     end
 
+    def run_dml_batch
+      return true if @dml_batch.empty?
+      begin
+        # Execute the DML statements in the batch.
+        execute_dml_statements_in_batch @dml_batch
+      ensure
+        @dml_batch = nil
+      end
+    end
+
+    ##
+    # Executes a set of DML statements as one batch. This method raises an error if no block is given.
+    def dml_batch
+      raise Google::Cloud::FailedPreconditionError, "No block given for the DML batch" unless block_given?
+      begin
+        start_batch_dml
+        yield
+        run_batch
+      rescue StandardError
+        abort_batch
+        raise
+      ensure
+        @dml_batch = nil
+      end
+    end
+
     # DQL, DML Statements
 
-    def execute_query sql, params: nil, types: nil, single_use_selector: nil, request_options: nil
+    def execute_query sql, params: nil, types: nil, single_use_selector: nil, request_options: nil, statement_type: nil
+      # Clear the transaction from the previous statement.
+      unless current_transaction&.active?
+        self.current_transaction = nil
+      end
+      if statement_type == :dml && dml_batch?
+        @dml_batch.push({ sql: sql, params: params, types: types })
+        return
+      end
       if params
         converted_params, types =
           Google::Cloud::Spanner::Convert.to_input_params_and_types(
@@ -215,11 +292,6 @@ module ActiveRecordSpannerAdapter
           )
       end
 
-      # Clear the transaction from the previous statement.
-      unless current_transaction&.active?
-        self.current_transaction = nil
-      end
-
       selector = transaction_selector || single_use_selector
       execute_sql_request sql, converted_params, types, selector, request_options
     end
@@ -250,6 +322,9 @@ module ActiveRecordSpannerAdapter
       end
       raise
     rescue Google::Cloud::Error => e
+      if TransactionMutationLimitExceededError.is_mutation_limit_error? e
+        raise
+      end
       # Check if it was the first statement in a transaction that included a BeginTransaction
       # option in the request. If so, execute an explicit BeginTransaction and then retry the
       # request without the BeginTransaction option.
@@ -274,9 +349,11 @@ module ActiveRecordSpannerAdapter
 
     # Transactions
 
-    def begin_transaction isolation = nil
+    def begin_transaction isolation = nil, **options
       raise "Nested transactions are not allowed" if current_transaction&.active?
-      self.current_transaction = Transaction.new self, isolation || @isolation_level
+      exclude_from_streams = options.fetch :exclude_txn_from_change_streams, false
+      self.current_transaction = Transaction.new self, isolation || @isolation_level,
+                                                 exclude_txn_from_change_streams: exclude_from_streams
       current_transaction.begin
       current_transaction
     end
@@ -343,6 +420,42 @@ module ActiveRecordSpannerAdapter
       job.done?
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def execute_dml_statements_in_batch statements
+      selector = transaction_selector
+      response = session.batch_update selector, current_transaction&.next_sequence_number do |batch|
+        statements.each do |statement|
+          batch.batch_update statement[:sql], params: statement[:params], types: statement[:types]
+        end
+      end
+      batch_update_results = Google::Cloud::Spanner::BatchUpdateResults.new response
+      first_res = response.result_sets.first
+      current_transaction.grpc_transaction = first_res.metadata.transaction \
+        if current_transaction && first_res&.metadata&.transaction
+      batch_update_results.row_counts
+    rescue Google::Cloud::AbortedError
+      # Mark the current transaction as aborted to prevent any unnecessary further requests on the transaction.
+      current_transaction&.mark_aborted
+      raise
+    rescue Google::Cloud::Spanner::BatchUpdateError => e
+      # Check if the status is ABORTED, and if it is, just propagate an AbortedError.
+      if e.cause&.code == GRPC::Core::StatusCodes::ABORTED
+        current_transaction&.mark_aborted
+        raise e.cause
+      end
+
+      # Check if the request returned a transaction or not.
+      # BatchDML is capable of returning BOTH an error and a transaction.
+      if current_transaction && !current_transaction.grpc_transaction? && selector&.begin&.read_write
+        selector = create_transaction_after_failed_first_statement e
+        retry
+      end
+      # It was not the first statement, or it returned a transaction, so propagate the error.
+      raise
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+
     ##
     # Retrieves the delay value from Google::Cloud::AbortedError or
     # GRPC::Aborted

data/lib/activerecord_spanner_adapter/transaction.rb

@@ -7,14 +7,21 @@
 module ActiveRecordSpannerAdapter
   class Transaction
     attr_reader :state
+    attr_reader :commit_options
+    attr_reader :begin_transaction_selector
+    attr_accessor :exclude_txn_from_change_streams
 
-    def initialize connection, isolation
+
+
+    def initialize connection, isolation, commit_options = nil, exclude_txn_from_change_streams: false
       @connection = connection
       @isolation = isolation
       @committable = ![:read_only, :pdml].include?(isolation) && !isolation.is_a?(Hash)
       @state = :INITIALIZED
       @sequence_number = 0
       @mutations = []
+      @commit_options = commit_options
+      @exclude_txn_from_change_streams = exclude_txn_from_change_streams
     end
 
     def active?
@@ -59,7 +66,8 @@ module ActiveRecordSpannerAdapter
           @begin_transaction_selector = Google::Cloud::Spanner::V1::TransactionSelector.new \
             begin: Google::Cloud::Spanner::V1::TransactionOptions.new(
               read_write: Google::Cloud::Spanner::V1::TransactionOptions::ReadWrite.new,
-              isolation_level: grpc_isolation
+              isolation_level: grpc_isolation,
+              exclude_txn_from_change_streams: @exclude_txn_from_change_streams
             )
         end
         @state = :STARTED
@@ -95,14 +103,23 @@ module ActiveRecordSpannerAdapter
       @sequence_number += 1 if @committable
     end
 
+    # Sets the commit options for this transaction.
+    # This is used to set the options for the commit RPC, such as return_commit_stats and max_commit_delay.
+    def set_commit_options options # rubocop:disable Naming/AccessorMethodName
+      @commit_options = options&.dup
+    end
+
     def commit
       raise "This transaction is not active" unless active?
 
       begin
         # Start a transaction with an explicit BeginTransaction RPC if the transaction only contains mutations.
         force_begin_read_write if @committable && !@mutations.empty? && !@grpc_transaction
-
-        @connection.session.commit_transaction @grpc_transaction, @mutations if @committable && @grpc_transaction
+        if @committable && @grpc_transaction
+          @connection.session.commit_transaction @grpc_transaction,
+                                                 @mutations,
+                                                 commit_options: commit_options
+        end
         @state = :COMMITTED
       rescue Google::Cloud::NotFoundError => e
         if @connection.session_not_found? e
@@ -148,6 +165,10 @@ module ActiveRecordSpannerAdapter
       @grpc_transaction = Google::Cloud::Spanner::Transaction.from_grpc grpc, @connection.session
     end
 
+    def grpc_transaction?
+      @grpc_transaction if @grpc_transaction
+    end
+
     def transaction_selector
       return unless active?
 

data/lib/activerecord_spanner_adapter/version.rb

@@ -5,5 +5,5 @@
 # https://opensource.org/licenses/MIT.
 
 module ActiveRecordSpannerAdapter
-  VERSION = "2.3.0".freeze
+  VERSION = "2.4.0".freeze
 end

data/lib/spanner_client_ext.rb

@@ -23,13 +23,14 @@ module Google
       end
 
       class Session
-        def commit_transaction transaction, mutations = []
+        def commit_transaction transaction, mutations = [], commit_options: nil
           ensure_service!
 
           resp = service.commit(
             path,
             mutations,
-            transaction_id: transaction.transaction_id
+            transaction_id: transaction.transaction_id,
+            commit_options: commit_options
           )
           @last_updated_at = Time.now
           Convert.timestamp_to_time resp.commit_timestamp

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-spanner-adapter
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Google LLC
@@ -365,6 +365,14 @@ files:
 - examples/snippets/auto-generated-primary-key/db/seeds.rb
 - examples/snippets/auto-generated-primary-key/models/album.rb
 - examples/snippets/auto-generated-primary-key/models/singer.rb
+- examples/snippets/batch-dml/README.md
+- examples/snippets/batch-dml/Rakefile
+- examples/snippets/batch-dml/application.rb
+- examples/snippets/batch-dml/config/database.yml
+- examples/snippets/batch-dml/db/migrate/01_create_tables.rb
+- examples/snippets/batch-dml/db/seeds.rb
+- examples/snippets/batch-dml/models/album.rb
+- examples/snippets/batch-dml/models/singer.rb
 - examples/snippets/bin/create_emulator_instance.rb
 - examples/snippets/bit-reversed-sequence/README.md
 - examples/snippets/bit-reversed-sequence/Rakefile
@@ -538,6 +546,7 @@ files:
 - examples/solidus/README.md
 - lib/active_record/connection_adapters/spanner/column.rb
 - lib/active_record/connection_adapters/spanner/database_statements.rb
+- lib/active_record/connection_adapters/spanner/errors/transaction_mutation_limit_exceeded_error.rb
 - lib/active_record/connection_adapters/spanner/quoting.rb
 - lib/active_record/connection_adapters/spanner/schema_cache.rb
 - lib/active_record/connection_adapters/spanner/schema_creation.rb