Percona's pt-online-schema-change runner for ActiveRecord migrations
Ruby Shell
Latest commit 9b0728e Feb 18, 2017 @sauloperez sauloperez committed on GitHub Merge pull request #44 from redbooth/install-cpan-modules
Show how to install DBI and DBD::mysql from cpan

Percona Migrator Build Status Code Climate

Percona Migrator is an ActiveRecord connection adapter that allows running MySQL online and non-blocking DDL through ActiveRecord::Migration without needing to use a different DSL other than Rails' migrations DSL.

It uses pt-online-schema-change command-line tool of Percona Toolkit which runs MySQL alter table statements without downtime.


Percona Migrator relies on pt-online-schema-change from Percona Toolkit


brew install percona-toolkit

If when running a migration you see an error like:

PerconaMigrator::Error: Cannot connect to MySQL: Cannot connect to MySQL because
the Perl DBI module is not installed or not found.

You also need to install the DBI and DBD::MySQL modules from cpan.

$ sudo cpan
cpan> install DBI
cpan> install DBD::mysql


Ubuntu/Debian based

apt-get install percona-toolkit

Arch Linux

pacman -S percona-toolkit perl-dbd-mysql

Other distros

For other Linux distributions check out the Percona Toolkit download page to find the package that fits your distribution.

You can also get it from Percona's apt repository

Once installed, add this line to your application's Gemfile:

gem 'percona_migrator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install percona_migrator


Once you added it to your app's Gemfile, you can create and run Rails migrations as usual.

All the ALTER TABLE statements will be executed with pt-online-schema-change, which will provide additional output to the migration.

pt-online-schema-change arguments

You can specify any pt-online-schema-change arguments when running the migration. All what you pass in the PERCONA_ARGS env var, will be bypassed to the binary, overwriting any default values. Note the format is the same as in pt-online-schema-change. Check the full list in Percona Toolkit documentation

$ PERCONA_ARGS='--chunk-time=1' bundle exec rake db:migrate:up VERSION=xxx

or even mulitple arguments

$ PERCONA_ARGS='--chunk-time=1 --critical-load=55' bundle exec rake db:migrate:up VERSION=xxx

This however, only works for db:migrate:up or db:migrate:down rake tasks and not with db:migrate. The settings you provide can't be generalized as these vary depending on the database table and the kind of changes you apply.

LHM support

If you moved to Soundcloud's Lhm already, we got you covered. Percona Migrator overrides Lhm's DSL so that all the alter statements also go through pt-online-schema-change as well.

You can keep your Lhm migrations and start using Rails migration's DSL back again in your next migration.


You can override any of the default values from an initializer:

PerconaMigrator.configure do |config|
  config.tmp_path = '/tmp/'

It's strongly recommended to name it after this gems name, such as config/initializers/percona_migrator.rb

How it works

When booting your Rails app, Percona Migrator extends the ActiveRecord::Migration#migrate method to reset the connection and reestablish it using the PerconaAdapter instead of the one you defined in your config/database.yml.

Then, when any migration DSL methods such as add_column or create_table are executed, they all go to the PerconaAdapter. There, the methods that require ALTER TABLE SQL statements, like add_column, are overriden to get executed with PerconaMigrator::Runner, which deals with the pt-online-schema-change binary. All the others, like create_table, are delegated to the ActiveRecord's built in Mysql2Adapter and so they follow the regular path.

PerconaMigrator::Runner spawns a new process that runs the pt-online-schema-change binary present in the system, with the apropriate arguments for the generated SQL.

When an any error occurs, an ActiveRecord::StatementInvalid exception is raised and the migration is aborted, as all other ActiveRecord connection adapters.


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


Bug reports and pull requests are welcome on GitHub at They need to be opened against master or v3.2 only if the changes fix a bug in Rails 3.2 apps.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Check the code of conduct here


You can consult the changelog here


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