strong_migrations 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85bce3e28cb77bab6bea2ff5fe300c7e5b7b7b26
-  data.tar.gz: aa648b6c6cb9744cfd9bad3fa0af93544e62d056
+  metadata.gz: 5b381f6d77227aa434bfae57e8bd63b5ee74181a
+  data.tar.gz: f1049edf7a7b01f3c075c0401003de048b7bde90
 SHA512:
-  metadata.gz: 0327c5add8b8d83026e1d2044740f115918c3ec588db1c09bf97130354bd812c59ac78ab0f9d2f13cff12c84593e5406b4a05d1fa1a426ed478869adcc7c94ba
-  data.tar.gz: 335feda7ce4b8fd0a55a52ea6272ac413e6bbffe1b308f2db9fc758ff0a0568a0a6a4b0e238dce5490979caee04568a4ab51c81b5a3c26efcc82d8db0d022b2a
+  metadata.gz: 28d568d129cb527e9e5465f8c583ef7cab4972da9e9142a944a899753b22f8e90346f3c1a9d63c1c3ea32b939b058716aa6734030ebca352a1a8cc507e3bd565
+  data.tar.gz: 7c8bc5d03567a87fab67ec089c9a0ca71d2704079b5a2960530e7b97d3f76e78fd772a949d5e36b19582eea49024cdd2a7e7e6a8062344ae673a70a52be41d96

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.2.0
+
+- Added customizable error messages
+- Updated instructions for adding a column with a default value
+
 ## 0.1.9
 
 - Added `start_after` option

data/README.md

@@ -4,7 +4,7 @@ Catch unsafe migrations at dev time
 
 :tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
 
-[![Build Status](https://travis-ci.org/ankane/strong_migrations.svg)](https://travis-ci.org/ankane/strong_migrations)
+[![Build Status](https://travis-ci.org/ankane/strong_migrations.svg?branch=master)](https://travis-ci.org/ankane/strong_migrations)
 
 ## Installation
 
@@ -16,12 +16,13 @@ gem 'strong_migrations'
 
 ## Dangerous Operations
 
+The following operations can cause downtime or errors:
+
 - adding a column with a non-null default value to an existing table
 - changing the type of a column
 - renaming a table
 - renaming a column
 - removing a column
-- executing arbitrary SQL
 - adding an index non-concurrently (Postgres only)
 - adding a `json` column to an existing table (Postgres only)
 
@@ -39,9 +40,9 @@ Also checks for best practices:
 ### Adding a column with a default value
 
 1. Add the column without a default value
-2. Commit the transaction
-3. Backfill the column
-4. Add the default value
+2. Add the default value
+3. Commit the transaction - **extremely important if you are backfilling in the migration**
+4. Backfill the column
 
 ```ruby
 class AddSomeColumnToUsers < ActiveRecord::Migration
@@ -50,18 +51,18 @@ class AddSomeColumnToUsers < ActiveRecord::Migration
     add_column :users, :some_column, :text
 
     # 2
+    change_column_default :users, :some_column, "default_value"
+
+    # 3
     commit_db_transaction
 
-    # 3.a (Rails 5+)
+    # 4.a (Rails 5+)
     User.in_batches.update_all some_column: "default_value"
 
-    # 3.b (Rails < 5)
+    # 4.b (Rails < 5)
     User.find_in_batches do |users|
       User.where(id: users.map(&:id)).update_all some_column: "default_value"
     end
-
-    # 4
-    change_column_default :users, :some_column, "default_value"
   end
 
   def down
@@ -94,23 +95,36 @@ If you really have to:
 
 ### Removing a column
 
-Tell ActiveRecord to ignore the column from its cache.
+ActiveRecord caches database columns at runtime, so if you drop a column, it can cause exceptions until your app reboots. To prevent this:
 
-```ruby
-# For Rails 5+
-class User < ActiveRecord::Base
-  self.ignored_columns = %w(some_column)
-end
+1. Tell ActiveRecord to ignore the column from its cache
 
-# For Rails < 5
-class User < ActiveRecord::Base
-  def self.columns
-    super.reject { |c| c.name == "some_column" }
+  ```ruby
+  # For Rails 5+
+  class User < ApplicationRecord
+    self.ignored_columns = %w(some_column)
   end
-end
-```
 
-Once it’s deployed, create a migration to remove the column.
+  # For Rails < 5
+  class User < ActiveRecord::Base
+    def self.columns
+      super.reject { |c| c.name == "some_column" }
+    end
+  end
+  ```
+
+2. Deploy code
+3. Write a migration to remove the column (wrap in `safety_assured` block)
+
+  ```ruby
+  class RemoveSomeColumnFromUsers < ActiveRecord::Migration
+    def change
+      safety_assured { remove_column :users, :some_column }
+    end
+  end
+  ```
+
+4. Deploy and run migration
 
 ### Adding an index (Postgres)
 
@@ -153,6 +167,8 @@ To mark migrations as safe that were created before installing this gem, create
 StrongMigrations.start_after = 20170101000000
 ```
 
+Use the version from your latest migration.
+
 ## Dangerous Tasks
 
 For safety, dangerous rake tasks are disabled in production - `db:drop`, `db:reset`, `db:schema:load`, and `db:structure:load`. To get around this, use:
@@ -178,6 +194,16 @@ Columns can flip order in `db/schema.rb` when you have multiple developers. One
 task "db:schema:dump": "strong_migrations:alphabetize_columns"
 ```
 
+## Custom Error Messages
+
+To customize specific error messages, create an initializer with:
+
+```ruby
+StrongMigrations.error_messages[:add_column_default] = "Your custom instructions"
+```
+
+Check the source code for the list of keys.
+
 ## Analyze Tables (Postgres)
 
 Analyze tables automatically (to update planner statistics) after an index is added. Create an initializer with:
@@ -186,6 +212,16 @@ Analyze tables automatically (to update planner statistics) after an index is ad
 StrongMigrations.auto_analyze = true
 ```
 
+## Lock Timeout (Postgres)
+
+It’s a good idea to set a lock timeout for the database user that runs migrations. This way, if migrations can’t acquire a lock in a timely manner, other statements won’t be stuck behind it.
+
+```sql
+ALTER ROLE myuser SET lock_timeout = '10s';
+```
+
+There’s also [a gem](https://github.com/gocardless/activerecord-safer_migrations) you can use for this.
+
 ## Credits
 
 Thanks to Bob Remeika and David Waller for the [original code](https://github.com/foobarfighter/safe-migrations).

data/lib/strong_migrations.rb

@@ -6,10 +6,125 @@ require "strong_migrations/railtie" if defined?(Rails)
 
 module StrongMigrations
   class << self
-    attr_accessor :auto_analyze, :start_after
+    attr_accessor :auto_analyze, :start_after, :error_messages
   end
   self.auto_analyze = false
   self.start_after = 0
+  self.error_messages = {
+    add_column_default:
+"Adding a column with a non-null default requires
+the entire table and indexes to be rewritten. Instead:
+
+1. Add the column without a default value
+2. Add the default value
+3. Commit the transaction
+4. Backfill the column",
+
+    add_column_json:
+"There's no equality operator for the json column type.
+Replace all calls to uniq with a custom scope.
+
+  scope :uniq_on_id, -> { select(\"DISTINCT ON (your_table.id) your_table.*\") }
+
+Once it's deployed, wrap this step in a safety_assured { ... } block.",
+
+    change_column:
+"Changing the type of an existing column requires
+the entire table and indexes to be rewritten.
+
+If you really have to:
+
+1. Create a new column
+2. Write to both columns
+3. Backfill data from the old column to the new column
+4. Move reads from the old column to the new column
+5. Stop writing to the old column
+6. Drop the old column",
+
+    remove_column:
+      if ActiveRecord::VERSION::MAJOR >= 5
+"ActiveRecord caches attributes which causes problems
+when removing columns. Be sure to ignore the column:
+
+class User < ApplicationRecord
+  self.ignored_columns = %w(some_column)
+end
+
+Once that's deployed, wrap this step in a safety_assured { ... } block.
+
+More info: https://github.com/ankane/strong_migrations#removing-a-column"
+      else
+"ActiveRecord caches attributes which causes problems
+when removing columns. Be sure to ignore the column:
+
+class User < ActiveRecord::Base
+  def self.columns
+    super.reject { |c| c.name == \"some_column\" }
+  end
+end
+
+Once that's deployed, wrap this step in a safety_assured { ... } block.
+
+More info: https://github.com/ankane/strong_migrations#removing-a-column"
+      end,
+
+    rename_column:
+"If you really have to:
+
+1. Create a new column
+2. Write to both columns
+3. Backfill data from the old column to new column
+4. Move reads from the old column to the new column
+5. Stop writing to the old column
+6. Drop the old column",
+
+    rename_table:
+"If you really have to:
+
+1. Create a new table
+2. Write to both tables
+3. Backfill data from the old table to new table
+4. Move reads from the old table to the new table
+5. Stop writing to the old table
+6. Drop the old table",
+
+    add_reference:
+"Adding a non-concurrent index locks the table. Instead, use:
+
+  def change
+    add_reference :users, :reference, index: false
+    commit_db_transaction
+    add_index :users, :reference_id, algorithm: :concurrently
+  end",
+
+    add_index:
+"Adding a non-concurrent index locks the table. Instead, use:
+
+  def change
+    commit_db_transaction
+    add_index :users, :some_column, algorithm: :concurrently
+  end",
+
+    add_index_columns:
+"Adding an index with more than three columns only helps on extremely large tables.
+
+If you're sure this is what you want, wrap it in a safety_assured { ... } block.",
+
+    change_table:
+"The strong_migrations gem does not support inspecting what happens inside a
+change_table block, so cannot help you here. Please make really sure that what
+you're doing is safe before proceeding, then wrap it in a safety_assured { ... } block.",
+
+    create_table:
+"The force option will destroy existing tables.
+If this is intended, drop the existing table first.
+Otherwise, remove the option.",
+
+    execute:
+"The strong_migrations gem does not support inspecting what happens inside an
+execute call, so cannot help you here. Please make really sure that what
+you're doing is safe before proceeding, then wrap it in a safety_assured { ... } block."
+  }
 end
 
 ActiveRecord::Migration.send(:prepend, StrongMigrations::Migration)

data/lib/strong_migrations/migration.rb

@@ -80,97 +80,6 @@ module StrongMigrations
     end
 
     def raise_error(message_key)
-      message =
-        case message_key
-        when :add_column_default
-"Adding a column with a non-null default requires
-the entire table and indexes to be rewritten. Instead:
-
-1. Add the column without a default value
-2. Commit the transaction
-3. Backfill the column
-4. Add the default value"
-        when :add_column_json
-"There's no equality operator for the json column type.
-Replace all calls to uniq with a custom scope.
-
-  scope :uniq_on_id, -> { select(\"DISTINCT ON (your_table.id) your_table.*\") }
-
-Once it's deployed, wrap this step in a safety_assured { ... } block."
-        when :change_column
-"Changing the type of an existing column requires
-the entire table and indexes to be rewritten.
-
-If you really have to:
-
-1. Create a new column
-2. Write to both columns
-3. Backfill data from the old column to the new column
-4. Move reads from the old column to the new column
-5. Stop writing to the old column
-6. Drop the old column"
-        when :remove_column
-"ActiveRecord caches attributes which causes problems
-when removing columns. Be sure to ignored the column:
-
-class User
-  def self.columns
-    super.reject { |c| c.name == \"some_column\" }
-  end
-end
-
-Once it's deployed, wrap this step in a safety_assured { ... } block."
-        when :rename_column
-"If you really have to:
-
-1. Create a new column
-2. Write to both columns
-3. Backfill data from the old column to new column
-4. Move reads from the old column to the new column
-5. Stop writing to the old column
-6. Drop the old column"
-        when :rename_table
-"If you really have to:
-
-1. Create a new table
-2. Write to both tables
-3. Backfill data from the old table to new table
-4. Move reads from the old table to the new table
-5. Stop writing to the old table
-6. Drop the old table"
-        when :add_reference
-"Adding a non-concurrent index locks the table. Instead, use:
-
-  def change
-    add_reference :users, :reference, index: false
-    commit_db_transaction
-    add_index :users, :reference_id, algorithm: :concurrently
-  end"
-        when :add_index
-"Adding a non-concurrent index locks the table. Instead, use:
-
-  def change
-    commit_db_transaction
-    add_index :users, :some_column, algorithm: :concurrently
-  end"
-        when :add_index_columns
-"Adding an index with more than three columns only helps on extremely large tables.
-
-If you're sure this is what you want, wrap it in a safety_assured { ... } block."
-        when :change_table
-"The strong_migrations gem does not support inspecting what happens inside a
-change_table block, so cannot help you here. Please make really sure that what
-you're doing is safe before proceeding, then wrap it in a safety_assured { ... } block."
-        when :create_table
-"The force option will destroy existing tables.
-If this is intended, drop the existing table first.
-Otherwise, remove the option."
-        when :execute
-"The strong_migrations gem does not support inspecting what happens inside an
-execute call, so cannot help you here. Please make really sure that what
-you're doing is safe before proceeding, then wrap it in a safety_assured { ... } block."
-        end
-
       wait_message = '
  __          __     _____ _______ _
  \ \        / /\   |_   _|__   __| |
@@ -180,7 +89,7 @@ you're doing is safe before proceeding, then wrap it in a safety_assured { ... }
      \/  \/_/    \_\_____|  |_|  (_)
 
 '
-
+      message = StrongMigrations.error_messages[message_key] || "Missing message"
       raise StrongMigrations::UnsafeMigration, "#{wait_message}#{message}\n"
     end
   end

data/lib/strong_migrations/version.rb

@@ -1,3 +1,3 @@
 module StrongMigrations
-  VERSION = "0.1.9"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strong_migrations
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Bob Remeika
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-14 00:00:00.000000000 Z
+date: 2018-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -123,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Catch unsafe migrations at dev time