Birdspotting

Some add-ons on ActiveRecord::Migration to make migration safer in the context of zero downtime deployment.

Installation

Add this line to your application's Gemfile:

gem 'birdspotting'

And then execute:

$ bundle

Or install it yourself as:

$ gem install birdspotting

Usage

Configuration

You can configure the gem (for instance by creating a config/initializers/birdspotting.rb) with the following options (here with the default values):

Birdspotting.configure do |config|
    config.start_check_at_version    = nil
    config.check_bypass_env_var      = "BYPASS_SCHEMA_STATEMENTS_CHECK"

    config.add_column_position_check = true

    config.encoding_check            = true
    config.encoding_check_message    = "\n/!\\ You are dealing with a %<type>s field" \
    "(%<column_name>s): did you think about emojis and used the appropriate encoding? /!\\ \n\n"

    config.rename_column_check       = true
    config.rename_column_message     = "Don't use rename_column! https://stackoverflow.com/a/18542147"

    config.remove_column_check        = true
end

Common configuration

start_check_at_version allows to start the checks after some migration version only. Set it to a migration timestamp like 20151209000000 for instance. When nil, all migrations will be checked.

check_bypass_env_var specify the ENV var allowing to bypass the checks. Use it to bypass temporarily all the checks so you do it intentionally. You can set it to any value, it's just testing it's set.

For instance if check_bypass_env_var is set to BYPASS_SCHEMA_STATEMENTS_CHECK (the default) you can do:

BYPASS_SCHEMA_STATEMENTS_CHECK=true rails db:migrate:up VERSION=20180806142044

add_column request position

We like to keep or columns organised for the case where we don't use the ORM but some other client.

This will raise a Birdspotting::ColumnPositionMissingError error if neither :first or :after is in the add_columns option.

You can skip this validation by setting add_column_position_check to false.

add_column encoding warning

This will add a warning when adding a string (or text) column to warn us to think about encoding issues. Like do we want to support emojis, or unusual characters?

You can skip this validation by setting encoding_check to false. You can customise the warning message by using the encoding_check_message setting.

rename_column

By default, we don't want to use the rename column possibility as it will break any live application. And we want to be able to release and run migration without downtime. Though when a rename_column is used, it will raise a Birdspotting::RenameColumnForbiddenError.

You can skip this validation by setting rename_column_check to false. You can customise the warning message by using the rename_column_message setting. You might like to customize the warning message to be a link to an internal set of instructions for the correct way to do this.

remove_column

By default, we don't want to be able to remove a columns which is still in use by a the application.

Thus we check if the column is still present in the columns list.

• If we are not able to find the model, we issue a Birdspotting::ModelNotFoundError.
• If the column is still present in the model, we issue a Birdspotting::RemoveColumnForbiddenError.

We advise to set the column in the ignored_columns of the model. (See this blog article)

You can skip this validation by setting remove_column_check to false.

reorder_columns [mySql only]

As said above, we like to keep or columns organised for the case where we don't use the ORM but some other client.

This helper allow to reorder all the columns of a table.

Usage:

class ReorderPostsColumns < ActiveRecord::Migration[5.2]
  include Birdspotting::ReorderColumns

  def change
    reorder_columns_for :posts, %i{
      id
      author
      body
      subject
      posted_at
      created_at
      updated_at
    }
  end
end

CAVEAT:

• All columns must be passed in parameters (or it will raise a Birdspotting::MismatchedColumnsError).
• For now, it only works on mysql (or it will raise a Birdspotting::UnsupportedAdapterError).

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/drivy/birdspotting. 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.

License

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

Code of Conduct

Everyone interacting in the Birdspotting project’s codebases and issue trackers is expected to follow the code of conduct.