README.md in lhm-1.3.0 vs README.md in lhm-2.0.0
- old
+ new
@@ -1,6 +1,6 @@
-# Large Hadron Migrator [][4]
+# Large Hadron Migrator [![Build Status][5]][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
changes is fast and easy.
@@ -43,17 +43,20 @@
## Requirements
Lhm currently only works with MySQL databases and requires an established
ActiveRecord or DataMapper connection.
-It is compatible and [continuously tested][4] with Ruby 1.8.7 and Ruby 1.9.x,
+It is compatible and [continuously tested][4] with MRI 1.9.x,
ActiveRecord 2.3.x and 3.x (mysql and mysql2 adapters), as well as DataMapper
1.2 (dm-mysql-adapter).
Lhm also works with dm-master-slave-adapter, it'll bind to the master before
running the migrations.
+The test suite is also run against MRI 2.0.0 in Continuous Integration, but
+there are a few bugs left to fix.
+
## Limitations
Lhm requires a monotonically increasing numeric Primary Key on the table, due to how
the Chunker works.
@@ -141,26 +144,61 @@
## Table rename strategies
There are two different table rename strategies available: LockedSwitcher and
AtomicSwitcher.
-The LockedSwitcher strategy locks the table being migrated and issues two ALTER TABLE statements.
+The LockedSwitcher strategy locks the table being migrated and issues two ALTER TABLE statements.
The AtomicSwitcher uses a single atomic RENAME TABLE query and is the favored solution.
-Lhm chooses AtomicSwitcher if no strategy is specified, **unless** your version of MySQL is
-affected by [binlog bug #39675](http://bugs.mysql.com/bug.php?id=39675). If your version is
-affected, Lhm will raise an error if you don't specify a strategy. You're recommended
-to use the LockedSwitcher in these cases to avoid replication issues.
+Lhm chooses AtomicSwitcher if no strategy is specified, **unless** your version of MySQL is
+affected by [binlog bug #39675](http://bugs.mysql.com/bug.php?id=39675). If your version is
+affected, Lhm will raise an error if you don't specify a strategy. You're recommended
+to use the LockedSwitcher in these cases to avoid replication issues.
To specify the strategy in your migration:
```ruby
Lhm.change_table :users, :atomic_switch => true do |m|
# ...
end
```
+## Limiting the data that is migrated
+
+For instances where you want to limit the data that is migrated to the new
+table by some conditions, you may tell the migration to filter by a set of
+conditions:
+
+```ruby
+Lhm.change_table(:sounds) do |m|
+ m.filter("inner join users on users.`id` = sounds.`user_id` and sounds.`public` = 1")
+end
+```
+
+Note that this SQL will be inserted into the copy directly after the "from"
+statement - so be sure to use inner/outer join syntax and not cross joins. These
+conditions will not affect the triggers, so any modifications to the table
+during the run will happen on the new table as well.
+
+## Cleaning up after an interrupted Lhm run
+
+If an Lhm migration is interrupted, it may leave behind the temporary tables
+used in the migration. If the migration is re-started, the unexpected presence
+of these tables will cause an error. In this case, `Lhm.cleanup` can be used
+to drop any orphaned Lhm temporary tables.
+
+To see what Lhm tables are found:
+
+```ruby
+Lhm.cleanup
+```
+
+To remove any Lhm tables found:
+```ruby
+Lhm.cleanup(true)
+```
+
## Contributing
We'll check out your contribution if you:
* Provide a comprehensive suite of tests for your fork.
@@ -182,6 +220,7 @@
[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
+[4]: https://travis-ci.org/soundcloud/lhm
+[5]: https://travis-ci.org/soundcloud/lhm.png?branch=master