# Handcuffs

[![Test](https://github.com/procore-oss/handcuffs/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/procore-oss/handcuffs/actions/workflows/test.yaml)
[![Gem Version](https://badge.fury.io/rb/handcuffs.svg)](https://badge.fury.io/rb/handcuffs)
[![Discord](https://img.shields.io/badge/Chat-EDEDED?logo=discord)](https://discord.gg/PbntEMmWws) 

Handcuffs provides an easy way to run migrations in phases in your [Ruby on Rails](https://rubyonrails.org/) application.

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

```ruby
# config/initializers/handcuffs.rb

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

Then call `phase` from inside your migrations

```ruby
# db/migrate/20160318230933_add_on_sale_column.rb

class AddOnSaleColumn < ActiveRecord::Migration

  phase :pre_restart

  def up
    add_column :products, :on_sale, :boolean
  end

  def down
    remove_column :products, :on_sale
  end

end
```

```ruby
# db/migrate/20160318230988_add_on_sale_index

class AddOnSaleIndex < ActiveRecord::Migration

  phase :post_restart

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

  def down
    remove_index :products, :on_sale
  end

end
```

You can then run your migrations in phases using

```bash
rake 'handcuffs:migrate[pre_restart]'
```

or

```bash
rake 'handcuffs:migrate[post_restart]'
```

You can run all migrations using

```bash
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.

```ruby
# config/initializers/handcuffs.rb

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

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'handcuffs'
```

And then execute:

```bash
bundle
```

Or install it yourself as:

```bash
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`

## Contributing

Bug reports and pull requests are welcome on GitHub at <https://github.com/procore-oss/handcuffs>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

## About Procore

<img
  src="https://www.procore.com/images/procore_logo.png"
  alt="Procore Logo"
  width="250px"
/>

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](https://www.procore.com/)