Skip to content


Repository files navigation


Test Gem Version Discord

Handcuffs provides an easy way to run migrations in phases in your Ruby on Rails application.

To configure, first create a handcuff initializer and define a configuration

# config/initializers/handcuffs.rb

Handcuffs.configure do |config|
  config.phases = [:pre_restart, :post_restart]

Then call phase from inside your migrations

# db/migrate/20160318230933_add_on_sale_column.rb

class AddOnSaleColumn < ActiveRecord::Migration

  phase :pre_restart

  def up
    add_column :products, :on_sale, :boolean

  def down
    remove_column :products, :on_sale

# db/migrate/20160318230988_add_on_sale_index

class AddOnSaleIndex < ActiveRecord::Migration

  phase :post_restart

  def up
    add_index :products, :on_sale, algorithm: :concurrently

  def down
    remove_index :products, :on_sale


You can then run your migrations in phases using

rake 'handcuffs:migrate[pre_restart]'


rake 'handcuffs:migrate[post_restart]'

You can run all migrations using

rake 'handcuffs:migrate[all]'

This differs from running rake db:migrate in that migrations will be run in the order that the phases are defined in the handcuffs config.

If you run a handcuffs rake task and any migration does not have a phase defined, an error will be raised before any migrations are run. To prevent this error, you can define a default phase for migrations that don't define one.

# config/initializers/handcuffs.rb

Handcuffs.configure do |config|
  config.phases = [:pre_restart, :post_restart]
  config.default_phase = :pre_restart


Add this line to your application's Gemfile:

gem 'handcuffs'

And then execute:


Or install it yourself as:

gem install handcuffs

Running specs

The specs for handcuffs are in the dummy application at /spec/dummy/spec. The spec suite requires PostgreSQL. To run it you will have to set the environment variables POSTGRES_DB_USERNAME and POSTGRES_DB_PASSWORD. You can then run the suite using rake spec


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.

About Procore

Procore Logo

Handcuffs is maintained by Procore Technologies.

Procore - building the software that builds the world.

Learn more about the #1 most widely used construction management software at