A Ruby gem for running Active Record migrations in phases
Ruby HTML CSS JavaScript Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin Initial Commit - 1.0.0 May 3, 2016
lib Bump version to 1.2.0 Dec 13, 2016
.gitignore Remove empty .ruby-version and gitignore it May 4, 2017
Appraisals Support Rails 5.1 May 4, 2017
Gemfile Initial Commit - 1.0.0 May 3, 2016
README.md Docs: Wrap handcuffs commands in quotes Apr 27, 2017
circle.yml Support Rails 5 (#10) Dec 13, 2016
handcuffs.gemspec Support Rails 5 (#10) Dec 13, 2016



Circle CI

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_column :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 specs 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:

$ bundle

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 https://github.com/procore/handcuffs. 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 procore.com