ar_mysql_flexmaster 0.0.6 → 0.0.8

data/README.md

@@ -1,6 +1,8 @@
 # ArMysqlFlexmaster
 
-TODO: Write a gem description
+Mysql Flexmaster is an adapter for ActiveRecord that allows an application node to choose
+among a list of potential masters at runtime.  It trades some properties of a more traditional
+HA solution (load balancing, middleware) for simplicity of operation.  
 
 ## Installation
 
@@ -16,9 +18,85 @@ Or install it yourself as:
 
     $ gem install ar_mysql_flexmaster
 
-## Usage
+## Configuration:
 
-TODO: Write usage instructions here
+database.yml contains a list of hosts -- all of them potential masters, all of them potential replicas.
+It should look like this:
+
+```
+production:
+  adapter: mysql_flexmaster
+  username: flex
+  hosts: ["db01:3306", "db02:3306"]
+
+production_slave:
+  adapter: mysql_flexmaster
+  username: flex
+  slave: true
+  hosts: ["db01:3306", "db02:3306"]
+```
+
+
+## How it works
+
+### Overview
+
+The mysql "READ_ONLY" flag is used to indicate a current master amongst the cluster.  Only one member 
+of the replication chain may be read-write at any given time.  The application picks in run time, based 
+on the read_only flag, which host is correct.
+
+### boot time
+
+Your activerecord application will pick a correct mysql host for the given configuration by probing hosts until 
+it finds the correct host.
+
+For master configurations (slave: true is not specified):
+
+The application will probe each host in turn, and find the mysql candidate among these nodes 
+that is read-write (SET GLOBAL READ_ONLY=0).  If it finds more than one node where READ_ONLY == 0, it will 
+abort.  
+
+For slave configurations (slave: true specified):
+
+The application will choose a replica at random from amongst those where READ_ONLY == 1. 
+
+### run time
+
+Before each transaction is begun on the master, the application checks the status of the READ_ONLY variable.
+If READ_ONLY == 0, it will proceed with the transaction as normal.  If READ_ONLY == 1, it will drop the current 
+connection and re-poll the cluster for the current master, sleeping up to a default of 5 seconds to wait for 
+the new master to be promoted.  When it finds the new master, it will begin the transaction there. 
+
+### promoting a new master
+
+*The bin/master_cut script in this project will perform steps 3-5 for you.*
+
+The process of promoting a new master to head the cluster should be as follows:
+
+1. identify a new candidate master
+1. ensure that all other replicas in the cluster are chained off the candidate master; you want the 
+   chain to look like this: 
+   
+   ```
+      <existing master> -> <candidate master> -> <other replicas>
+                                              -> <other replicas> 
+        
+   ```
+
+1. set the old master to READ_ONLY = 1
+1. record the master-bin-log position of the candidate master (if you want to re-use the old master)
+1. set the new master to READ_ONLY = 0 
+
+The application will eventually shift slave traffic to another node in the cluster, if available, and
+will drop their connection to the old master whenever a transaction is attempted, or after a certain 
+number of queries.
+
+
+### caveats, gotchas
+
+- Any explicit ( BEGIN ... END ) transaction that are in-flight when the old master goes READ_ONLY
+  will crash.  In theory there's a workaround for this problem, in pratice it's rather unwieldy due
+  to a lack of shared global variables in mysql.
 
 ## Contributing
 

data/ar_mysql_flexmaster.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "ar_mysql_flexmaster"
   gem.require_paths = ["lib"]
-  gem.version       = "0.0.6"
+  gem.version       = "0.0.8"
 
   gem.add_runtime_dependency("mysql2")
   gem.add_runtime_dependency("activerecord")

data/lib/active_record/connection_adapters/mysql_flexmaster_adapter.rb

@@ -1,3 +1,4 @@
+require 'active_record'
 require 'active_record/connection_adapters/mysql2_adapter'
 require 'timeout'
 

data/lib/ar_mysql_flexmaster.rb

@@ -1,2 +1,3 @@
+require 'active_record/connection_adapters/mysql_flexmaster_adapter'
 module ArMysqlFlexmaster
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ar_mysql_flexmaster
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-17 00:00:00.000000000 Z
+date: 2013-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mysql2
@@ -137,7 +137,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3392143039168594248
+      hash: 1068549902361046667
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -146,7 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3392143039168594248
+      hash: 1068549902361046667
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24