zero_downtime_migrations 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 973c17c1d4e2b556771a49e67eb41f64d22655dc
-  data.tar.gz: ffb23352741be8e007ea9b96d0aaae484480cd56
+  metadata.gz: 57fd5eb4562491e398c6357a0d13d1647e88cc34
+  data.tar.gz: a15d532d3130ace1169a5473ee5d4b0071c7945d
 SHA512:
-  metadata.gz: 841c9c76ff327639b2f233030d74cde99b7e2f8e0d40fd0b87bb4bf8f74b8fcc2127dc59ba53524adf6d7659e30b23bbd29bd54125aec89bd31c5f2892a6e8d6
-  data.tar.gz: fdcb4f80ac5f442add67e4914ab793af53e85a679f27b7c5a8ca6cf1f7c623b7fa40e660257ada0a3b364949d34e3bb85d558f426193cf1ec46c84c38f3534c2
+  metadata.gz: 970ce6605bf9fb36e7523f4819978ca02cd711b72ec43af74caa5caaebfd38072f7b5fd1a409cf3613f11c289f41f54f04321afa00c94d13556b04edf38f13a5
+  data.tar.gz: 984caa68bb7e0fe27b0d211744b8b04bad2c7dd40c6967eb4af6884a3871dba74dc3eeb5bff2dfb55e90c421c8675e54e6c894980dc19c396b545fb78b4bc340

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero_downtime_migrations (0.0.6)
+    zero_downtime_migrations (0.0.7)
       activerecord
 
 GEM

data/README.md

@@ -36,7 +36,7 @@ These exceptions display clear instructions of how to perform the same operation
 
 #### Bad
 
-This migration can potentially lock your database table!
+This can take a long time with significant database size or traffic and lock your table!
 
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
@@ -48,7 +48,7 @@ end
 
 #### Good
 
-Instead, let's first add the column without a default.
+First let’s add the column without a default. When we add a column with a default it has to lock the table while it performs an UPDATE for ALL rows to set this new default.
 
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
@@ -58,7 +58,7 @@ class AddPublishedToPosts < ActiveRecord::Migration[5.0]
 end
 ```
 
-Then set the new column default in a separate migration. Note that this does not update any existing data.
+Then we’ll set the new column default in a separate migration. Note that this does not update any existing data! This only sets the default for newly inserted rows going forward.
 
 ```ruby
 class SetPublishedDefaultOnPosts < ActiveRecord::Migration[5.0]
@@ -68,7 +68,7 @@ class SetPublishedDefaultOnPosts < ActiveRecord::Migration[5.0]
 end
 ```
 
-If necessary then backport the default value for existing data in batches. This should be done in its own migration as well.
+Finally we’ll backport the default value for existing data in batches. This should be done in its own migration as well. Updating in batches allows us to lock 1000 rows at a time (or whatever batch size we prefer).
 
 ```ruby
 class BackportPublishedDefaultOnPosts < ActiveRecord::Migration[5.0]
@@ -85,7 +85,7 @@ end
 
 #### Bad
 
-This action can potentially lock your database table while indexing all existing data!
+This action can lock your database table while indexing existing data!
 
 ```ruby
 class IndexUsersOnEmail < ActiveRecord::Migration[5.0]
@@ -99,6 +99,8 @@ end
 
 Instead, let's add the index concurrently in its own migration with the DDL transaction disabled.
 
+This allows PostgreSQL to build the index without locking in a way that prevent concurrent inserts, updates, or deletes on the table. Standard indexes lock out writes (but not reads) on the table.
+
 ```ruby
 class IndexUsersOnEmail < ActiveRecord::Migration[5.0]
   disable_ddl_transaction!
@@ -129,9 +131,9 @@ end
 
 Instead, let's split apart these types of migrations into separate files.
 
-* Introduce schema changes with methods like `create_table` or `add_column` in one file.
-* Update data with methods like `update_all` or `save` in another file.
-* Add indexes concurrently within their own file as well.
+* Introduce schema changes with methods like `create_table` or `add_column` in one file. These should be run within a DDL transaction so that they can be rolled back if there are any issues.
+* Update data with methods like `update_all` or `save` in another file. Data migrations tend to be much more error prone than changing the schema or adding indexes.
+* Add indexes concurrently within their own file as well. Indexes should be created without the DDL transaction enabled to avoid table locking.
 
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
@@ -163,7 +165,7 @@ end
 
 #### Bad
 
-The DDL transaction should only be disabled for migrations that add indexes.
+The DDL transaction should only be disabled for migrations that add indexes. All other types of migrations should keep the DDL transaction enabled so that changes can be rolled back if any unexpected errors occur.
 
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]

data/lib/zero_downtime_migrations/validation/add_column.rb

@@ -12,9 +12,12 @@ module ZeroDowntimeMigrations
         <<-MESSAGE.strip_heredoc
           Adding a column with a default is unsafe!
 
-          This action can potentially lock your database table!
+          This can take a long time with significant database
+          size or traffic and lock your table!
 
-          Instead, let's first add the column without a default.
+          First let’s add the column without a default. When we add
+          a column with a default it has to lock the table while it
+          performs an UPDATE for ALL rows to set this new default.
 
             class Add#{column_title}To#{table_title} < ActiveRecord::Migration
               def change
@@ -22,8 +25,9 @@ module ZeroDowntimeMigrations
               end
             end
 
-          Then set the new column default in a separate migration. Note that
-          this does not update any existing data.
+          Then we’ll set the new column default in a separate migration.
+          Note that this does not update any existing data! This only
+          sets the default for newly inserted rows going forward.
 
             class AddDefault#{column_title}To#{table_title} < ActiveRecord::Migration
               def change
@@ -31,8 +35,10 @@ module ZeroDowntimeMigrations
               end
             end
 
-          If necessary then backport the default value for existing data in batches.
-          This should be done in its own migration as well.
+          Finally we’ll backport the default value for existing data in
+          batches. This should be done in its own migration as well.
+          Updating in batches allows us to lock 1000 rows at a time
+          (or whatever batch size we prefer).
 
             class BackportDefault#{column_title}To#{table_title} < ActiveRecord::Migration
               def change

data/lib/zero_downtime_migrations/validation/add_index.rb

@@ -12,11 +12,15 @@ module ZeroDowntimeMigrations
         <<-MESSAGE.strip_heredoc
           Adding a non-concurrent index is unsafe!
 
-          This action can potentially lock your database table!
+          This action can lock your database table while indexing existing data!
 
           Instead, let's add the index concurrently in its own migration with
           the DDL transaction disabled.
 
+          This allows PostgreSQL to build the index without locking in a way
+          that prevent concurrent inserts, updates, or deletes on the table.
+          Standard indexes lock out writes (but not reads) on the table.
+
             class Index#{table_title}On#{column_title} < ActiveRecord::Migration
               disable_ddl_transaction!
 

data/lib/zero_downtime_migrations/validation/ddl_migration.rb

@@ -13,6 +13,8 @@ module ZeroDowntimeMigrations
           Disabling the DDL transaction is unsafe!
 
           The DDL transaction should only be disabled for migrations that add indexes.
+          All other types of migrations should keep the DDL transaction enabled so
+          that changes can be rolled back if any unexpected errors occur.
 
           Any other data or schema changes must live in their own migration files with
           the DDL transaction enabled just in case they need to be rolled back.

data/lib/zero_downtime_migrations/validation/mixed_migration.rb

@@ -14,9 +14,16 @@ module ZeroDowntimeMigrations
 
           Instead, let's split apart these types of migrations into separate files.
 
-          * Introduce schema changes with methods like `create_table` or `add_column` in one file.
+          * Introduce schema changes with methods like `create_table` or `add_column`
+            in one file. These should be run within a DDL transaction so that they
+            can be rolled back if there are any issues.
+
           * Update data with methods like `update_all` or `save` in another file.
-          * Add indexes concurrently within their own file as well.
+            Data migrations tend to be much more error prone than changing the
+            schema or adding indexes.
+
+          * Add indexes concurrently within their own file as well. Indexes should
+            be created without the DDL transaction enabled to avoid table locking.
 
           If you're 100% positive that this migration is already safe, then simply
           add a call to `safety_assured` to your migration.

data/zero_downtime_migrations.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= 2.0.0"
   s.summary               = "Zero downtime migrations with ActiveRecord and PostgreSQL"
   s.test_files            = `git ls-files -- spec/*`.split("\n")
-  s.version               = "0.0.6"
+  s.version               = "0.0.7"
 
   s.add_dependency "activerecord"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero_downtime_migrations
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - LendingHome
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-21 00:00:00.000000000 Z
+date: 2016-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord