Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update readme

  • Loading branch information...
commit 22ff9e3a5e3aa6b8239463a7ab0a3ddca1366160 1 parent 3e3b48c
@grobie authored
Showing with 89 additions and 41 deletions.
  1. +85 −41 README.md
  2. +4 −0 lib/lhm/atomic_switcher.rb
View
126 README.md
@@ -1,4 +1,4 @@
-# Large Hadron Migrator [![Build Status](https://secure.travis-ci.org/soundcloud/large-hadron-migrator.png)](http://travis-ci.org/soundcloud/large-hadron-migrator)
+# Large Hadron Migrator [![Build Status](https://secure.travis-ci.org/soundcloud/large-hadron-migrator.png)][4]
Rails style database migrations are a useful way to evolve your data schema in
an agile manner. Most Rails projects start like this, and at first, making
@@ -20,7 +20,7 @@ table. The InnoDB Plugin provides facilities for online index creation, which
is great if you are using this engine, but only solves half the problem.
At SoundCloud we started having migration pains quite a while ago, and after
-looking around for third party solutions [0] [1] [2], we decided to create our
+looking around for third party solutions, we decided to create our
own. We called it Large Hadron Migrator, and it is a gem for online
ActiveRecord migrations.
@@ -31,62 +31,100 @@ ActiveRecord migrations.
## The idea
The basic idea is to perform the migration online while the system is live,
-without locking the table. In contrast to OAK (online alter table) [0] and the
-facebook tool [1], we only use a copy table and triggers.
+without locking the table. In contrast to [OAK][0] and the
+[facebook tool][1], we only use a copy table and triggers.
The Large Hadron is a test driven Ruby solution which can easily be dropped
into an ActiveRecord migration. It presumes a single auto incremented
numerical primary key called id as per the Rails convention. Unlike the
-twitter solution [2], it does not require the presence of an indexed
+[twitter solution][2], it does not require the presence of an indexed
`updated_at` column.
+## Requirements
+
+Lhm currently only works with MySQL databases and requires an established
+ActiveRecord connection.
+
+It is compatible and [continuously tested][4] with Ruby 1.8.7 and Ruby 1.9.x,
+ActiveRecord 2.3.x and 3.x as well as mysql and mysql2 adapters.
+
+## Installation
+
+Install it via `gem install lhm` or add `gem "lhm"` to your Gemfile.
+
## Usage
-You can invoke Lhm directly from a plain ruby file after connecting active
-record to your mysql instance:
+You can invoke Lhm directly from a plain ruby file after connecting ActiveRecord
+to your mysql instance:
- require 'lhm'
+```ruby
+require 'lhm'
- ActiveRecord::Base.establish_connection(
- :adapter => 'mysql',
- :host => '127.0.0.1',
- :database => 'lhm'
- )
+ActiveRecord::Base.establish_connection(
+ :adapter => 'mysql',
+ :host => '127.0.0.1',
+ :database => 'lhm'
+)
- Lhm.change_table(:users) do |m|
- m.add_column(:arbitrary, "INT(12)")
- m.add_index([:arbitrary, :created_at])
- m.ddl("alter table %s add column flag tinyint(1)" % m.name)
- end
+Lhm.change_table :users do |m|
+ m.add_column :arbitrary, "INT(12)"
+ m.add_index [:arbitrary_id, :created_at]
+ m.ddl("alter table %s add column flag tinyint(1)" % m.name)
+end
+```
To use Lhm from an ActiveRecord::Migration in a Rails project, add it to your
Gemfile, then invoke as follows:
- class MigrateUsers < ActiveRecord::Migration
-
- def self.up
- Lhm.change_table(:users) do |m|
- m.add_column(:arbitrary, "INT(12)")
- m.add_index([:arbitrary, :created_at])
- m.ddl("alter table %s add column flag tinyint(1)" % m.name)
- end
- end
-
- def self.down
- Lhm.change_table(:users) do |m|
- m.remove_index([:arbitrary, :created_at])
- m.remove_column(:arbitrary)
- end
- end
+```ruby
+require 'lhm'
+
+class MigrateUsers < ActiveRecord::Migration
+ def self.up
+ Lhm.change_table :users do |m|
+ m.add_column :arbitrary, "INT(12)"
+ m.add_index [:arbitrary_id, :created_at]
+ m.ddl("alter table %s add column flag tinyint(1)" % m.name)
+ end
+ end
+
+ def self.down
+ Lhm.change_table :users do |m|
+ m.remove_index [:arbitrary_id, :created_at]
+ m.remove_column :arbitrary)
end
+ end
+end
+```
+
+## Table rename strategies
+
+There are two different table rename strategies available: LockedSwitcher and
+AtomicSwitcher.
+
+For all setups which use replication and a MySQL version
+affected by the the [binlog bug #39675](http://bugs.mysql.com/bug.php?id=39675),
+we recommend the LockedSwitcher strategy to avoid replication issues. This
+strategy locks the table being migrated and issues two ALTER TABLE statements.
+The AtomicSwitcher uses a single atomic RENAME TABLE query and should be favored
+in setups which do not suffer from the mentioned replication bug.
+
+Lhm chooses the strategy automatically based on the used MySQL server version,
+but you can override the behavior with an option:
+
+```ruby
+Lhm.change_table :users, :atomic_switch => true do |m|
+ # ...
+end
+```
## Contributing
We'll check out your contribution if you:
-- Provide a comprehensive suite of tests for your fork.
-- Have a clear and documented rationale for your changes.
-- Package these up in a pull request.
+ * Provide a comprehensive suite of tests for your fork.
+ * Have a clear and documented rationale for your changes.
+ * Package these up in a pull request.
We'll do our best to help you out with any contribution issues you may have.
@@ -94,9 +132,15 @@ We'll do our best to help you out with any contribution issues you may have.
The license is included as LICENSE in this directory.
-## Footnotes
+## Similar solutions
-[0]: http://openarkkit.googlecode.com "OAK online alter table"
-[1]: http://www.facebook.com/note.php?note\_id=430801045932 "Facebook"
-[2]: https://github.com/freels/table\_migrator "Twitter"
+ * [OAK: online alter table][0]
+ * [Facebook][1]
+ * [Twitter][2]
+ * [pt-online-schema-change][3]
+[0]: http://openarkkit.googlecode.com
+[1]: http://www.facebook.com/note.php?note\_id=430801045932
+[2]: https://github.com/freels/table_migrator
+[3]: http://www.percona.com/doc/percona-toolkit/2.1/pt-online-schema-change.html
+[4]: http://travis-ci.org/soundcloud/large-hadron-migrator
View
4 lib/lhm/atomic_switcher.rb
@@ -7,6 +7,10 @@
module Lhm
# Switches origin with destination table using an atomic rename.
+ #
+ # It should only be used if the MySQL server version is not affected by the
+ # bin log affecting bug #39675. This can be verified using
+ # Lhm::SqlHelper.supports_atomic_switch?.
class AtomicSwitcher
include Command
include SqlHelper
Please sign in to comment.
Something went wrong with that request. Please try again.