statesman 13.3.0 → 13.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5de6588300b8aa3559f3ef4691e865c8b4571b029029671704aa8249b6fccb48
-  data.tar.gz: 2b70040b208dfa076b5633640668f5b964a148cd7d6ea4e1cd7a6671dc29e5cd
+  metadata.gz: 706f8fde91c1454f1ab6a7082c1317341eb5855f4c4c418e73bca0246b677a0e
+  data.tar.gz: 6cc6d3c4c43fc38f751dd361db4a7dd622b02b4ca07afd94315bef7dc433f23d
 SHA512:
-  metadata.gz: 33129e2eb00defefabd11b7edcf85efb709eed969c68897fc2b321927e8b7b47a7e4abf474365ab4ed9b9b5916e06937752a312520e205650427992de93adf2e
-  data.tar.gz: 0c33cba64756fc17cb293c0efbd3dd752d7741c8fb7469407ce1e5eb51df59a4c3ff9b989e433ed5220716c6c378a97331e7cb4ffb64fe97dbd9521be6dd2877
+  metadata.gz: fbcf95c6f1bfdbb867768072d5cfe47d0476d26c9f37ad038eb7563ee541cf03dd4a2e66c77fe808926732e9f51a6746be77892b171148756d07e24e3e11b368
+  data.tar.gz: b70bb3d87a2f6923a4f42b1d2fda278caae324d2339731a2abdd501ac76f4a43fd70a9128a528ae55e1e05173d944b6d328b2ebeedc6c56a8a128e0d7b48371d

data/.github/workflows/tests.yml

@@ -21,7 +21,52 @@ jobs:
           bundler-cache: true
       - run: bundle exec rubocop --extra-details --display-style-guide --parallel --force-exclusion
 
+  bundle:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.3", "3.4", "4.0"]
+        rails-version:
+          - "7.2"
+          - "8.0"
+          - "8.1"
+          - "main"
+    runs-on: ubuntu-latest
+    env:
+      RAILS_VERSION: ${{ matrix.rails-version }}
+      BUNDLE_PATH: vendor/bundle
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "${{ matrix.ruby-version }}"
+      - name: Resolve gems
+        run: bundle lock
+      - name: Restore gems
+        id: cache
+        uses: actions/cache/restore@v6
+        with:
+          path: vendor/bundle
+          key: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-${{ hashFiles('Gemfile.lock') }}
+          restore-keys: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-
+      - name: Install gems
+        if: steps.cache.outputs.cache-hit != 'true'
+        # The lockfile is stored inside the cached path so downstream jobs, which can't
+        # compute this key, can restore the most recent entry and use the same gems.
+        run: |
+          bundle install --jobs 4
+          bundle clean
+          cp Gemfile.lock vendor/bundle/Gemfile.lock
+      - name: Save gems
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v6
+        with:
+          path: vendor/bundle
+          key: ${{ steps.cache.outputs.cache-primary-key }}
+
   sqlite:
+    needs: bundle
     strategy:
       fail-fast: false
       matrix:
@@ -37,18 +82,33 @@ jobs:
     runs-on: ubuntu-latest
     env:
       RAILS_VERSION: ${{ matrix.rails-version }}
+      BUNDLE_PATH: vendor/bundle
     steps:
       - uses: actions/checkout@v5
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          bundler-cache: true
           ruby-version: "${{ matrix.ruby-version }}"
+      # Restore-only: the bundle job owns saving, so matrix jobs never race to write
+      # the same cache entry. The most recent entry for this prefix is the one the
+      # bundle job just resolved.
+      - name: Restore gems
+        uses: actions/cache/restore@v6
+        with:
+          path: vendor/bundle
+          key: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-
+          restore-keys: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-
+          fail-on-cache-miss: true
+      - name: Install gems
+        run: |
+          cp vendor/bundle/Gemfile.lock Gemfile.lock
+          bundle install --local
       - name: Run specs
         run: |
           bundle exec rspec --profile --format progress --format RSpec::Github::Formatter
 
   postgres:
+    needs: bundle
     strategy:
       fail-fast: false
       matrix:
@@ -63,36 +123,37 @@ jobs:
           - ruby-version: "3.2"
             rails-version: "main"
     runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: postgres:${{ matrix.postgres-version }}
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_DB: statesman_test
-          POSTGRES_PASSWORD: statesman
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 10
     env:
-      DATABASE_URL: postgres://postgres:statesman@localhost/statesman_test
-      DATABASE_DEPENDENCY_PORT: "5432"
+      DB: postgres
+      DB_IMAGE: postgres:${{ matrix.postgres-version }}
       RAILS_VERSION: ${{ matrix.rails-version }}
+      BUNDLE_PATH: vendor/bundle
     steps:
       - uses: actions/checkout@v5
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          bundler-cache: true
           ruby-version: "${{ matrix.ruby-version }}"
+      # Restore-only: the bundle job owns saving, so matrix jobs never race to write
+      # the same cache entry. The most recent entry for this prefix is the one the
+      # bundle job just resolved.
+      - name: Restore gems
+        uses: actions/cache/restore@v6
+        with:
+          path: vendor/bundle
+          key: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-
+          restore-keys: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-
+          fail-on-cache-miss: true
+      - name: Install gems
+        run: |
+          cp vendor/bundle/Gemfile.lock Gemfile.lock
+          bundle install --local
       - name: Run specs
         run: |
           bundle exec rspec --profile --format progress --format RSpec::Github::Formatter
 
   mysql:
+    needs: bundle
     strategy:
       fail-fast: false
       matrix:
@@ -108,32 +169,31 @@ jobs:
             rails-version: "main"
 
     runs-on: ubuntu-latest
-    services:
-      mysql:
-        image: mysql:${{ matrix.mysql-version }}
-        env:
-          MYSQL_ROOT_PASSWORD: password
-          MYSQL_USER: foobar
-          MYSQL_PASSWORD: password
-          MYSQL_DATABASE: statesman_test
-        ports:
-          - "3306:3306"
-        options: >-
-          --health-cmd "mysqladmin ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
     env:
-      DATABASE_URL: mysql2://foobar:password@127.0.0.1/statesman_test
-      DATABASE_DEPENDENCY_PORT: "3306"
+      DB: mysql
+      DB_IMAGE: mysql:${{ matrix.mysql-version }}
       RAILS_VERSION: ${{ matrix.rails-version }}
+      BUNDLE_PATH: vendor/bundle
     steps:
       - uses: actions/checkout@v5
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          bundler-cache: true
           ruby-version: "${{ matrix.ruby-version }}"
+      # Restore-only: the bundle job owns saving, so matrix jobs never race to write
+      # the same cache entry. The most recent entry for this prefix is the one the
+      # bundle job just resolved.
+      - name: Restore gems
+        uses: actions/cache/restore@v6
+        with:
+          path: vendor/bundle
+          key: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-
+          restore-keys: bundle-${{ runner.os }}-${{ matrix.ruby-version }}-${{ matrix.rails-version }}-
+          fail-on-cache-miss: true
+      - name: Install gems
+        run: |
+          cp vendor/bundle/Gemfile.lock Gemfile.lock
+          bundle install --local
       - name: Run specs
         run: |
           bundle exec rspec --profile --format progress --format RSpec::Github::Formatter

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.5

data/CHANGELOG.md

@@ -5,6 +5,12 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v13.4.0 14th October 2026
+
+### Added
+
+- `Statesman::BulkTransition`, which transitions many parents from one state to another in a single transaction with a fixed number of queries (a flip of the current `most_recent` rows, one `insert_all!`, and one cached-current-state update if configured). Works with the `ActiveRecord` adapter on PostgreSQL, MySQL (including `mysql_gaplock_protection`) and SQLite. Like `transition_to!`, it flips the previous transition and updates the cached current state, but it does not run guards, `before`/`after` callbacks or `ActiveRecord` validations/callbacks on the transition model. Supports per-parent overrides via `metadata_per_id` and `attributes_per_id`, and an optional block that is called inside the transaction with a lazy `ActiveRecord::Relation` over the newly inserted transitions. Parents not in the `from` state are skipped, so a batch is safe to re-run. Assumes a non-STI transition table and a single-column parent primary key.
+
 ## v13.3.0 4th August 2026
 
 ### Added

data/CONTRIBUTING.md

@@ -11,6 +11,26 @@ ways you can help make this project better!
 - No need to add to the changelog, we will take care of updating it as we make
   releases.
 
+## Running tests
+
+`bundle exec rake` runs the suite against SQLite, PostgreSQL and MySQL in
+parallel. PostgreSQL and MySQL are started as throwaway containers in Docker via
+[Testcontainers](https://github.com/testcontainers/testcontainers-ruby).
+
+```sh
+bundle exec rake                           # all databases, in parallel
+bundle exec rake spec:postgres             # a single database
+```
+
+`bundle exec rspec` runs against SQLite by default. Set `DB` to use a container,
+or point `DATABASE_URL` at an existing database:
+
+```sh
+DB=postgres bundle exec rspec              # postgres:17
+DB=mysql bundle exec rspec                 # mysql:8.4
+DB=mysql DB_IMAGE=mysql:9.4 bundle exec rspec spec/statesman/machine_spec.rb
+```
+
 ## Style
 
 We use [Rubocop](https://github.com/bbatsov/rubocop) to help maintain a

data/Gemfile

@@ -12,6 +12,9 @@ else
   gem "rails", "~> 8.0"
 end
 
+# ActiveSupport 7.2 passes `quirks_mode:` to JSON, which json 3 no longer accepts.
+gem "json", "< 3" if ENV['RAILS_VERSION'] == '7.2'
+
 group :development, :test do
   gem "ammeter", "~> 1.1"
   gem "gc_ruboconfig", "~> 6.0.0"
@@ -24,6 +27,8 @@ group :development, :test do
   gem "rspec-its", "~> 2.0"
   gem "rspec-rails", "~> 8.0"
   gem "sqlite3", "~> 2.9.0"
+  gem "testcontainers-mysql", "~> 0.2.0"
+  gem "testcontainers-postgres", "~> 0.2.0"
   gem "test-unit", "~> 3.3"
   gem "timecop", "~> 0.9.1"
 end

data/README.md

@@ -674,6 +674,66 @@ returning the configured column, for generic tooling that needs to introspect
 or repair the cached column (e.g. a cache-repair rake task working across
 several models).
 
+## Bulk transitions
+
+`Statesman::BulkTransition` moves many parents from one state to another in a
+single transaction, with a fixed number of queries however many parents there
+are, instead of the several queries per record that `transition_to!` costs. It
+works with the `ActiveRecord` adapter on PostgreSQL, MySQL and SQLite.
+
+```ruby
+bulk = Statesman::BulkTransition.new(
+  model_class: Order,
+  machine_class: OrderStateMachine,
+  from: :pending,
+  to: :confirmed,
+)
+
+transitioned_ids = bulk.call!(order_ids, metadata: { source: "import" })
+```
+
+`call!` returns the ids of the parents that were actually transitioned. Parents
+that aren't currently in the `from` state are silently skipped, so a batch is
+safe to re-run.
+
+It performs the same mechanical write as `transition_to!` — flipping the
+current `most_recent` transition, inserting the new one, and updating the
+parent's cached current state if you've called `configure_cached_current_state`
+— but it deliberately **does not run** the machine's guards, its
+`before_transition`/`after_transition` callbacks, or any validations and
+callbacks on the transition model. If you need equivalent side effects,
+reproduce them in the block (below).
+
+Options:
+
+- `metadata:` — applied to every new transition. `metadata_per_id:` overrides it
+  for individual parents, keyed by parent id (`1` and `"1"` match the same
+  parent).
+- `attributes_to_copy:` — extra transition columns to carry forward from the
+  previous transition onto the new one. The parent foreign key and `sort_key`
+  are always carried. There's no default, so you have to choose explicitly.
+  `attributes_per_id:` overrides those carried values for individual parents,
+  and may only name columns listed in `attributes_to_copy` (anything else raises
+  `Statesman::BulkTransition::ValidationError`).
+
+If you pass a block, it is called inside the same transaction with an
+`ActiveRecord::Relation` over the newly inserted transitions. The relation is
+lazy, so the block decides what to read or write:
+
+```ruby
+bulk.call!(order_ids) do |transitions|
+  rows = transitions.pluck(:order_id, :to_state)
+  AuditLog.insert_all(rows.map { |id, state| { order_id: id, state: state } })
+end
+```
+
+An exception raised in the block rolls the entire batch back. If a row
+conflicts with the unique index on the transition table, `call!` raises
+`Statesman::TransitionConflictError` and nothing is committed.
+
+Two assumptions to be aware of: the transition table must not be an STI table,
+and the parent must have a single-column primary key.
+
 ## Frequently Asked Questions
 
 ### Storing the state on the model object

data/Rakefile

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+require "open3"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec) do |task|
@@ -13,4 +14,34 @@ RSpec::Core::RakeTask.new(:spec) do |task|
   end
 end
 
-task default: :spec
+DATABASES = %w[sqlite postgres mysql].freeze
+RSPEC_COMMAND = %w[bundle exec rspec].freeze
+
+# DB_IMAGE and DATABASE_URL are cleared so each run gets its own database rather than all of them
+# sharing whichever one the caller's environment points at.
+database_env = ->(db) { { "DB" => (db unless db == "sqlite"), "DB_IMAGE" => nil, "DATABASE_URL" => nil } }
+
+namespace :spec do
+  DATABASES.each do |db|
+    desc "Run specs against #{db}"
+    task(db) { sh(database_env.call(db), *RSPEC_COMMAND) }
+  end
+
+  desc "Run specs against all databases in parallel"
+  task :all do
+    output_lock = Mutex.new
+
+    results = DATABASES.map do |db|
+      Thread.new do
+        output, status = Open3.capture2e(database_env.call(db), *RSPEC_COMMAND)
+        output_lock.synchronize { puts "==> #{db}", output }
+        [db, status.success?]
+      end
+    end.map(&:value)
+
+    failed = results.reject { |_, success| success }.map(&:first)
+    abort "Specs failed for: #{failed.join(', ')}" if failed.any?
+  end
+end
+
+task default: "spec:all"

data/lib/statesman/bulk_transition.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+module Statesman
+  # Bulk, race-safe state transitions for ActiveRecord (PostgreSQL, MySQL, SQLite).
+  #
+  # Statesman's Machine#transition_to! handles one parent at a time: a flip UPDATE on
+  # the current `most_recent` transition, an INSERT for the new one, and (if the model
+  # called configure_cached_current_state) an UPDATE on the parent's cached column -
+  # each inside its own transaction, with guards/callbacks firing per record.
+  #
+  # BulkTransition performs the same mechanical write for many parents in a single
+  # transaction: one `UPDATE ... RETURNING` to flip+lock the old rows (on adapters without
+  # RETURNING: a `SELECT ... FOR UPDATE` then an `UPDATE`), one `insert_all!` for the new
+  # ones, and one bulk cached_current_state UPDATE if configured. This trades
+  # per-record guards/callbacks/AR-validations for an order-of-magnitude fewer round
+  # trips on large batches.
+  #
+  # Deliberately NOT run: Machine guards, before/after/after_commit callbacks, and AR
+  # validations/callbacks on the transition model. Callers that need equivalent side
+  # effects must reproduce them, set-based, in the block passed to #call!.
+  #
+  # Like the single-transition path, "not current" is written as NULL when the
+  # `most_recent` column is nullable (databases without partial indexes, e.g. MySQL, need
+  # this for the unique (parent, most_recent) index) and false otherwise. On MySQL the
+  # new rows are inserted "not current" and then marked current in a separate UPDATE, to
+  # avoid the next-key locks an INSERT of `most_recent = true` takes (see
+  # Statesman::Adapters::ActiveRecord#create_transition).
+  #
+  # Assumption (documented, not enforced): the transition table is not an STI table.
+  #
+  # A later version may add guard/callback execution (falling back to a plain per-item
+  # #transition_to! loop where needed) - this is the proven,
+  # independent mechanical core that such a version would sit on top of.
+  class BulkTransition
+    class ValidationError < StandardError; end
+
+    SORT_KEY_INCREMENT = 10
+
+    def initialize(model_class:, machine_class:, from:, to:)
+      @model_class = model_class
+      @from = from.to_s
+      @to = to.to_s
+      @transition_class = model_class.transition_class
+
+      machine_class.validate_from_and_to_state(@from, @to)
+    end
+
+    # @param parent_ids [Array<String, Integer>] primary keys of the parents to
+    #   transition. Parents not currently in `from` state are silently skipped - this
+    #   is what makes the batch idempotent and safe to re-run.
+    # @param metadata [Hash] applied uniformly to every new transition row in the batch,
+    #   unless overridden per-parent by metadata_per_id.
+    # @param attributes_to_copy [Array<String, Symbol>] extra transition-row columns to
+    #   carry forward from the flipped row onto the new one, beyond the parent FK and
+    #   sort_key, which are always carried. No default: the caller must explicitly audit
+    #   which mutable columns their own after_transition callbacks depend on.
+    # @param metadata_per_id [Hash{String, Integer => Hash}, nil] per-parent metadata
+    #   overrides, keyed by parent id (matched by its string form, so 1 and "1" are the
+    #   same parent), merged onto (and taking precedence over) the uniform `metadata` for
+    #   that parent only. Parents absent from this hash just get the uniform `metadata`.
+    # @param attributes_per_id [Hash{String, Integer => Hash}, nil] per-parent overrides,
+    #   keyed like metadata_per_id, for attributes_to_copy columns only (anything else
+    #   raises ValidationError), merged onto (and taking precedence over) the value
+    #   carried forward from that parent's own flipped row - for a value that can't be
+    #   derived from the previous transition (e.g. a value looked up from an
+    #   association the caller already has loaded).
+    # @param block [Proc, nil] optional, called with an ActiveRecord::Relation over the
+    #   newly inserted transitions, inside the same transaction, after rows are flipped
+    #   and inserted (and after the cached_current_state bulk update, if any). The
+    #   relation is lazy: the block decides what to read (e.g. `pluck`) or write. An
+    #   exception here rolls back the entire batch - nothing is committed.
+    # @return [Array] parent ids that were actually transitioned.
+    def call!(
+      parent_ids, metadata: {}, attributes_to_copy: [],
+      metadata_per_id: nil, attributes_per_id: nil, &block
+    )
+      return [] if parent_ids.empty?
+
+      attributes_to_copy = attributes_to_copy.to_set(&:to_s)
+      validate_attribute_names!(attributes_to_copy)
+      metadata_per_id = normalize_per_id(metadata_per_id)
+      attributes_per_id = normalize_per_id(attributes_per_id)
+      validate_attributes_per_id!(attributes_per_id, attributes_to_copy)
+
+      now = Time.current
+      transitioned_ids = []
+
+      ActiveRecord::Base.transaction(requires_new: true) do
+        flipped_rows = flip_most_recent!(parent_ids, now, attributes_to_copy)
+        next if flipped_rows.empty?
+
+        primary_keys, transitioned_ids = insert_new_transitions!(
+          flipped_rows, metadata, attributes_to_copy, now, metadata_per_id, attributes_per_id
+        ).transpose
+        inserted = transition_class.where(transition_class.primary_key => primary_keys)
+
+        update_cached_current_state!(transitioned_ids)
+
+        block&.call(inserted)
+      end
+
+      transitioned_ids
+    end
+
+    private
+
+    attr_reader :model_class, :from, :to, :transition_class
+
+    def mysql_gaplock_protection?
+      Statesman.mysql_gaplock_protection?(transition_class.connection)
+    end
+
+    # Matches the single-transition path: NULL when the column is nullable (needed for a
+    # unique (parent, most_recent) index on databases without partial indexes), else false.
+    def not_most_recent_value
+      transition_class.columns_hash["most_recent"].null == false ? false : nil
+    end
+
+    # PostgreSQL can flip and return rows in one `UPDATE ... RETURNING` statement and
+    # recover inserted keys from `INSERT ... RETURNING`. Other adapters (MySQL, SQLite)
+    # take a portable path built from `SELECT ... FOR UPDATE` + `UPDATE` by primary key.
+    def returning_supported?
+      transition_class.connection.adapter_name.casecmp("postgresql").zero?
+    end
+
+    def validate_attribute_names!(attributes_to_copy)
+      unknown = attributes_to_copy - transition_class.column_names
+      return if unknown.empty?
+
+      raise ValidationError, "Unknown #{transition_class.name} column(s): #{unknown.join(', ')}"
+    end
+
+    # Overrides are matched against ids read back from the database, whose type (Integer,
+    # String UUID) the caller needn't know - so both sides are compared as strings. Inner
+    # keys become strings too, because the rows being inserted are string-keyed.
+    def normalize_per_id(per_id)
+      per_id&.to_h { |id, overrides| [id.to_s, overrides.transform_keys(&:to_s)] }
+    end
+
+    # Every row in one insert_all! must have the same keys, and an override for a column
+    # that isn't carried forward would add a key to only some rows.
+    def validate_attributes_per_id!(attributes_per_id, attributes_to_copy)
+      return if attributes_per_id.nil?
+
+      unknown = attributes_per_id.values.flat_map(&:keys).to_set - attributes_to_copy
+      return if unknown.empty?
+
+      raise ValidationError, "attributes_per_id column(s) not in attributes_to_copy: #{unknown.to_a.join(', ')}"
+    end
+
+    def parent_reflection
+      @parent_reflection ||= Statesman::Adapters::ActiveRecordQueries.
+        transition_reflection_for(model_class, transition_class)
+    end
+
+    def parent_foreign_key
+      @parent_foreign_key ||= parent_reflection.foreign_key
+    end
+
+    def parent_primary_key
+      @parent_primary_key ||= parent_reflection.active_record_primary_key
+    end
+
+    # Flips the `from`-state transitions to not-most-recent, returning the flipped
+    # rows (including their pre-flip sort_key) via RETURNING. Under Postgres Read
+    # Committed, a concurrent writer that commits a transition on one of these parents
+    # between this statement starting and acquiring its row lock causes the WHERE
+    # clause to re-evaluate against the latest committed row on wake - so that parent
+    # is silently excluded here, never corrupted.
+    def flip_most_recent!(parent_ids, now, attributes_to_copy)
+      if returning_supported?
+        flip_with_returning!(parent_ids, now, attributes_to_copy)
+      else
+        flip_with_lock!(parent_ids, now, attributes_to_copy)
+      end
+    end
+
+    def flip_with_returning!(parent_ids, now, attributes_to_copy)
+      # Not `RETURNING *`: only the carried columns are used afterwards, and a wider
+      # result set is costly on large batches.
+      returning = carried_columns(attributes_to_copy).
+        map { |column| transition_class.connection.quote_column_name(column) }.
+        join(", ")
+
+      # Arel has no RETURNING support, so that one clause is appended to the compiled
+      # statement; everything else (quoting, binds, IN list) is built by Arel.
+      sql = "#{flip_update_manager(parent_ids, now).to_sql} RETURNING #{returning}"
+
+      transition_class.connection.exec_query(sql).to_a
+    end
+
+    def flip_update_manager(parent_ids, now)
+      table = transition_class.arel_table
+
+      Arel::UpdateManager.new.tap do |update|
+        update.table(table)
+        update.set([[table[:most_recent], not_most_recent_value], [table[:updated_at], now]])
+        update.where(
+          table[:to_state].eq(from).
+            and(table[:most_recent].eq(true)).
+            and(table[parent_foreign_key].in(parent_ids)),
+        )
+      end
+    end
+
+    # Portable equivalent of the above: lock the matching rows, then flip them by primary
+    # key. The locking read always sees the latest committed row (MySQL REPEATABLE READ
+    # included), so a parent that a concurrent writer already moved on is excluded. SQLite
+    # has no row locks, but serialises writers at the database level.
+    def flip_with_lock!(parent_ids, now, attributes_to_copy)
+      columns = carried_columns(attributes_to_copy)
+      primary_key = transition_class.primary_key
+
+      locked = transition_class.
+        where(to_state: from, most_recent: true, parent_foreign_key => parent_ids).
+        lock.
+        pluck(primary_key, *columns)
+      return [] if locked.empty?
+
+      transition_class.where(primary_key => locked.map(&:first)).
+        update_all(most_recent: not_most_recent_value, updated_at: now)
+
+      locked.map { |_pk, *values| columns.zip(values).to_h }
+    end
+
+    def carried_columns(attributes_to_copy)
+      Set[parent_foreign_key, "sort_key"] | attributes_to_copy
+    end
+
+    def insert_new_transitions!(
+      flipped_rows, metadata, attributes_to_copy, now, metadata_per_id, attributes_per_id
+    )
+      carried = carried_columns(attributes_to_copy)
+      include_from_state = transition_class.has_attribute?(:from_state)
+      most_recent = mysql_gaplock_protection? ? not_most_recent_value : true
+
+      rows = flipped_rows.map do |row|
+        id = row[parent_foreign_key]
+        row_metadata = merge_per_id(metadata, metadata_per_id, id)
+        row_overrides = merge_per_id({}, attributes_per_id, id)
+
+        new_row = row.slice(*carried).merge(row_overrides).merge(
+          "to_state" => to,
+          "metadata" => row_metadata,
+          "most_recent" => most_recent,
+          "sort_key" => row["sort_key"].to_i + SORT_KEY_INCREMENT,
+          "created_at" => now,
+          "updated_at" => now,
+        )
+        new_row["from_state"] = from if include_from_state
+        new_row
+      end
+
+      insert_rows!(rows)
+    rescue ActiveRecord::RecordNotUnique => e
+      # One conflicting row aborts the whole batch - this is an accepted trade-off,
+      # not a silent gap: every real writer (Statesman's own single-transition path, and
+      # this class) follows the flip-then-insert convention, so a collision here means
+      # something outside that convention wrote a most_recent row directly.
+      raise TransitionConflictError, e.message
+    end
+
+    # Inserts the rows and returns [primary key, parent foreign key] pairs for them, so the
+    # caller can both build a relation and know which parents moved without another query.
+    # Under MySQL gap-lock protection the rows are also marked most recent here, so
+    # whatever reads them afterwards sees the final state.
+    def insert_rows!(rows)
+      inserted = insert_and_fetch_keys!(rows)
+      mark_most_recent!(inserted.map(&:first)) if mysql_gaplock_protection?
+      inserted
+    end
+
+    def insert_and_fetch_keys!(rows)
+      if returning_supported?
+        return transition_class.insert_all!(rows, returning: [transition_class.primary_key, parent_foreign_key]).rows
+      end
+
+      transition_class.insert_all!(rows)
+      fetch_inserted_keys(rows)
+    end
+
+    # Finds the rows just inserted by (parent, sort_key): the unique index Statesman
+    # requires on those columns makes that pair unambiguous, whatever state the rows are in.
+    def fetch_inserted_keys(inserted)
+      sort_keys = inserted.map { |row| row["sort_key"] }.uniq
+      expected = inserted.to_set { |row| [row[parent_foreign_key], row["sort_key"]] }
+
+      transition_class.
+        where(parent_foreign_key => inserted.map { |row| row[parent_foreign_key] }, sort_key: sort_keys).
+        pluck(transition_class.primary_key, parent_foreign_key, "sort_key").
+        select { |_pk, fk, sort_key| expected.include?([fk, sort_key]) }.
+        map { |pk, fk, _sort_key| [pk, fk] }
+    end
+
+    # Second half of the MySQL gap-lock protection: the old rows were already flipped, so
+    # this only ever sets one row per parent to true and cannot trip the unique index.
+    def mark_most_recent!(primary_keys)
+      transition_class.where(transition_class.primary_key => primary_keys).
+        update_all(most_recent: true)
+    end
+
+    # Merges a per-parent override hash (see normalize_per_id) onto a base hash, for one
+    # parent only. The override, where present, wins key-by-key.
+    def merge_per_id(base, per_id, id)
+      return base if per_id.nil? || !per_id.key?(id.to_s)
+
+      base.merge(per_id.fetch(id.to_s))
+    end
+
+    def update_cached_current_state!(transitioned_ids)
+      return if transitioned_ids.empty?
+      return unless model_class.respond_to?(:cached_state_column_name)
+
+      column = model_class.cached_state_column_name
+      attrs = { column => to }
+      attrs[:updated_at] = Time.current if model_class.cached_current_state_touch_updated_at?
+
+      model_class.where(parent_primary_key => transitioned_ids).update_all(attrs)
+    end
+  end
+end

data/lib/statesman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statesman
-  VERSION = "13.3.0"
+  VERSION = "13.4.0"
 end

data/lib/statesman.rb

@@ -3,6 +3,7 @@
 module Statesman
   autoload :Config,     "statesman/config"
   autoload :Machine,    "statesman/machine"
+  autoload :BulkTransition, "statesman/bulk_transition"
   autoload :Callback,   "statesman/callback"
   autoload :Guard,      "statesman/guard"
   autoload :Utils,      "statesman/utils"

data/spec/spec_helper.rb

@@ -32,11 +32,18 @@ RSpec.configure do |config|
   else
     current_env = ActiveRecord::ConnectionHandling::DEFAULT_ENV.call
 
+    database_url = ENV.fetch("DATABASE_URL") do
+      if (db = ENV["DB"].presence)
+        require "support/database_container"
+        DatabaseContainer.start(db, image: ENV["DB_IMAGE"].presence)
+      end
+    end
+
     # We have to parse this to a hash since ActiveRecord::Base.configurations
     # will only consider a single URL config.
-    url_config = if ENV["DATABASE_URL"]
+    url_config = if database_url
                    ActiveRecord::DatabaseConfigurations::ConnectionUrlResolver.
-                     new(ENV["DATABASE_URL"]).to_hash.merge({ sslmode: "disable" })
+                     new(database_url).to_hash.merge({ sslmode: "disable" })
                  end
 
     db_config = {

data/spec/statesman/adapters/active_record_spec.rb

@@ -15,9 +15,7 @@ describe Statesman::Adapters::ActiveRecord, :active_record do
     Statesman.configure do
       # Rubocop requires described_class to be used, but this block
       # is instance_eval'd and described_class won't be defined
-      # rubocop:disable RSpec/DescribedClass
-      storage_adapter(Statesman::Adapters::ActiveRecord)
-      # rubocop:enable RSpec/DescribedClass
+      storage_adapter(Statesman::Adapters::ActiveRecord) # rubocop:disable RSpec/DescribedClass
     end
   end
 

data/spec/statesman/bulk_transition_spec.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe Statesman::BulkTransition, :active_record do
+  before do
+    # The shared MyActiveRecordModel fixture is wired via the older
+    # `include ActiveRecordQueries[...]` form, which doesn't define `.transition_class`.
+    # BulkTransition relies on the newer `configure_state_machine` convention (the same
+    # one `configure_cached_current_state` requires), so configure it here once.
+    unless MyActiveRecordModel.respond_to?(:transition_class)
+      MyActiveRecordModel.extend(Statesman::Adapters::TypeSafeActiveRecordQueries)
+      MyActiveRecordModel.configure_state_machine(
+        transition_class: MyActiveRecordModelTransition, initial_state: :initial,
+      )
+    end
+
+    unless MyActiveRecordModel.respond_to?(:cached_state_column_name)
+      MyActiveRecordModel.include(Statesman::Adapters::ConfigureCachedCurrentState)
+      MyActiveRecordModel.configure_cached_current_state
+    end
+
+    prepare_model_table
+    prepare_transitions_table
+
+    # Other specs redefine MyActiveRecordModel.transition_class without restoring it, so
+    # pin it here to stay independent of spec ordering.
+    allow(MyActiveRecordModel).to receive(:transition_class).
+      and_return(MyActiveRecordModelTransition)
+
+    # Add a free business column (not one of AR's "magic" created_on/updated_on/etc.
+    # timestamp columns, which insert_all auto-populates regardless of row content) so
+    # attributes_to_copy has something meaningful to carry forward in this spec.
+    ActiveRecord::Base.connection.execute(
+      "ALTER TABLE my_active_record_model_transitions ADD COLUMN extra_data text",
+    )
+    MyActiveRecordModelTransition.reset_column_information
+  end
+
+  let(:machine_class) { MyStateMachine }
+
+  # How a non-current row's most_recent is stored: NULL when the column is nullable
+  # (needed for the unique index on databases without partial indexes, e.g. MySQL),
+  # false otherwise - same as the single-transition path.
+  def not_most_recent_value
+    MyActiveRecordModelTransition.columns_hash["most_recent"].null ? nil : false
+  end
+
+  def create_model(initial_state: "initial", extra_data: nil)
+    model = MyActiveRecordModel.create!
+    model.my_active_record_model_transitions.create!(
+      to_state: initial_state, sort_key: 10, most_recent: true, metadata: {},
+      extra_data: extra_data
+    )
+    model
+  end
+
+  def last_transition_for(id)
+    MyActiveRecordModel.find(id).my_active_record_model_transitions.order(:sort_key).last
+  end
+
+  describe "#call!" do
+    it "transitions only the parents currently in the from state" do
+      in_initial = Array.new(3) { create_model.id }
+      in_succeeded = create_model(initial_state: "succeeded").id
+
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      transitioned = bulk.call!(in_initial + [in_succeeded], metadata: { "foo" => "bar" })
+
+      expect(transitioned).to match_array(in_initial)
+    end
+
+    it "raises TransitionConflictError and rolls the whole batch back on a conflicting row" do
+      ok = create_model.id
+      conflicted = create_model.id
+      # An out-of-band row occupying the sort_key the new transition would take.
+      MyActiveRecordModelTransition.create!(
+        my_active_record_model_id: conflicted, to_state: "failed", sort_key: 20,
+        most_recent: not_most_recent_value, metadata: {}
+      )
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      expect { bulk.call!([ok, conflicted]) }.to raise_error(Statesman::TransitionConflictError)
+
+      expect(MyActiveRecordModelTransition.where(my_active_record_model_id: [ok, conflicted], most_recent: true).
+        pluck(:to_state)).to eq(%w[initial initial])
+    end
+
+    it "marks flipped rows as not current the same way the single path does" do
+      ids = Array.new(2) { create_model.id }
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      bulk.call!(ids)
+
+      old_rows = MyActiveRecordModelTransition.where(my_active_record_model_id: ids, to_state: "initial")
+
+      expect(old_rows.map(&:most_recent)).to all(eq(not_most_recent_value))
+      expect(MyActiveRecordModelTransition.where(my_active_record_model_id: ids, most_recent: true).count).
+        to eq(ids.size)
+    end
+
+    it "applies the metadata and most_recent flag to each transitioned parent" do
+      in_initial = Array.new(3) { create_model.id }
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      bulk.call!(in_initial, metadata: { "foo" => "bar" })
+
+      MyActiveRecordModel.where(id: in_initial).each do |model|
+        last = model.my_active_record_model_transitions.order(:sort_key).last
+        expect(last.to_state).to eq("succeeded")
+        expect(last.most_recent).to be(true)
+        expect(last.metadata).to eq({ "foo" => "bar" })
+      end
+    end
+
+    it "leaves parents not currently in the from state untouched" do
+      in_succeeded = create_model(initial_state: "succeeded").id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      bulk.call!([in_succeeded], metadata: { "foo" => "bar" })
+
+      expect(last_transition_for(in_succeeded).sort_key).to eq(10)
+    end
+
+    it "is idempotent - re-running skips parents no longer in the from state" do
+      ids = Array.new(2) { create_model.id }
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      first_run = bulk.call!(ids)
+      second_run = bulk.call!(ids)
+
+      expect(first_run).to match_array(ids)
+      expect(second_run).to eq([])
+    end
+
+    it "flips the old most_recent row off and sets sort_key = old + 10" do
+      id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      bulk.call!([id])
+
+      transitions = MyActiveRecordModel.find(id).
+        my_active_record_model_transitions.order(:sort_key)
+      expect(transitions.map(&:most_recent)).to eq([not_most_recent_value, true])
+      expect(transitions.map(&:sort_key)).to eq([10, 20])
+    end
+
+    it "carries forward only explicitly requested attributes_to_copy" do
+      id = create_model(extra_data: "keep-me").id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      bulk.call!([id], attributes_to_copy: ["extra_data"])
+
+      expect(last_transition_for(id).extra_data).to eq("keep-me")
+    end
+
+    it "does not carry forward attributes that weren't requested" do
+      id = create_model(extra_data: "should-not-persist").id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      bulk.call!([id]) # no attributes_to_copy
+
+      expect(last_transition_for(id).extra_data).to be_nil
+    end
+
+    describe "flip query RETURNING clause" do
+      def flip_sql_for(bulk, id, **options)
+        statements = []
+        subscriber = ->(*, payload) do
+          statements << payload[:sql] if /\AUPDATE\s+"?my_active_record_model_transitions/i.match?(payload[:sql])
+        end
+        ActiveSupport::Notifications.subscribed(subscriber, "sql.active_record") do
+          bulk.call!([id], **options)
+        end
+        statements.find { |sql| sql.include?(" RETURNING ") }
+      end
+
+      let(:bulk) do
+        described_class.new(
+          model_class: MyActiveRecordModel, machine_class: machine_class,
+          from: :initial, to: :succeeded
+        )
+      end
+
+      it "returns only the carried columns, not *" do
+        skip "RETURNING is PostgreSQL-only" unless postgres? # rubocop:disable RSpec/Pending
+        id = create_model(extra_data: "x").id
+        sql = flip_sql_for(bulk, id, attributes_to_copy: ["extra_data"])
+        returning = sql[/RETURNING (.*)\z/m, 1]
+
+        expect(sql).to_not include("RETURNING *")
+        expect(returning.split(", ")).to contain_exactly(
+          '"my_active_record_model_id"', '"sort_key"', '"extra_data"'
+        )
+      end
+
+      it "does not return columns that were not requested" do
+        skip "RETURNING is PostgreSQL-only" unless postgres? # rubocop:disable RSpec/Pending
+        id = create_model(extra_data: "x").id
+        sql = flip_sql_for(bulk, id, attributes_to_copy: [])
+
+        expect(sql[/RETURNING (.*)\z/m, 1]).to_not include("extra_data")
+      end
+    end
+
+    it "raises ValidationError for unknown attributes_to_copy columns" do
+      id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      expect do
+        bulk.call!([id], attributes_to_copy: ["not_a_real_column"])
+      end.to raise_error(Statesman::BulkTransition::ValidationError, /not_a_real_column/)
+    end
+
+    it "raises InvalidTransitionError for a from/to pair the machine doesn't allow" do
+      expect do
+        described_class.new(
+          model_class: MyActiveRecordModel, machine_class: machine_class,
+          from: :succeeded, to: :succeeded
+        )
+      end.to raise_error(Statesman::InvalidTransitionError)
+    end
+
+    it "runs the block inside the transaction and rolls back everything if it raises" do
+      id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      expect do
+        bulk.call!([id]) { |_rows| raise "boom" }
+      end.to raise_error("boom")
+
+      last = last_transition_for(id)
+      expect(last.to_state).to eq("initial")
+      expect(last.most_recent).to be(true)
+    end
+
+    it "matches per-parent overrides by the string form of the id" do
+      id = create_model(extra_data: "from-previous-row").id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      bulk.call!(
+        [id],
+        metadata_per_id: { id.to_s => { "origin" => "api" } },
+        attributes_to_copy: ["extra_data"],
+        attributes_per_id: { id.to_s => { extra_data: "looked-up-value" } },
+      )
+
+      expect(last_transition_for(id).metadata).to eq({ "origin" => "api" })
+      expect(last_transition_for(id).extra_data).to eq("looked-up-value")
+    end
+
+    it "raises ValidationError for attributes_per_id columns not in attributes_to_copy" do
+      id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      expect do
+        bulk.call!([id], attributes_per_id: { id => { "extra_data" => "x" } })
+      end.to raise_error(Statesman::BulkTransition::ValidationError, /extra_data/)
+    end
+
+    it "yields a relation over the inserted transitions to the block" do
+      id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      yielded = nil
+      bulk.call!([id]) { |transitions| yielded = transitions.pluck(:my_active_record_model_id, :to_state) }
+
+      expect(yielded).to eq([[id, "succeeded"]])
+    end
+
+    it "invokes a callback object's #call via normal method dispatch, not bare yield" do
+      id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      callback = ->(_rows) {}
+
+      expect(callback).to receive(:call).once.and_call_original
+
+      bulk.call!([id], &callback)
+    end
+
+    it "returns an empty array and does nothing for an empty id list" do
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      expect(bulk.call!([])).to eq([])
+    end
+
+    it "overrides metadata per-parent via metadata_per_id, falling back to the uniform metadata" do
+      overridden_id = create_model.id
+      default_id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      bulk.call!(
+        [overridden_id, default_id],
+        metadata: { "origin" => "gocardless" },
+        metadata_per_id: { overridden_id => { "origin" => "api" } },
+      )
+
+      expect(last_transition_for(overridden_id).metadata).to eq({ "origin" => "api" })
+      expect(last_transition_for(default_id).metadata).to eq({ "origin" => "gocardless" })
+    end
+
+    it "overrides a copied attribute per-parent via attributes_per_id" do
+      overridden_id = create_model(extra_data: "from-previous-row").id
+      default_id = create_model(extra_data: "from-previous-row").id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      bulk.call!(
+        [overridden_id, default_id],
+        attributes_to_copy: ["extra_data"],
+        attributes_per_id: { overridden_id => { "extra_data" => "looked-up-value" } },
+      )
+
+      expect(last_transition_for(overridden_id).extra_data).to eq("looked-up-value")
+      expect(last_transition_for(default_id).extra_data).to eq("from-previous-row")
+    end
+
+    it "yields only the new transitions, with their final most_recent state" do
+      id = create_model.id
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+
+      yielded = nil
+      bulk.call!([id]) { |transitions| yielded = transitions.pluck(:to_state, :most_recent) }
+
+      expect(yielded).to eq([["succeeded", true]])
+    end
+  end
+
+  describe "cached_current_state integration" do
+    it "bulk-updates the cached column for every transitioned parent" do
+      ids = Array.new(2) { create_model.id }
+      bulk = described_class.new(
+        model_class: MyActiveRecordModel, machine_class: machine_class,
+        from: :initial, to: :succeeded
+      )
+      bulk.call!(ids)
+
+      MyActiveRecordModel.where(id: ids).each do |model|
+        expect(model.cached_current_state).to eq("succeeded")
+      end
+    end
+  end
+end

data/spec/support/database_container.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "testcontainers/mysql"
+require "testcontainers/postgres"
+
+# Starts a throwaway database in Docker so the suite can run against PostgreSQL or
+# MySQL locally without a pre-provisioned server.
+module DatabaseContainer
+  DEFAULT_IMAGES = {
+    "postgres" => "postgres:17",
+    "mysql" => "mysql:8.4",
+  }.freeze
+
+  def self.start(db, image: nil)
+    image ||= DEFAULT_IMAGES.fetch(db) do
+      raise ArgumentError, "Unsupported DB '#{db}', expected one of: " \
+                           "#{DEFAULT_IMAGES.keys.join(', ')}"
+    end
+
+    container = build(db, image)
+    container.start
+    at_exit { container.remove(force: true) }
+
+    database_url(container)
+  end
+
+  def self.build(db, image)
+    case db
+    when "postgres" then Testcontainers::PostgresContainer.new(image)
+    when "mysql" then Testcontainers::MysqlContainer.new(image)
+    end
+  end
+
+  def self.database_url(container)
+    if container.is_a?(Testcontainers::MysqlContainer)
+      container.database_url(protocol: "mysql2")
+    else
+      container.database_url
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 13.3.0
+  version: 13.4.0
 platform: ruby
 authors:
 - GoCardless
@@ -25,6 +25,7 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".ruby-version"
+- ".tool-versions"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - Gemfile
@@ -47,6 +48,7 @@ files:
 - lib/statesman/adapters/memory.rb
 - lib/statesman/adapters/memory_transition.rb
 - lib/statesman/adapters/type_safe_active_record_queries.rb
+- lib/statesman/bulk_transition.rb
 - lib/statesman/callback.rb
 - lib/statesman/config.rb
 - lib/statesman/exceptions.rb
@@ -70,6 +72,7 @@ files:
 - spec/statesman/adapters/memory_transition_spec.rb
 - spec/statesman/adapters/shared_examples.rb
 - spec/statesman/adapters/type_safe_active_record_queries_spec.rb
+- spec/statesman/bulk_transition_spec.rb
 - spec/statesman/callback_spec.rb
 - spec/statesman/config_spec.rb
 - spec/statesman/exceptions_spec.rb
@@ -77,6 +80,7 @@ files:
 - spec/statesman/machine_spec.rb
 - spec/statesman/utils_spec.rb
 - spec/support/active_record.rb
+- spec/support/database_container.rb
 - spec/support/exactly_query_databases.rb
 - spec/support/generators_shared_examples.rb
 - statesman.gemspec