zero_downtime_migrations 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c8dfec1a4d2d84e2a9260829418235053eeec0c
-  data.tar.gz: 0568a51dd7990eb896354ed67cfe984a3bcc8f13
+  metadata.gz: c98c1cbcf271026706fc6d40043d1fcba981ef04
+  data.tar.gz: aa219a884d42a7024256b9763f08decbfb6950d4
 SHA512:
-  metadata.gz: 1b0b3503a2749957e5f310bd5c38bcfa3243a3fd2d077f793ca17fff631c384a65f6dc75d247588f52912bb43ee36d2bbbd6d173f33912f34abc357f9e0aa4f6
-  data.tar.gz: 1d2d7bc71333d19ba28b1c6600a99d23cf2094078f9f45dd9df826ce9306b0284b9e9236eae920b3b1224d33cddeb7f8ce020c81567d77448df1d36e62966b3c
+  metadata.gz: 862eaac1afae554f4727fad033c8f1ac023973c3dc2d849535eb715fb2a18ec87c770aca6a591d604417d18fd23c9116f8c02684cf1914ee5d28d3df30950bd0
+  data.tar.gz: 30bbf4dd92155ae61b48721d8088f9cee339ba502634b775f6169cc5e4b7405d3109261da0d93bd127b1cb5fb72d77628e85e51b7db5a3be6b5e7debb389705b

data/Gemfile.lock

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

data/README.md

@@ -1,15 +1,16 @@
 # ![LendingHome](https://cloud.githubusercontent.com/assets/2419/19467866/7efa93a8-94c8-11e6-93e7-4375dbb8a7bc.png) zero_downtime_migrations
+[![Code Climate](https://codeclimate.com/github/LendingHome/zero_downtime_migrations/badges/gpa.svg)](https://codeclimate.com/github/LendingHome/zero_downtime_migrations) [![Coverage](https://codeclimate.com/github/LendingHome/zero_downtime_migrations/badges/coverage.svg)](https://codeclimate.com/github/LendingHome/zero_downtime_migrations) [![Gem Version](https://badge.fury.io/rb/zero_downtime_migrations.svg)](http://badge.fury.io/rb/zero_downtime_migrations)
 
-Zero downtime migrations with ActiveRecord and PostgreSQL. Catch problematic migrations at development/test time!
+> Zero downtime migrations with ActiveRecord and PostgreSQL.
 
-Heavily inspired by these similar projects:
+Catch problematic migrations at development/test time! Heavily inspired by these similar projects:
 
 * https://github.com/ankane/strong_migrations
 * https://github.com/foobarfighter/safe-migrations
 
 ## Installation
 
-Simply add the gem to the project `Gemfile`. Ensure that it's only **added to the `development` and `test`** groups.
+Simply add this gem to the project `Gemfile` under the **`development` and `test`** groups.
 
 ```ruby
 gem "zero_downtime_migrations", only: %i(development test)
@@ -27,45 +28,7 @@ It checks for common things like:
 * Performing data or schema migrations with the DDL transaction disabled
 * Using `each` instead of `find_each` to loop thru `ActiveRecord` objects
 
-These exceptions display very clear instructions of how to perform the same operation the "zero downtime way".
-
-## Disabling exceptions
-
-We can disable any of these "zero downtime migration" enforcements by wrapping them in a `safety_assured` block.
-
-```ruby
-class AddPublishedToPosts < ActiveRecord::Migration[5.0]
-  def change
-    safety_assured do
-      add_column :posts, :published, :boolean, default: true
-    end
-  end
-end
-```
-
-We can also mark an entire migration as safe by using the `safety_assured` helper method.
-
-```ruby
-class AddPublishedToPosts < ActiveRecord::Migration[5.0]
-  safety_assured
-  
-  def change
-    add_column :posts, :published, :boolean
-    Post.where("created_at >= ?", 1.day.ago).update_all(published: true)
-  end
-end
-```
-
-Enforcements can be globally disabled by setting `ENV["SAFETY_ASSURED"]` when running migrations.
-
-```bash
-SAFETY_ASSURED=1 bundle exec rake db:migrate --trace
-```
-
-These enforcements are **automatically disabled by default for the following scenarios**:
-
-* The database schema is being loaded with `rake db:schema:load` instead of `db:migrate`
-* The current migration is a reverse (down) migration
+These exceptions display clear instructions of how to perform the same operation the "zero downtime way".
 
 ## Validations
 
@@ -73,6 +36,8 @@ These enforcements are **automatically disabled by default for the following sce
 
 #### Bad
 
+This migration can potentially lock your database table!
+
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
   def change
@@ -83,6 +48,8 @@ end
 
 #### Good
 
+Instead, let's first add the column without a default.
+
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
   def change
@@ -91,6 +58,8 @@ 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.
+
 ```ruby
 class SetPublishedDefaultOnPosts < ActiveRecord::Migration[5.0]
   def change
@@ -99,6 +68,8 @@ 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.
+
 ```ruby
 class BackportPublishedDefaultOnPosts < ActiveRecord::Migration[5.0]
   def change
@@ -114,6 +85,8 @@ end
 
 #### Bad
 
+This action can potentially lock your database table while indexing all existing data!
+
 ```ruby
 class IndexUsersOnEmail < ActiveRecord::Migration[5.0]
   def change
@@ -124,6 +97,8 @@ end
 
 #### Good
 
+Instead, let's add the index concurrently in its own migration with the DDL transaction disabled.
+
 ```ruby
 class IndexUsersOnEmail < ActiveRecord::Migration[5.0]
   disable_ddl_transaction!
@@ -138,6 +113,8 @@ end
 
 #### Bad
 
+Performing migrations that change the schema, update data, or add indexes within one big transaction is unsafe!
+
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
   def change
@@ -150,6 +127,12 @@ end
 
 #### Good
 
+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.
+
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
   def change
@@ -180,6 +163,8 @@ end
 
 #### Bad
 
+The DDL transaction should only be disabled for migrations that add indexes.
+
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
   disable_ddl_transaction!
@@ -202,6 +187,8 @@ end
 
 #### Good
 
+Any other data or schema changes must live in their own migration files with the DDL transaction enabled just in case they make changes that need to be rolled back.
+
 ```ruby
 class AddPublishedToPosts < ActiveRecord::Migration[5.0]
   def change
@@ -222,6 +209,8 @@ end
 
 #### Bad
 
+This might accidentally load tens or hundreds of thousands of records into memory all at the same time!
+
 ```ruby
 class BackportPublishedDefaultOnPosts < ActiveRecord::Migration[5.0]
   def change
@@ -234,6 +223,8 @@ end
 
 #### Good
 
+Let's use the `find_each` method to fetch records in batches instead.
+
 ```ruby
 class BackportPublishedDefaultOnPosts < ActiveRecord::Migration[5.0]
   def change
@@ -251,6 +242,45 @@ end
 * Renaming a column
 * Renaming a table
 
+## Disabling "zero downtime migration" enforcements
+
+We can disable any of these "zero downtime migration" enforcements by wrapping them in a `safety_assured` block.
+
+```ruby
+class AddPublishedToPosts < ActiveRecord::Migration[5.0]
+  def change
+    safety_assured do
+      add_column :posts, :published, :boolean, default: true
+    end
+  end
+end
+```
+
+We can also mark an entire migration as safe by using the `safety_assured` helper method.
+
+```ruby
+class AddPublishedToPosts < ActiveRecord::Migration[5.0]
+  safety_assured
+
+  def change
+    add_column :posts, :published, :boolean
+    Post.where("created_at >= ?", 1.day.ago).update_all(published: true)
+  end
+end
+```
+
+Enforcements can be globally disabled by setting `ENV["SAFETY_ASSURED"]` when running migrations.
+
+```bash
+SAFETY_ASSURED=1 bundle exec rake db:migrate --trace
+```
+
+These enforcements are **automatically disabled by default for the following scenarios**:
+
+* The database schema is being loaded with `rake db:schema:load` instead of `db:migrate`
+* The current migration is a reverse (down) migration
+* The current migration is named `RollupMigrations`
+
 ## Testing
 
 ```bash
@@ -265,6 +295,10 @@ bundle exec rspec
 * Commit, do not mess with the version or history.
 * Open a pull request. Bonus points for topic branches.
 
+## Authors
+
+* [Sean Huber](https://github.com/shuber)
+
 ## License
 
 [MIT](https://github.com/lendinghome/zero_downtime_migrations/blob/master/LICENSE) - Copyright © 2016 LendingHome

data/docker-compose.yml

@@ -9,6 +9,7 @@ services:
       - postgres
     environment:
       - CI
+      - CODECLIMATE_REPO_TOKEN=efff74f42f6e9dff9daa21e21e8d8d2d3cb33f37b84a9d06bb907edb48a2cf6f
       - DATABASE_URL=postgres://postgres@postgres/zero_downtime_migrations
       - DOCKER=true
       - RACK_ENV=test

data/lib/zero_downtime_migrations/{unsafe_migration_error.rb → error.rb}

@@ -1,5 +1,11 @@
 module ZeroDowntimeMigrations
-  class UnsafeMigrationError < StandardError
+  class Error < StandardError
+  end
+
+  class UndefinedValidationError < Error
+  end
+
+  class UnsafeMigrationError < Error
     def initialize(error, correction)
       error_with_type = "#{self.class.name}: #{error}"
       super("#{error_with_type}\n\n#{correction}")

data/lib/zero_downtime_migrations/migration.rb

@@ -94,7 +94,9 @@ module ZeroDowntimeMigrations
     end
 
     def validate(type, *args)
-      Validation.validate!(type, self, *args) if Migration.unsafe?
+      Validation.validate!(type, self, *args)
+    rescue UndefinedValidationError
+      nil
     end
   end
 end

data/lib/zero_downtime_migrations/relation.rb

@@ -3,10 +3,8 @@ module ZeroDowntimeMigrations
     prepend Data
 
     def each(*)
-      return super unless Migration.migrating? && Migration.unsafe?
-      error = "Using ActiveRecord::Relation#each is unsafe!"
-      correction = "Instead, let's use the find_each method to query in batches."
-      raise UnsafeMigrationError.new(error, correction)
+      Validation.validate!(:find_each)
+      super
     end
   end
 end

data/lib/zero_downtime_migrations/validation/ddl_migration.rb

@@ -15,6 +15,18 @@ module ZeroDowntimeMigrations
 
           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.
+
+          If you're 100% positive that this migration is already safe, then simply
+          add a call to `safety_assured` to your migration.
+
+            class #{migration_name} < ActiveRecord::Migration
+              disable_ddl_transaction!
+              safety_assured
+
+              def change
+                # ...
+              end
+            end
         MESSAGE
       end
     end

data/lib/zero_downtime_migrations/validation/find_each.rb

@@ -0,0 +1,32 @@
+module ZeroDowntimeMigrations
+  class Validation
+    class FindEach < Validation
+      def validate!
+        message = "Using `ActiveRecord::Relation#each` is unsafe!"
+        error!(message, correction)
+      end
+
+      private
+
+      def correction
+        <<-MESSAGE.strip_heredoc
+          Let's use the `find_each` method to fetch records in batches instead.
+
+          Otherwise we may accidentally load tens or hundreds of thousands of
+          records into memory all at the same time!
+
+          If you're 100% positive that this migration is already safe, then wrap the
+          call to `each` in a `safety_assured` block.
+
+            class YourMigration < ActiveRecord::Migration
+              def change
+                safety_assured do
+                  # use .each in this block
+                end
+              end
+            end
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/zero_downtime_migrations/validation/mixed_migration.rb

@@ -16,6 +16,17 @@ module ZeroDowntimeMigrations
           * 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.
+
+          If you're 100% positive that this migration is already safe, then simply
+          add a call to `safety_assured` to your migration.
+
+            class #{migration_name} < ActiveRecord::Migration
+              safety_assured
+
+              def change
+                # ...
+              end
+            end
         MESSAGE
       end
     end

data/lib/zero_downtime_migrations/validation.rb

@@ -1,9 +1,14 @@
 module ZeroDowntimeMigrations
   class Validation
-    def self.validate!(type, migration, *args)
+    def self.validate!(type, migration = nil, *args)
+      return unless Migration.migrating? && Migration.unsafe?
       validator = type.to_s.classify
-      validator = const_get(validator) if const_defined?(validator)
-      validator.new(migration, *args).validate! if validator
+
+      if const_defined?(validator)
+        const_get(validator).new(migration, *args).validate!
+      else
+        raise UndefinedValidationError.new(validator)
+      end
     end
 
     attr_reader :migration, :args
@@ -17,6 +22,10 @@ module ZeroDowntimeMigrations
       raise UnsafeMigrationError.new(*args)
     end
 
+    def migration_name
+      migration.class.name
+    end
+
     def options
       args.last.is_a?(Hash) ? args.last : {}
     end

data/lib/zero_downtime_migrations.rb

@@ -2,14 +2,15 @@ require "active_record"
 
 require_relative "zero_downtime_migrations/data"
 require_relative "zero_downtime_migrations/dsl"
+require_relative "zero_downtime_migrations/error"
 require_relative "zero_downtime_migrations/migration"
 require_relative "zero_downtime_migrations/relation"
 require_relative "zero_downtime_migrations/validation"
 require_relative "zero_downtime_migrations/validation/add_column"
 require_relative "zero_downtime_migrations/validation/add_index"
 require_relative "zero_downtime_migrations/validation/ddl_migration"
+require_relative "zero_downtime_migrations/validation/find_each"
 require_relative "zero_downtime_migrations/validation/mixed_migration"
-require_relative "zero_downtime_migrations/unsafe_migration_error"
 
 ActiveRecord::Base.send(:prepend, ZeroDowntimeMigrations::Data)
 ActiveRecord::Migration.send(:prepend, ZeroDowntimeMigrations::Migration)

data/spec/internal/db/migrate/20161012223258_create_table_comments.rb

@@ -0,0 +1,10 @@
+class CreateTableComments < ActiveRecord::Migration[5.0]
+  def change
+    create_table :comments do |t|
+      t.references :user, null: false
+      t.references :post, null: false
+      t.text :body, null: false
+      t.timestamps null: false
+    end
+  end
+end

data/spec/zero_downtime_migrations/validation/add_index_spec.rb

@@ -30,20 +30,4 @@ RSpec.describe ZeroDowntimeMigrations::Validation::AddIndex do
       expect { migration.migrate(:up) }.to raise_error(error)
     end
   end
-
-  context "with the correct options" do
-    let(:migration) do
-      Class.new(ActiveRecord::Migration[5.0]) do
-        disable_ddl_transaction!
-
-        def change
-          add_index :users, :updated_at, algorithm: :concurrently
-        end
-      end
-    end
-
-    it "does not raise an unsafe migration error" do
-      expect { migration.migrate(:up) }.not_to raise_error(error)
-    end
-  end
 end

data/spec/zero_downtime_migrations/{relation_spec.rb → validation/find_each_spec.rb}

@@ -1,4 +1,4 @@
-RSpec.describe ZeroDowntimeMigrations::Relation do
+RSpec.describe ZeroDowntimeMigrations::Validation::FindEach do
   let(:error) { ZeroDowntimeMigrations::UnsafeMigrationError }
 
   context "with data migrations using each" do

data/spec/zero_downtime_migrations/validation_spec.rb

@@ -4,6 +4,14 @@ RSpec.describe ZeroDowntimeMigrations::Validation do
   let(:migration) { double("migration") }
   let(:args) { [] }
 
+  describe ".validate!" do
+    let(:error) { ZeroDowntimeMigrations::UndefinedValidationError }
+
+    it "raises UndefinedValidationError if one does not exist" do
+      expect { described_class.validate!(:invalid) }.to raise_error(error)
+    end
+  end
+
   describe "#args" do
     it "returns the initialized args" do
       expect(subject.args).to eq(args)

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.1"
+  s.version               = "0.0.2"
 
   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.1
+  version: 0.0.2
 platform: ruby
 authors:
 - LendingHome
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-18 00:00:00.000000000 Z
+date: 2016-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -46,13 +46,14 @@ files:
 - lib/zero_downtime_migrations.rb
 - lib/zero_downtime_migrations/data.rb
 - lib/zero_downtime_migrations/dsl.rb
+- lib/zero_downtime_migrations/error.rb
 - lib/zero_downtime_migrations/migration.rb
 - lib/zero_downtime_migrations/relation.rb
-- lib/zero_downtime_migrations/unsafe_migration_error.rb
 - lib/zero_downtime_migrations/validation.rb
 - lib/zero_downtime_migrations/validation/add_column.rb
 - lib/zero_downtime_migrations/validation/add_index.rb
 - lib/zero_downtime_migrations/validation/ddl_migration.rb
+- lib/zero_downtime_migrations/validation/find_each.rb
 - lib/zero_downtime_migrations/validation/mixed_migration.rb
 - spec/internal/app/models/post.rb
 - spec/internal/app/models/user.rb
@@ -63,13 +64,14 @@ files:
 - spec/internal/db/migrate/20161012223255_safe_add_index_with_env.rb
 - spec/internal/db/migrate/20161012223256_safe_add_index_with_dsl.rb
 - spec/internal/db/migrate/20161012223257_add_index_concurrently.rb
+- spec/internal/db/migrate/20161012223258_create_table_comments.rb
 - spec/internal/db/schema.rb
 - spec/internal/log/.gitignore
 - spec/spec_helper.rb
-- spec/zero_downtime_migrations/relation_spec.rb
 - spec/zero_downtime_migrations/validation/add_column_spec.rb
 - spec/zero_downtime_migrations/validation/add_index_spec.rb
 - spec/zero_downtime_migrations/validation/ddl_migration_spec.rb
+- spec/zero_downtime_migrations/validation/find_each_spec.rb
 - spec/zero_downtime_migrations/validation/mixed_migration_spec.rb
 - spec/zero_downtime_migrations/validation_spec.rb
 - spec/zero_downtime_migrations_spec.rb
@@ -113,13 +115,14 @@ test_files:
 - spec/internal/db/migrate/20161012223255_safe_add_index_with_env.rb
 - spec/internal/db/migrate/20161012223256_safe_add_index_with_dsl.rb
 - spec/internal/db/migrate/20161012223257_add_index_concurrently.rb
+- spec/internal/db/migrate/20161012223258_create_table_comments.rb
 - spec/internal/db/schema.rb
 - spec/internal/log/.gitignore
 - spec/spec_helper.rb
-- spec/zero_downtime_migrations/relation_spec.rb
 - spec/zero_downtime_migrations/validation/add_column_spec.rb
 - spec/zero_downtime_migrations/validation/add_index_spec.rb
 - spec/zero_downtime_migrations/validation/ddl_migration_spec.rb
+- spec/zero_downtime_migrations/validation/find_each_spec.rb
 - spec/zero_downtime_migrations/validation/mixed_migration_spec.rb
 - spec/zero_downtime_migrations/validation_spec.rb
 - spec/zero_downtime_migrations_spec.rb