pt-online-schema-change migrations

Runs regular Rails/ActiveRecord migrations via the Percona Toolkit pt-online-schema-change tool.

WARNING: I am not actively contributing this project any more.
PRs to fix bugs and add features are welcome, but do not expect feature requests to go answered.

Installation

Add this line to your application's Gemfile:

gem 'pt-osc'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pt-osc

Usage

Set your database adapter to be mysql_pt_osc in your application's database.yml. Specify pt-online-schema-change flags in a percona hash in the config. e.g.

environment:
  host: localhost
  username: root
  database: rails
  percona:
    defaults-file: /etc/mysql/percona-user.cnf
    recursion-method: "'dsn=D=percona,t=slaves'"

Additional/modified options for the percona hash include:

• defaults-file: Can be specified as an absolute path (with leading /) or relative (without). Relative paths will be treated as relative to your project's working directory.
• check-alter: When set to false, ALTER commands will not be checked when executing (same as --no-check-alter)
• run_mode: Specify 'execute' to actually run pt-online-schema-change when the migration runs. Specify 'print' to output the commands to run to STDOUT instead. Default is 'print'.
• log: Specify the file used for logging activity. Can be a relative or absolute path.
• user: By default, the command will use the username given in your standard database config. Specify a username here to override. Specify false to omit username (such as when using a defaults-file.
• password: By default, the command will use the password given in your standard database config. Specify a password here to override. Specify false to omit password (such as when using a defaults-file.

Migrations

To run migrations with pt-online-schema-change, you need to explicitly opt them in by changing their parent class to ActiveRecord::PtOscMigration. For instance, if your migration was

class CreateTeams < ActiveRecord::Migration

you should change it to

class CreateTeams < ActiveRecord::PtOscMigration

If you have migrations that you do not want to be run with pt-online-schema-change, leave the same parent class and they will be run normally.

Caveats

This gem is not considered production ready. There will be bugs.

Requirements and Compatibility

ActiveRecord

• ~> 3.2
• ~> 3.2

Ruby

• Ruby 1.9.3
• Ruby 2.0.0
• Ruby 2.1.2
• Ruby 2.1 latest

Percona Toolkit

• 2.2 branch (latest)
• 2.1 branch (latest)
• does not work with 2.0 or 1.0 branches

Support for other versions of these tools is unknown and not guaranteed.

pt-osc requires the use of pt-online-schema-change 2.0 or later. Some options may not work with all versions.

pt-osc is compatible with versions 0.5.0 and later of zdennis/activerecord-import. It will not work with earlier versions.

Testing

create a machine for pt-osc, this should only be needed once

docker-machine create pt-osc --driver virtualbox

every new shell that needs to access pt-osc within docker needs to run:

eval $(docker-machine env pt-osc)

to access the docker shell

docker-compose run pt-osc bash

useful commands in docker shell

create the initial database within mysql for tests, only needed once

bundle exec rake db:test_create

run the tests in docker

bundle exec rake