Prepare for zero downtime migrationszero-downtime-migrations

Starting with GitLab 9.1.0 we will no longer allow downtime migrations
unless absolutely necessary. This commit updates the various developer
guides and adds code that is necessary to make zero downtime migrations
less painful.

3 files changed, 467 insertions, 0 deletions

diff --git a/spec/lib/gitlab/database/migration_helpers_spec.rb b/spec/lib/gitlab/database/migration_helpers_spec.rb
index 4ac79454647..8d109cba71a 100644
--- a/spec/lib/gitlab/database/migration_helpers_spec.rb
+++ b/spec/lib/gitlab/database/migration_helpers_spec.rb
@@ -294,4 +294,392 @@ describe Gitlab::Database::MigrationHelpers, lib: true do
       end
     end
   end
+
+  describe '#rename_column_concurrently' do
+    context 'in a transaction' do
+      it 'raises RuntimeError' do
+        allow(model).to receive(:transaction_open?).and_return(true)
+
+        expect { model.rename_column_concurrently(:users, :old, :new) }.
+          to raise_error(RuntimeError)
+      end
+    end
+
+    context 'outside a transaction' do
+      let(:old_column) do
+        double(:column,
+               type: :integer,
+               limit: 8,
+               default: 0,
+               null: false,
+               precision: 5,
+               scale: 1)
+      end
+
+      let(:trigger_name) { model.rename_trigger_name(:users, :old, :new) }
+
+      before do
+        allow(model).to receive(:transaction_open?).and_return(false)
+        allow(model).to receive(:column_for).and_return(old_column)
+
+        # Since MySQL and PostgreSQL use different quoting styles we'll just
+        # stub the methods used for this to make testing easier.
+        allow(model).to receive(:quote_column_name) { |name| name.to_s }
+        allow(model).to receive(:quote_table_name) { |name| name.to_s }
+      end
+
+      context 'using MySQL' do
+        it 'renames a column concurrently' do
+          allow(Gitlab::Database).to receive(:postgresql?).and_return(false)
+
+          expect(model).to receive(:install_rename_triggers_for_mysql).
+            with(trigger_name, 'users', 'old', 'new')
+
+          expect(model).to receive(:add_column).
+            with(:users, :new, :integer,
+                 limit: old_column.limit,
+                 default: old_column.default,
+                 null: old_column.null,
+                 precision: old_column.precision,
+                 scale: old_column.scale)
+
+          expect(model).to receive(:update_column_in_batches)
+
+          expect(model).to receive(:copy_indexes).with(:users, :old, :new)
+          expect(model).to receive(:copy_foreign_keys).with(:users, :old, :new)
+
+          model.rename_column_concurrently(:users, :old, :new)
+        end
+      end
+
+      context 'using PostgreSQL' do
+        it 'renames a column concurrently' do
+          allow(Gitlab::Database).to receive(:postgresql?).and_return(true)
+
+          expect(model).to receive(:install_rename_triggers_for_postgresql).
+            with(trigger_name, 'users', 'old', 'new')
+
+          expect(model).to receive(:add_column).
+            with(:users, :new, :integer,
+                 limit: old_column.limit,
+                 default: old_column.default,
+                 null: old_column.null,
+                 precision: old_column.precision,
+                 scale: old_column.scale)
+
+          expect(model).to receive(:update_column_in_batches)
+
+          expect(model).to receive(:copy_indexes).with(:users, :old, :new)
+          expect(model).to receive(:copy_foreign_keys).with(:users, :old, :new)
+
+          model.rename_column_concurrently(:users, :old, :new)
+        end
+      end
+    end
+  end
+
+  describe '#cleanup_concurrent_column_rename' do
+    it 'cleans up the renaming procedure for PostgreSQL' do
+      allow(Gitlab::Database).to receive(:postgresql?).and_return(true)
+
+      expect(model).to receive(:remove_rename_triggers_for_postgresql).
+        with(:users, /trigger_.{12}/)
+
+      expect(model).to receive(:remove_column).with(:users, :old)
+
+      model.cleanup_concurrent_column_rename(:users, :old, :new)
+    end
+
+    it 'cleans up the renaming procedure for MySQL' do
+      allow(Gitlab::Database).to receive(:postgresql?).and_return(false)
+
+      expect(model).to receive(:remove_rename_triggers_for_mysql).
+        with(/trigger_.{12}/)
+
+      expect(model).to receive(:remove_column).with(:users, :old)
+
+      model.cleanup_concurrent_column_rename(:users, :old, :new)
+    end
+  end
+
+  describe '#change_column_type_concurrently' do
+    it 'changes the column type' do
+      expect(model).to receive(:rename_column_concurrently).
+        with('users', 'username', 'username_for_type_change', type: :text)
+
+      model.change_column_type_concurrently('users', 'username', :text)
+    end
+  end
+
+  describe '#cleanup_concurrent_column_type_change' do
+    it 'cleans up the type changing procedure' do
+      expect(model).to receive(:cleanup_concurrent_column_rename).
+        with('users', 'username', 'username_for_type_change')
+
+      expect(model).to receive(:rename_column).
+        with('users', 'username_for_type_change', 'username')
+
+      model.cleanup_concurrent_column_type_change('users', 'username')
+    end
+  end
+
+  describe '#install_rename_triggers_for_postgresql' do
+    it 'installs the triggers for PostgreSQL' do
+      expect(model).to receive(:execute).
+        with(/CREATE OR REPLACE FUNCTION foo()/m)
+
+      expect(model).to receive(:execute).
+        with(/CREATE TRIGGER foo/m)
+
+      model.install_rename_triggers_for_postgresql('foo', :users, :old, :new)
+    end
+  end
+
+  describe '#install_rename_triggers_for_mysql' do
+    it 'installs the triggers for MySQL' do
+      expect(model).to receive(:execute).
+        with(/CREATE TRIGGER foo_insert.+ON users/m)
+
+      expect(model).to receive(:execute).
+        with(/CREATE TRIGGER foo_update.+ON users/m)
+
+      model.install_rename_triggers_for_mysql('foo', :users, :old, :new)
+    end
+  end
+
+  describe '#remove_rename_triggers_for_postgresql' do
+    it 'removes the function and trigger' do
+      expect(model).to receive(:execute).with('DROP TRIGGER foo ON bar')
+      expect(model).to receive(:execute).with('DROP FUNCTION foo()')
+
+      model.remove_rename_triggers_for_postgresql('bar', 'foo')
+    end
+  end
+
+  describe '#remove_rename_triggers_for_mysql' do
+    it 'removes the triggers' do
+      expect(model).to receive(:execute).with('DROP TRIGGER foo_insert')
+      expect(model).to receive(:execute).with('DROP TRIGGER foo_update')
+
+      model.remove_rename_triggers_for_mysql('foo')
+    end
+  end
+
+  describe '#rename_trigger_name' do
+    it 'returns a String' do
+      expect(model.rename_trigger_name(:users, :foo, :bar)).
+        to match(/trigger_.{12}/)
+    end
+  end
+
+  describe '#indexes_for' do
+    it 'returns the indexes for a column' do
+      idx1 = double(:idx, columns: %w(project_id))
+      idx2 = double(:idx, columns: %w(user_id))
+
+      allow(model).to receive(:indexes).with('table').and_return([idx1, idx2])
+
+      expect(model.indexes_for('table', :user_id)).to eq([idx2])
+    end
+  end
+
+  describe '#foreign_keys_for' do
+    it 'returns the foreign keys for a column' do
+      fk1 = double(:fk, column: 'project_id')
+      fk2 = double(:fk, column: 'user_id')
+
+      allow(model).to receive(:foreign_keys).with('table').and_return([fk1, fk2])
+
+      expect(model.foreign_keys_for('table', :user_id)).to eq([fk2])
+    end
+  end
+
+  describe '#copy_indexes' do
+    context 'using a regular index using a single column' do
+      it 'copies the index' do
+        index = double(:index,
+                       columns: %w(project_id),
+                       name: 'index_on_issues_project_id',
+                       using: nil,
+                       where: nil,
+                       opclasses: {},
+                       unique: false,
+                       lengths: [],
+                       orders: [])
+
+        allow(model).to receive(:indexes_for).with(:issues, 'project_id').
+          and_return([index])
+
+        expect(model).to receive(:add_concurrent_index).
+          with(:issues,
+               %w(gl_project_id),
+               unique: false,
+               name: 'index_on_issues_gl_project_id',
+               length: [],
+               order: [])
+
+        model.copy_indexes(:issues, :project_id, :gl_project_id)
+      end
+    end
+
+    context 'using a regular index with multiple columns' do
+      it 'copies the index' do
+        index = double(:index,
+                       columns: %w(project_id foobar),
+                       name: 'index_on_issues_project_id_foobar',
+                       using: nil,
+                       where: nil,
+                       opclasses: {},
+                       unique: false,
+                       lengths: [],
+                       orders: [])
+
+        allow(model).to receive(:indexes_for).with(:issues, 'project_id').
+          and_return([index])
+
+        expect(model).to receive(:add_concurrent_index).
+          with(:issues,
+               %w(gl_project_id foobar),
+               unique: false,
+               name: 'index_on_issues_gl_project_id_foobar',
+               length: [],
+               order: [])
+
+        model.copy_indexes(:issues, :project_id, :gl_project_id)
+      end
+    end
+
+    context 'using an index with a WHERE clause' do
+      it 'copies the index' do
+        index = double(:index,
+                       columns: %w(project_id),
+                       name: 'index_on_issues_project_id',
+                       using: nil,
+                       where: 'foo',
+                       opclasses: {},
+                       unique: false,
+                       lengths: [],
+                       orders: [])
+
+        allow(model).to receive(:indexes_for).with(:issues, 'project_id').
+          and_return([index])
+
+        expect(model).to receive(:add_concurrent_index).
+          with(:issues,
+               %w(gl_project_id),
+               unique: false,
+               name: 'index_on_issues_gl_project_id',
+               length: [],
+               order: [],
+               where: 'foo')
+
+        model.copy_indexes(:issues, :project_id, :gl_project_id)
+      end
+    end
+
+    context 'using an index with a USING clause' do
+      it 'copies the index' do
+        index = double(:index,
+                       columns: %w(project_id),
+                       name: 'index_on_issues_project_id',
+                       where: nil,
+                       using: 'foo',
+                       opclasses: {},
+                       unique: false,
+                       lengths: [],
+                       orders: [])
+
+        allow(model).to receive(:indexes_for).with(:issues, 'project_id').
+          and_return([index])
+
+        expect(model).to receive(:add_concurrent_index).
+          with(:issues,
+               %w(gl_project_id),
+               unique: false,
+               name: 'index_on_issues_gl_project_id',
+               length: [],
+               order: [],
+               using: 'foo')
+
+        model.copy_indexes(:issues, :project_id, :gl_project_id)
+      end
+    end
+
+    context 'using an index with custom operator classes' do
+      it 'copies the index' do
+        index = double(:index,
+                       columns: %w(project_id),
+                       name: 'index_on_issues_project_id',
+                       using: nil,
+                       where: nil,
+                       opclasses: { 'project_id' => 'bar' },
+                       unique: false,
+                       lengths: [],
+                       orders: [])
+
+        allow(model).to receive(:indexes_for).with(:issues, 'project_id').
+          and_return([index])
+
+        expect(model).to receive(:add_concurrent_index).
+          with(:issues,
+               %w(gl_project_id),
+               unique: false,
+               name: 'index_on_issues_gl_project_id',
+               length: [],
+               order: [],
+               opclasses: { 'gl_project_id' => 'bar' })
+
+        model.copy_indexes(:issues, :project_id, :gl_project_id)
+      end
+    end
+
+    describe 'using an index of which the name does not contain the source column' do
+      it 'raises RuntimeError' do
+        index = double(:index,
+                       columns: %w(project_id),
+                       name: 'index_foobar_index',
+                       using: nil,
+                       where: nil,
+                       opclasses: {},
+                       unique: false,
+                       lengths: [],
+                       orders: [])
+
+        allow(model).to receive(:indexes_for).with(:issues, 'project_id').
+          and_return([index])
+
+        expect { model.copy_indexes(:issues, :project_id, :gl_project_id) }.
+          to raise_error(RuntimeError)
+      end
+    end
+  end
+
+  describe '#copy_foreign_keys' do
+    it 'copies foreign keys from one column to another' do
+      fk = double(:fk,
+                  from_table: 'issues',
+                  to_table: 'projects',
+                  on_delete: :cascade)
+
+      allow(model).to receive(:foreign_keys_for).with(:issues, :project_id).
+        and_return([fk])
+
+      expect(model).to receive(:add_concurrent_foreign_key).
+        with('issues', 'projects', column: :gl_project_id, on_delete: :cascade)
+
+      model.copy_foreign_keys(:issues, :project_id, :gl_project_id)
+    end
+  end
+
+  describe '#column_for' do
+    it 'returns a column object for an existing column' do
+      column = model.column_for(:users, :id)
+
+      expect(column.name).to eq('id')
+    end
+
+    it 'returns nil when a column does not exist' do
+      expect(model.column_for(:users, :kittens)).to be_nil
+    end
+  end
 end
diff --git a/spec/lib/gitlab/database/multi_threaded_migration_spec.rb b/spec/lib/gitlab/database/multi_threaded_migration_spec.rb
new file mode 100644
index 00000000000..6c45f13bb5a
--- /dev/null
+++ b/spec/lib/gitlab/database/multi_threaded_migration_spec.rb
@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+describe Gitlab::Database::MultiThreadedMigration do
+  let(:migration) do
+    Class.new { include Gitlab::Database::MultiThreadedMigration }.new
+  end
+
+  describe '#connection' do
+    after do
+      Thread.current[described_class::MULTI_THREAD_AR_CONNECTION] = nil
+    end
+
+    it 'returns the thread-local connection if present' do
+      Thread.current[described_class::MULTI_THREAD_AR_CONNECTION] = 10
+
+      expect(migration.connection).to eq(10)
+    end
+
+    it 'returns the global connection if no thread-local connection was set' do
+      expect(migration.connection).to eq(ActiveRecord::Base.connection)
+    end
+  end
+
+  describe '#with_multiple_threads' do
+    it 'starts multiple threads and yields the supplied block in every thread' do
+      output = Queue.new
+
+      migration.with_multiple_threads(2) do
+        output << migration.connection.execute('SELECT 1')
+      end
+
+      expect(output.size).to eq(2)
+    end
+
+    it 'joins the threads when the join parameter is set' do
+      expect_any_instance_of(Thread).to receive(:join).and_call_original
+
+      migration.with_multiple_threads(1) { }
+    end
+  end
+end
diff --git a/spec/models/concerns/ignorable_column_spec.rb b/spec/models/concerns/ignorable_column_spec.rb
new file mode 100644
index 00000000000..dba9fe43327
--- /dev/null
+++ b/spec/models/concerns/ignorable_column_spec.rb
@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe IgnorableColumn do
+  let :base_class do
+    Class.new do
+      def self.columns
+        # This method does not have access to "double"
+        [Struct.new(:name).new('id'), Struct.new(:name).new('title')]
+      end
+    end
+  end
+
+  let :model do
+    Class.new(base_class) do
+      include IgnorableColumn
+    end
+  end
+
+  describe '.columns' do
+    it 'returns the columns, excluding the ignored ones' do
+      model.ignore_column(:title)
+
+      expect(model.columns.map(&:name)).to eq(%w(id))
+    end
+  end
+
+  describe '.ignored_columns' do
+    it 'returns a Set' do
+      expect(model.ignored_columns).to be_an_instance_of(Set)
+    end
+
+    it 'returns the names of the ignored columns' do
+      model.ignore_column(:title)
+
+      expect(model.ignored_columns).to eq(Set.new(%w(title)))
+    end
+  end
+end