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.
pt-online-schema-change command-line tool of
which runs MySQL alter table statements without downtime.
Percona Migrator relies on
pt-online-schema-change from Percona
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
$ sudo cpan cpan> install DBI cpan> install DBD::mysql
apt-get install percona-toolkit
pacman -S percona-toolkit perl-dbd-mysql
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:
And then execute:
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.
ALTER TABLE statements will be executed with
pt-online-schema-change, which will provide additional output to the
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
$ 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:down rake tasks and
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.
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/' end
It's strongly recommended to name it after this gems name, such as
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
Then, when any migration DSL methods such as
executed, they all go to the
There, the methods that require
ALTER TABLE SQL statements, like
are overriden to get executed with
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.
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
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
https://github.com/redbooth/percona_migrator. They need to be opened against
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.