https://github.com/state-machines/state_machines-activerecord

StateMachines Active Record Integration
https://github.com/state-machines/state_machines-activerecord

Keywords

activerecord ruby state-machine

Keywords from Contributors

activejob mvc activemodel rubygem sinatra rack ruby-gem rspec rubocop background-jobs

Last synced: about 22 hours ago
JSON representation

Repository metadata

StateMachines Active Record Integration

Host: GitHub
URL: https://github.com/state-machines/state_machines-activerecord
Owner: state-machines
License: mit
Created: 2015-01-06T15:29:46.000Z (about 11 years ago)
Default Branch: master
Last Pushed: 2026-01-06T12:22:11.000Z (about 2 months ago)
Last Synced: 2026-02-24T08:42:42.346Z (7 days ago)
Topics: activerecord, ruby, state-machine
Language: Ruby
Homepage: https://github.com/state-machines/state_machines-activerecord
Size: 157 KB
Stars: 422
Watchers: 8
Forks: 83
Open Issues: 7
Releases: 4
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt

StateMachines Active Record Integration

The Active Record 7.2+ integration adds support for database transactions, automatically
saving the record, named scopes, validation errors.

Requirements

Ruby 3.2+
Rails 7.2+

Installation

Add this line to your application's Gemfile:

gem 'state_machines-activerecord'

And then execute:

$ bundle

Or install it yourself as:

$ gem install state_machines-activerecord

Usage

For the complete usage guide, see http://www.rubydoc.info/github/state-machines/state_machines-activerecord/StateMachines/Integrations/ActiveRecord

Example

class Vehicle < ApplicationRecord
  state_machine :initial => :parked do
    before_transition :parked => any - :parked, :do => :put_on_seatbelt
    after_transition any => :parked do |vehicle, transition|
      vehicle.seatbelt = 'off'
    end
    around_transition :benchmark

    event :ignite do
      transition :parked => :idling
    end

    state :first_gear, :second_gear do
      validates :seatbelt_on, presence: true
    end
  end

  def put_on_seatbelt
    ...
  end

  def benchmark
    ...
    yield
    ...
  end
end

Scopes

Usage of the generated scopes (assuming default column state):

Vehicle.with_state(:parked)                         # also plural #with_states
Vehicle.without_states(:first_gear, :second_gear)   # also singular #without_state

Transparent Scopes

State scopes will return all records when nil is passed, making them perfect for search filters:

Vehicle.with_state(nil)                            # Returns all vehicles
Vehicle.with_state(params[:state])                 # Returns all vehicles if params[:state] is nil
Vehicle.where(color: 'red').with_state(nil)        # Returns all red vehicles (chainable)

Rails Enum Integration

When your ActiveRecord model uses Rails enums and defines a state machine on the same attribute, this gem automatically detects the conflict and provides seamless integration. This prevents method name collisions between Rails enum methods and state machine methods.

Auto-Detection and Conflict Resolution

class Order < ApplicationRecord
  # Rails enum definition
  enum :status, { pending: 0, processing: 1, completed: 2, cancelled: 3 }
  
  # State machine on the same attribute
  state_machine :status do
    state :pending, :processing, :completed, :cancelled
    
    event :process do
      transition pending: :processing
    end
    
    event :complete do
      transition processing: :completed
    end
    
    event :cancel do
      transition [:pending, :processing] => :cancelled
    end
  end
end

When enum integration is detected, the gem automatically:

Preserves original Rails enum methods (pending?, processing?, etc.)
Generates prefixed state machine methods to avoid conflicts (status_pending?, status_processing?, etc.)
Creates prefixed scope methods (Order.status_pending, Order.status_processing, etc.)

Available Methods

Original Rails enum methods (preserved):

order = Order.create(status: :pending)
order.pending?        # => true (Rails enum method)
order.processing?     # => false (Rails enum method)
order.processing!     # Sets status to :processing (Rails enum method)

Order.pending         # Rails enum scope
Order.processing      # Rails enum scope

Generated state machine methods (prefixed):

# Predicate methods
order.status_pending?     # => true (state machine method)
order.status_processing?  # => false (state machine method)
order.status_completed?   # => false (state machine method)

# Bang methods (for conflict resolution only)
# These are placeholders and raise runtime errors
order.status_processing!  # => raises RuntimeError

# Scope methods  
Order.status_pending      # State machine scope
Order.status_processing   # State machine scope
Order.not_status_pending  # Negative state machine scope

Introspection API

The integration provides a comprehensive introspection API for advanced use cases:

machine = Order.state_machine(:status)

# Check if enum integration is enabled
machine.enum_integrated?  # => true

# Get the Rails enum mapping
machine.enum_mapping     # => {"pending"=>0, "processing"=>1, "completed"=>2, "cancelled"=>3}

# Get original Rails enum methods that were preserved
machine.original_enum_methods
# => ["pending?", "processing?", "completed?", "cancelled?", "pending!", "processing!", ...]

# Get state machine methods that were generated
machine.state_machine_methods  
# => ["status_pending?", "status_processing?", "status_completed?", "status_cancelled?", ...]

Requirements for Enum Integration

The state machine attribute must match an existing Rails enum attribute
Auto-detection is enabled by default when this condition is met

Configuration Options

The enum integration supports several configuration options:

prefix (default: true) - Adds a prefix to generated methods to avoid conflicts
suffix (default: false) - Alternative naming strategy using suffixes instead of prefixes
scopes (default: true) - Controls whether state machine scopes are generated

State driven validations

As mentioned in StateMachines::Machine#state, you can define behaviors,
like validations, that only execute for certain states. One important
caveat here is that, due to a constraint in ActiveRecord's validation
framework, custom validators will not work as expected when defined to run
in multiple states. For example:

class Vehicle < ApplicationRecord
  state_machine do
    state :first_gear, :second_gear do
      validate :speed_is_legal
    end
  end
end

In this case, the :speed_is_legal validation will only get run
for the :second_gear state. To avoid this, you can define your
custom validation like so:

class Vehicle < ApplicationRecord
  state_machine do
    state :first_gear, :second_gear do
      validate {|vehicle| vehicle.speed_is_legal}
    end
  end
end

Contributing

Fork it ( https://github.com/state-machines/state_machines-activerecord/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Owner metadata

Name: State Machines
Login: state-machines
Email:
Kind: organization
Description:
Website:
Location: Antarctica
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/7613709?v=4
Repositories: 11
Last ynced at: 2023-09-07T15:13:42.457Z
Profile URL: https://github.com/state-machines

GitHub Events

Total

Release event: 2
Delete event: 8
Pull request event: 22
Fork event: 1
Issues event: 4
Watch event: 17
Issue comment event: 15
Push event: 32
Pull request review comment event: 7
Pull request review event: 13
Create event: 13

Last Year

Release event: 2
Delete event: 8
Pull request event: 22
Fork event: 1
Issues event: 4
Watch event: 14
Issue comment event: 15
Push event: 32
Pull request review comment event: 7
Pull request review event: 13
Create event: 13

Committers metadata

Last synced: 5 days ago

Total Commits: 96
Total Committers: 26
Avg Commits per committer: 3.692
Development Distribution Score (DDS): 0.677

Commits in past year: 22
Committers in past year: 4
Avg Commits per committer in past year: 5.5
Development Distribution Score (DDS) in past year: 0.409

Name	Email	Commits
Abdelkader Boudih	t**e@g**m	31
Rafael Mendonça França	r**a@g**m	16
Kevin Ross	k**s@a**m	7
github-actions[bot]	4****]	6
Washington Luiz	h**o@g**m	5
Josef Šimánek	j**k@g**m	4
John Hawthorn	j**n@s**m	3
Marius Bobin	m**n@g**m	2
Leonardo	l**o@g**m	2
Edouard CHIN	e**n@s**m	2
Olivier Lacan	hi@o****m	2
Simon Claessens	g**o@g**m	2
Carles Jove i Buxeda	h**a@c**t	1
Diego Toral	d**l@g**m	1
Dmytro Stepaniuk	s**k@m**m	1
Dusan Orlovic	d**c@g**m	1
Hisham Malik	h**m@a**m	1
Jean byroot Boussier	j**b@s**m	1
Joel Van Horn	1****h	1
Kaan Ozkan	k**n@s**m	1
Kaspar V	c****r	1
Marius Bobin	m****n	1
Olle Jonsson	o**n@g**m	1
Thomas Walpole	t**e@g**m	1
Tomasz Stachewicz	t**s@o**l	1
lulalala	m**k@g**w	1

Committer domains:

Issue and Pull Request metadata

Last synced: 7 days ago

Total issues: 60
Total pull requests: 74
Average time to close issues: about 1 year
Average time to close pull requests: 6 months
Total issue authors: 56
Total pull request authors: 34
Average comments per issue: 3.0
Average comments per pull request: 1.5
Merged pull request: 51
Bot issues: 0
Bot pull requests: 8

Past year issues: 0
Past year pull requests: 23
Past year average time to close issues: N/A
Past year average time to close pull requests: 4 days
Past year issue authors: 0
Past year pull request authors: 2
Past year average comments per issue: 0
Past year average comments per pull request: 0.65
Past year merged pull request: 18
Past year bot issues: 0
Past year bot pull requests: 8

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/state-machines/state_machines-activerecord

Top Issue Authors

codemilan (2)
mksm (2)
jeffblake (2)
rosskevin (2)
andytcox (1)
kbennoune (1)
duleorlovic (1)
JohnSmall (1)
HoneyryderChuck (1)
optimum-dulopin (1)
fredngo (1)
aripollak (1)
nir0 (1)
joelzwarrington (1)
muzfuz (1)

Top Pull Request Authors

seuros (24)
github-actions[bot] (8)
rosskevin (4)
diegotoral (3)
byroot (2)
olivierlacan (2)
joelvh (2)
duleorlovic (2)
billkauf (2)
DmytroStepaniuk (1)
casperisfine (1)
carlesjove (1)
simi (1)
Edouard-chin (1)
tomash (1)

Top Issue Labels

bug (2)
bug? (2)
question (1)

Top Pull Request Labels

autorelease: pending (5)
autorelease: tagged (3)

Package metadata

Total packages: 13
Total downloads:
- rubygems: 127,240,146 total
Total docker downloads: 868,541,566
Total dependent packages: 30 (may contain duplicates)
Total dependent repositories: 3,164 (may contain duplicates)
Total versions: 60
Total maintainers: 2

gem.coop: state_machines-activerecord

Adds support for creating state machines for attributes on ActiveRecord

Homepage: https://github.com/state-machines/state_machines-activerecord/
Documentation: http://www.rubydoc.info/gems/state_machines-activerecord/
Licenses: MIT
Latest release: 0.100.0 (published 8 months ago)
Last Synced: 2026-03-02T10:04:30.703Z (1 day ago)
Versions: 17
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 63,622,713 Total
Docker Downloads: 434,270,783
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.186%
- Docker downloads count: 0.305%
- Downloads: 0.438%
Maintainers (2)
- seuros
- rafaelfranca

rubygems.org: state_machines-activerecord

Adds support for creating state machines for attributes on ActiveRecord

Homepage: https://github.com/state-machines/state_machines-activerecord/
Documentation: http://www.rubydoc.info/gems/state_machines-activerecord/
Licenses: MIT
Latest release: 0.100.0 (published 8 months ago)
Last Synced: 2026-03-02T03:32:23.021Z (1 day ago)
Versions: 17
Dependent Packages: 30
Dependent Repositories: 3,164
Downloads: 63,617,433 Total
Docker Downloads: 434,270,783
Rankings:
- Docker downloads count: 0.36%
- Downloads: 0.473%
- Dependent repos count: 0.553%
- Dependent packages count: 0.827%
- Average: 1.329%
- Forks count: 2.866%
- Stargazers count: 2.896%
Maintainers (2)
- rafaelfranca
- seuros

proxy.golang.org: github.com/state-machines/state_machines-activerecord

Homepage:
Documentation: https://pkg.go.dev/github.com/state-machines/state_machines-activerecord#section-documentation
Licenses: mit
Latest release: v0.100.0 (published 8 months ago)
Last Synced: 2026-02-26T11:01:33.672Z (5 days ago)
Versions: 16
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 5.432%
- Average: 5.615%
- Dependent repos count: 5.797%

ubuntu-24.04: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Licenses: mit
Latest release: 0.8.0-2 (published 18 days ago)
Last Synced: 2026-02-13T01:03:29.027Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.04: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Licenses:
Latest release: 0.8.0-2 (published 20 days ago)
Last Synced: 2026-02-11T06:50:34.094Z (20 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-20.04: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Licenses:
Latest release: 0.6.0-2 (published 18 days ago)
Last Synced: 2026-02-13T07:23:26.829Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.10: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Licenses:
Latest release: 0.8.0-2 (published 18 days ago)
Last Synced: 2026-02-13T18:33:54.032Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-24.10: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Licenses:
Latest release: 0.8.0-2 (published 22 days ago)
Last Synced: 2026-02-09T17:22:36.738Z (22 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-11: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Documentation: https://packages.debian.org/bullseye/ruby-state-machines-activerecord
Licenses:
Latest release: 0.6.0-2 (published 20 days ago)
Last Synced: 2026-02-13T08:25:20.212Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-10: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Documentation: https://packages.debian.org/buster/ruby-state-machines-activerecord
Licenses:
Latest release: 0.5.1-2 (published 20 days ago)
Last Synced: 2026-02-13T04:26:24.215Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-22.04: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Licenses:
Latest release: 0.8.0-2 (published 18 days ago)
Last Synced: 2026-02-13T13:26:34.402Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-12: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Documentation: https://packages.debian.org/bookworm/ruby-state-machines-activerecord
Licenses:
Latest release: 0.8.0-2 (published 18 days ago)
Last Synced: 2026-02-12T23:42:21.276Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-13: ruby-state-machines-activerecord

Homepage: https://github.com/state-machines/state_machines-activerecord
Documentation: https://packages.debian.org/trixie/ruby-state-machines-activerecord
Licenses:
Latest release: 0.9.0-2 (published 19 days ago)
Last Synced: 2026-02-13T13:20:07.002Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

Dependencies

Gemfile rubygems

pry-byebug >= 0

state_machines-activerecord.gemspec rubygems

appraisal >= 1 development
minitest >= 5.4.0 development
minitest-reporters >= 0 development
rake ~> 13.0 development
sqlite3 ~> 1.3 development
activerecord >= 5.1
state_machines-activemodel >= 0.8.0

.github/workflows/ruby.yml actions

actions/checkout v2 composite
ruby/setup-ruby v1 composite

.github/workflows/release.yml actions

googleapis/release-please-action v4 composite

Score: 30.03859570107175

https://github.com/state-machines/state_machines-activerecord

Keywords

Keywords from Contributors

Repository metadata

README.md

StateMachines Active Record Integration

Requirements

Installation

Usage

Example

Scopes

Transparent Scopes

Rails Enum Integration

Auto-Detection and Conflict Resolution

Available Methods

Introspection API

Requirements for Enum Integration

Configuration Options

State driven validations

Contributing

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Package metadata

gem.coop: state_machines-activerecord

rubygems.org: state_machines-activerecord

proxy.golang.org: github.com/state-machines/state_machines-activerecord

ubuntu-24.04: ruby-state-machines-activerecord

ubuntu-23.04: ruby-state-machines-activerecord

ubuntu-20.04: ruby-state-machines-activerecord

ubuntu-23.10: ruby-state-machines-activerecord

ubuntu-24.10: ruby-state-machines-activerecord

debian-11: ruby-state-machines-activerecord

debian-10: ruby-state-machines-activerecord

ubuntu-22.04: ruby-state-machines-activerecord

debian-12: ruby-state-machines-activerecord

debian-13: ruby-state-machines-activerecord

Dependencies