mongoid_lazy_migration 0.2 → 0.2.1

data/README.md

@@ -1,7 +1,7 @@
 Mongoid Lazy Migration
 ======================
 
-![Build Status](https://secure.travis-ci.org/nviennot/mongoid_lazy_migration.png?branch=master)
+[![Build Status](https://secure.travis-ci.org/nviennot/mongoid_lazy_migration.png?branch=master)](http://travis-ci.org/nviennot/mongoid_lazy_migration)
 
 LazyMigration allows you to migrate your document on the fly.
 The migration is run when an instance of your model is initialized.
@@ -52,9 +52,8 @@ A document migration goes through the following states:
 
 ### Atomic Migration Example
 
-Suppose we have a model `GroupOfPeople` with two fields: `num_males` and
-`num_females`.
-We wish to add a field `num_people`. Here is how it goes:
+Suppose we have a model GroupOfPeople with two fields: num_males and
+num_females. We wish to add a field num_people. Here is how it goes:
 
 ```ruby
 class GroupOfPeople
@@ -75,7 +74,7 @@ class GroupOfPeople
 end
 ```
 
-Note that calling `inc_num_people` is perfectly fine in presence of contention
+Note that calling inc_num_people is perfectly fine in presence of contention
 because only one client will be able to commit the migration to the database.
 
 Locked Mode
@@ -98,15 +97,16 @@ Because of the locking, a locked migration runs slower than an atomic one.
 ### Migration States
 
 A document migration goes through the following states:
+
 1. pending: the migration needs to be performed.
 2. processing: the document is being migrated, blocking other clients.
 3. done: the migration is complete.
 
 ### Locked Migration Example
 
-Suppose we have a model `GroupOfPeople` with an array `people_names`, which is
-an array of strings. Our migration consists of introducing a new model `Person`,
-and removing the array `people_names` from `GroupOfPeople`. Here it goes:
+Suppose we have a model GroupOfPeople with an array people_names, which is an
+array of strings. Our migration consists of introducing a new model Person, and
+removing the array people_names from GroupOfPeople. Here it goes:
 
 ```ruby
 class Person
@@ -124,7 +124,7 @@ class GroupOfPeople
   has_many :people
 
   migration(:lock => true) do
-    people.names.each do |name|
+    people_names.each do |name|
       self.people.create(:name => name)
     end
   end
@@ -134,7 +134,7 @@ end
 Since only one client can execute the migration block, we are guaranteed that
 we only create the associations once.
 
-Just to be safe, we don't unset the `people_names` in the migration. It would
+Just to be safe, we don't unset the people_names in the migration. It would
 be done manually once the migration is complete.
 
 Background Migration
@@ -145,17 +145,24 @@ migrate the rest of the collection in the background.
 
 It can be done programmatically:
 
-* `Mongoid::LazyMigration.migrate` will migrate all the models that have a
-  migration block.
-* `Mongoid::LazyMigration.migrate(Model)` will only migrate `Model`.
-* `Mongoid::LazyMigration.migrate(Model.where(:active => true))` will only
-  migrate the active models.
+```ruby
+# migrate all the models that have a migration block.
+Mongoid::LazyMigration.migrate
 
-A rake task is provided to call the migrate() method:
+# migrate only Model.
+Mongoid::LazyMigration.migrate(Model)
 
-* `rake db:mongoid:migrate`
-* `rake db:mongoid:migrate[Model]`
-* `rake db:mongoid:migrate[Model.where(:active => true)]`
+# migrate only active documents of Model.
+Mongoid::LazyMigration.migrate(Model.where(:active => true))
+```
+
+A rake task is provided wrapping the migrate method:
+
+```ruby
+rake db:mongoid:migrate
+rake db:mongoid:migrate[Model]
+rake db:mongoid:migrate[Model.where(:active => true)]
+```
 
 Both methods display a progress bar.
 
@@ -178,17 +185,24 @@ rake db:mongoid:migrate[User.where(:shard => 2, :active => true)]
 Cleaning up
 -----------
 
-Once all the document have their migration state equal to done, you must
-cleanup your collection (removing the migration_state field) to clear some
-database space, and to ensure that you can run a future migration.
+Once all the document have their migration state equal to done, you must do two things:
 
-The two ways to cleanup a model are:
+1. Remove the migration block from your model.
+2. Cleanup the database (removing the migration_state field) to ensure that you
+   can run a future migration.
 
-* `Mongoid::LazyMigration.cleanup(Model)`
-* `rake db:mongoid:cleanup_migration[Model]`
+The two ways to cleanup a collection are:
 
-The cleanup process will abort if any of the document migrations are still in
-the processing state, or if you haven't removed the migration block.
+```ruby
+# programmatically
+Mongoid::LazyMigration.cleanup(Model)
+
+# rake task
+rake db:mongoid:cleanup_migration[Model]
+```
+
+The cleanup process will be aborted if any of the document migrations are still
+in the processing state, or if you haven't removed the migration block.
 
 Important Considerations
 ------------------------
@@ -201,7 +215,7 @@ A couple of points that you need to be aware of:
   interacting directly with the mongo driver and bypassing mongoid, you are on
   your own.
 * If you use only() in some of your queries, make sure that you include the
-  `migration_state` field.
+  migration_state field.
 * Do not use identity maps and threads at the same time. It is currently
   unsupported, but support may be added in the future.
 * Make sure you can migrate a document quickly, because migrations will be
@@ -212,26 +226,22 @@ A couple of points that you need to be aware of:
 * The save and update callbacks will not be called when persisting the
   migration.
 * No validation will be performed during the migration.
-* The migration will not update the `updated_at` field.
-
-You can pass a criteria to `Mongoid::LazyMigration.migrate` (used at step 4
-of the recipe). It allows you to:
-
-* Update your most important document first (like your active members),
-  and do the rest after.
-* Use many workers on different shards of your database. Note that it is
-  safe to try migrating the same document by different workers, but not
-  recommended for performance reasons.
+* The migration will not update the updated_at field.
 
 Workflow
 --------
 
-You may use the following recepe to perform a migration:
+First, add the following line in your Gemfile:
+
+```ruby
+gem 'mongoid_lazy_migration'
+```
+
+Follow the following steps to perform a migration:
 
 1. Run `rake db:mongoid:cleanup[Model]` just to be safe.
-2. Include Mongoid::LazyMigration in your document and write your migration
-   specification. Modify your application code to reflect the changes from the
-   migration.
+2. Include `Mongoid::LazyMigration` in your document and write your migration.
+   Modify your application code to reflect the changes from the migration.
 3. Deploy.
 4. Run `rake db:mongoid:migrate`.
 5. Remove the migration block from your model.

data/lib/mongoid/lazy_migration/document.rb

@@ -9,7 +9,9 @@ module Mongoid::LazyMigration::Document
   end
 
   def atomic_selector
-    if @running_migrate_block && !self.class.lock_migration
+    return super unless @running_migrate_block
+
+    unless self.class.lock_migration
         raise ["You cannot save during an atomic migration,",
                "You are only allowed to set the document fields",
                "The document will be commited once the migration is complete.",

data/lib/mongoid/lazy_migration/version.rb

@@ -1,5 +1,5 @@
 module Mongoid
   module LazyMigration
-    VERSION = 0.2
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid_lazy_migration
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-09 00:00:00.000000000 Z
+date: 2012-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mongoid
@@ -66,13 +66,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/mongoid_lazy_migration.rb
 - lib/mongoid/lazy_migration/version.rb
-- lib/mongoid/lazy_migration/railtie.rb
-- lib/mongoid/lazy_migration/railtie/migrate.rake
 - lib/mongoid/lazy_migration/tasks.rb
+- lib/mongoid/lazy_migration/railtie/migrate.rake
+- lib/mongoid/lazy_migration/railtie.rb
 - lib/mongoid/lazy_migration/document.rb
 - lib/mongoid/lazy_migration.rb
-- lib/mongoid_lazy_migration.rb
 - README.md
 homepage: http://github.com/nviennot/mongoid_lazy_migration
 licenses: []