galera_cluster_migrations 0.0.1.alpha1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e24f85effe38b4e4fc180c833284be6fefab16d5
-  data.tar.gz: 216ac2decfb6691d8f78f6a55a0eba7e9158e275
+  metadata.gz: 1bc341370d48d39e1ebca83c4d827958921b7111
+  data.tar.gz: 48a1e9f27c5d19d359652db69647a62a0416565c
 SHA512:
-  metadata.gz: f784f267d056c4db43a3aede6245d94034761bf91234a6bbd118830ed6e2ec00da82bf6d0b6e5f5f97b60b9c622a70ae0a0ab8fdde66a1c97d5a79ce7daeaaf4
-  data.tar.gz: 5e76db6a96bf068af0529d4a0b3c2e4c0c1419f2f2d3d9fc7a9eaf06cd4860187a13e422f3a4a8aa98dcf1545afcbd4cafd9f3fd81ed333bcc85ff6724fab4eb
+  metadata.gz: ba9b5b5cb6fc36e458280263a296fa242575039c9d9e8f2d35f2c70086af4d5b01ba5a92379be8e4de65fc3515ec46d6ba7d7b6a7c5cd0e349a59e4fc169e060
+  data.tar.gz: 9ff4efb41bedd16edba5bd8c5feda733aa8a18fdacd982cf69f40a52e3bc74fd65744fff874d09b90565889b2730509c0fac18666e910cc38abb05939276c13d

data/README.md

@@ -1,6 +1,47 @@
 # GaleraClusterMigrations
 
-TODO: Write a gem description
+GaleraClusterMigrations helps to alleviate some of the woes of executing Rails
+database migrations with [Galera Cluster](http://galeracluster.com). Galera
+Cluster provides two options for executing DDL (Data Definition Language)
+statements: Total Order Isolation (TOI) and Rolling Schema Upgrade (RSU).
+Each has its advantages and disadvantages, but once your database reaches a
+certain size you must start considering RSU for modifications on large tables.
+
+## Total Order Isolation (TOI)
+
+TOI is the default DDL replication method in Galera Cluster. When the master
+node receives a DDL statement it sends out a replication event before starting
+the DDL processing. Every node in the cluster will processs the replicated DDL
+statement during the same "slot" in the cluster transaction stream. This
+ensures that every node in the cluster will process the schema change at the
+same time.
+
+With this guarantee you don't have to worry about schema backwards
+compatibility, but there are some drawbacks. The strict commit order will make
+every transaction wait until DDL processing is over. Meaning that altering a
+table will block any queries that are trying to access that table. For a table
+with a large number or rows, altering a table or adding an index could take
+several minutes, or longer, during which the table cannot be queried.
+
+## Rolling Schema Upgrade (RSU)
+
+To allow the rest of the cluster to continue operating at full speed Galera
+Cluster offers the RSU method for DDL statements. During RSU the node executing
+a DDL statement is desynchronized from replication for the duration of the DDL
+processing. All incoming replication events are buffered and the node will not
+send replication events to the other nodes in the cluster. When DDL processing
+is over, the node will automatically join back into the cluster and process
+missed transactions from the buffer. Once the node has rejoined and caught up
+with the rest of the cluster, you must repeat the DDL statements on the next
+node in the cluster.
+
+The RSU method will not slow down the cluster; all other transactions can
+complete at full speed on the two synced nodes. However, there are caveats that
+must be considered when using RSU. The entire session will be processed with
+RSU (i.e. any insert statements will not be replicated to the other nodes).
+Second, upgrading the schema on all nodes is a manual operation. As a result
+the schema changes must be backward compatible since queries will be processed
+against and replicated to upgraded and non-upgraded nodes.
 
 ## Installation
 
@@ -18,7 +59,66 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+GaleraClusterMigrations contains 3 components:
+
+1. An ActiveSupport concern that should be included in your database migrations,
+2. A rake task for performing database migrations on a single cluster node,
+3. And a capistrano task for remotely executing the rake task.
+
+### To Use RSU within a Migration
+
+The `GaleraClusterMigrations` ActiveSupport concern contains methods to enable
+RSU and TOI. The `#with_rsu` method is the recommended way to run migrations
+with RSU. It accepts a block and will enable RSU for the duration of the block
+and then re-enable TOI.
+
+The first step is to include the `GaleraClusterMigrations` module in your
+migration and use the `#with_rsu` method to enable RSU for DDL statements
+specified inside a block:
+
+    # db/migrate/20140710000000_add_foo_to_bars.rb
+    class AddFooToBars < ActiveRecord::Migration
+      include GaleraClusterMigrations
+
+      def change
+        with_rsu do
+          add_column :bars, :foo, :integer, default: 0
+        end
+      end
+    end
+
+The `add_column` statement above will be executed in RSU mode when the migration
+is run.
+
+If you are using Capistrano, require `galera_cluster_migrations/capistrano` in
+your `config/deploy.rb` file and use the `galera:migrate` task to run the
+migration on each node:
+
+    # config/deploy.rb
+    ...
+    require 'galera_cluster_migrations/capistrano'
+    ...
+
+You should also disable the default `deploy:migrate` task from running during
+a deploy. Once the migration has been deployed to your cluster, execute the
+migration on each node checking that the entire cluster is in the *Synced*
+state before proceeding with the next node. Be sure to use the `HOSTFILTER`
+option to specify a single node to migrate at a time.
+
+    $ cap production galera:migrate HOSTFILTER=db1.example.com
+    # check that db1 has rejoined the cluster and is Synced
+    $ cap production galera:migrate HOSTFILTER=db2.example.com
+    # check that db2 has rejoined the cluster and is Synced
+    $ cap production galera:migrate HOSTFILTER=db3.example.com
+    # check that db3 has rejoined the cluster and is Synced
+
+You have now successfully upgraded the schema on every database node using
+RSU! During this time the two nodes not processing the migration will be
+available to process queries at full speed.
+
+For migrations that you want to run using TOI there is nothing special required
+to migrate the database. Write the database migration as you normally would and
+migrate the database with `cap production deploy:migrate`.
 
 ## Contributing
 

data/lib/galera_cluster_migrations.rb

@@ -7,7 +7,7 @@ module GaleraClusterMigrations
   require 'galera_cluster_migrations/railtie' if defined?(Rails)
 
   included do
-    def set_db_to_rsu
+    def enable_rsu
       say "Setting wsrep_OSU_method to RSU"
       unless [:development, :test].include?(Rails.env)
         execute "SET GLOBAL wsrep_OSU_method=RSU"
@@ -29,7 +29,7 @@ module GaleraClusterMigrations
       end
     end
 
-    def set_db_to_toi
+    def enable_toi
       say "Setting wsrep_OSU_method to TOI"
       unless [:development, :test].include?(Rails.env)
         execute "SET GLOBAL wsrep_OSU_method=TOI"

data/lib/galera_cluster_migrations/capistrano.rb

@@ -9,10 +9,6 @@ module GaleraClusterMigrations
     def self.load_into(capistrano_config)
       capistrano_config.load do
 
-        before(Capistrano::TASKS) do
-          Config.load(self)
-        end
-
         namespace :galera do
           desc <<-DESC
             Run the migrate rake task. By default, it runs this in most recently \

data/lib/galera_cluster_migrations/version.rb

@@ -1,3 +1,3 @@
 module GaleraClusterMigrations
-  VERSION = "0.0.1.alpha1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: galera_cluster_migrations
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha1
+  version: 1.0.0
 platform: ruby
 authors:
 - Bryan Traywick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-03 00:00:00.000000000 Z
+date: 2014-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -99,9 +99,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.2