slavery 1.0.0

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+test_db
+test_slave_db

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Kenn Ejima
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# Slavery - Simple, conservative slave read for ActiveRecord
+
+Slavery is a simple, easy to use plugin for ActiveRecord that enables conservative slave reads, which means it doesn't automatically redirect all SELECTs to slaves. Instead, it lets you specify `Slavery.on_slave { User.count }` to send a particular query to a slave.
+
+Probably you just start off with one single database. As your app grows, you would move to master-slave replication for redundancy. At this point, all queries still go to the master and slaves are just backups. With that configuration, it's tempting to run some long-running queries on the slave. And that's exactly what Slavery does.
+
+* Conservative - Safe by default. Installing Slavery won't change your app's current behavior.
+* Future proof - No dirty hacks, simply works as a proxy for `ActiveRecord::Base.connection`.
+* Simple - Less than 100 LOC, you can read the entire source and completely stay in control.
+
+Slavery works with ActiveRecord 3 or later.
+
+## Install
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'slavery'
+```
+
+And create slave configs for each environment.
+
+```yaml
+development:
+  adapter: mysql2
+  username: root
+  database: myapp_development
+
+development_slave:
+  adapter: mysql2
+  username: root
+  database: myapp_development
+```
+
+By convention, config keys with `[env]_slave` are automatically used for slave reads.
+
+Notice that you just copied the settings for `development` to `development_slave`. For `development` and `test`, it's actually recommended as probably you don't want to have replicating multiple databases on your machine. Two connections to the same identical database should be fine for testing purpose.
+
+At this point, Slavery does nothing. Run tests and confirm that anything isn't broken.
+
+## Usage
+
+To start using Slavery, you need to add `Slavery.on_slave` in your code. Queries in the `Slavery.on_slave` block run on the slave.
+
+```ruby
+Slavery.on_slave { User.count } 	# => runs on slave
+```
+
+You can nest `on_slave` and `on_master` interchangeably. The following code works as expected.
+
+```ruby
+Slavery.on_slave do
+  ...
+  Slavery.on_master do
+    ...
+  end
+  ...
+end
+```
+
+## Read-only user
+
+For an extra safeguard, it is recommended to use a read-only user for slave access.
+
+```ruby
+development_slave:
+  adapter: mysql2
+  username: readonly
+  database: myapp_development
+```
+
+With MySQL, `GRANT SELECT` creates the user.
+
+```SQL
+GRANT SELECT ON *.* TO 'readonly'@'localhost';
+```
+
+With this setting, writes on slave should raises an exception.
+
+```ruby
+Slavery.on_slave { User.create } 	# => ActiveRecord::StatementInvalid: Mysql2::Error: INSERT command denied...
+```
+
+## Database failure
+
+When one of the master or the slave goes down, you would rewrite `database.yml` to make all queries go to the surviving database, until you recover or rebuild the failed one.
+
+In such an event, you don't want to manually remove `Slavery.on_slave` from your code. Instead, just put the following line in `config/initializers/slavery.rb`.
+
+```ruby
+Slavely.disabled = true
+```
+
+With this line, Slavery stops connection switching and all queries go to the master database.
+
+## Support for non-Rails apps
+
+If you're using ActiveRecord in a non-Rails app (e.g. Sinatra), be sure to set `Slavery.env` in the boot sequence.
+
+```ruby
+Slavery.env = 'development'
+
+ActiveRecord::Base.configurations = {
+  'development' =>        { adapter: 'mysql2', ... },
+  'development_slave' =>  { adapter: 'mysql2', ... }
+}
+ActiveRecord::Base.establish_connection(:development)
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+
+# RSpec
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/slavery.rb

@@ -0,0 +1,89 @@
+require 'slavery/version'
+require 'slavery/railtie'
+require 'active_record'
+require 'active_support/core_ext/module/attribute_accessors'
+
+module Slavery
+  extend ActiveSupport::Concern
+
+  included do
+    class << self
+      alias_method_chain :connection, :slavery
+    end
+  end
+
+  class Error < StandardError; end
+
+  mattr_accessor :disabled
+
+  module ModuleFunctions
+    def on_slave(&block)
+      ActiveRecord::Base.on_slave(&block)
+    end
+
+    def on_master(&block)
+      ActiveRecord::Base.on_master(&block)
+    end
+
+    def env
+      self.env = defined?(Rails) ? Rails.env.to_s : 'development' unless @env
+      @env
+    end
+
+    def env=(string)
+      @env = ActiveSupport::StringInquirer.new(string)
+    end
+  end
+  extend ModuleFunctions
+
+  module ClassMethods
+    def on_slave(&block)
+      with_slavery true, &block
+    end
+
+    def on_master(&block)
+      with_slavery false, &block
+    end
+
+    def with_slavery(new_value)
+      old_value = Thread.current[:on_slave] # Save for recursive nested calls
+      Thread.current[:on_slave] = new_value
+      yield
+    ensure
+      Thread.current[:on_slave] = old_value
+    end
+
+    def connection_with_slavery
+      if Thread.current[:on_slave] and slaveryable?
+        slave_connection
+      else
+        master_connection
+      end
+    end
+
+    def slaveryable?
+      inside_transaction = master_connection.open_transactions > 0
+      raise Error.new('on_slave cannot be used inside transaction block!') if inside_transaction
+
+      !Slavery.disabled
+    end
+
+    def master_connection
+      connection_without_slavery
+    end
+
+    def slave_connection
+      slave_connection_holder.connection_without_slavery
+    end
+
+    # Create an anonymous AR class to hold slave connection
+    def slave_connection_holder
+      @slave_connection_holder ||= Class.new(ActiveRecord::Base) {
+        self.abstract_class = true
+        establish_connection("#{Slavery.env}_slave")
+      }
+    rescue ActiveRecord::AdapterNotSpecified
+      raise Error.new("#{Slavery.env}_slave does not exist!")
+    end
+  end
+end

data/lib/slavery/railtie.rb

@@ -0,0 +1,11 @@
+module Slavery
+  if defined? Rails::Railtie
+  	class Railtie < Rails::Railtie
+  	  initializer 'slavery.insert_into_active_record' do |app|
+  	    ActiveSupport.on_load :active_record do
+  	      include Slavery
+  	    end
+  	  end
+  	end
+  end
+end

data/lib/slavery/version.rb

@@ -0,0 +1,3 @@
+module Slavery
+  VERSION = '1.0.0'
+end

data/slavery.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'slavery/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'slavery'
+  gem.version       = Slavery::VERSION
+  gem.authors       = ['Kenn Ejima']
+  gem.email         = ['kenn.ejima@gmail.com']
+  gem.description   = %q{Selective slave read for ActiveRecord}
+  gem.summary       = %q{Selective slave read for ActiveRecord}
+  gem.homepage      = 'https://github.com/kenn/slavery'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_runtime_dependency 'activerecord', '>= 3.0.0'
+
+  gem.add_development_dependency 'mysql2'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'sqlite3'
+end

data/spec/slavery_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+
+describe Slavery do
+  def on_slave?
+    Thread.current[:on_slave]
+  end
+
+  it 'sets thread local' do
+    Slavery.on_master { on_slave?.should == false }
+    Slavery.on_slave  { on_slave?.should == true }
+  end
+
+  it 'returns value from block' do
+    Slavery.on_master { User.count }.should == 2
+    Slavery.on_slave  { User.count }.should == 1
+  end
+
+  it 'handles nested calls' do
+    # Slave -> Slave
+    Slavery.on_slave do
+      on_slave?.should == true
+
+      Slavery.on_slave do
+        on_slave?.should == true
+      end
+
+      on_slave?.should == true
+    end
+
+    # Slave -> Master
+    Slavery.on_slave do
+      on_slave?.should == true
+
+      Slavery.on_master do
+        on_slave?.should == false
+      end
+
+      on_slave?.should == true
+    end
+  end
+
+  it 'disables in transaction' do
+    User.transaction do
+      expect { User.slaveryable? }.to raise_error(Slavery::Error)
+    end
+  end
+
+  it 'disables by configuration' do
+    Slavery.stub(:disabled).and_return(false)
+    Slavery.on_slave { User.slaveryable?.should == true }
+
+    Slavery.stub(:disabled).and_return(true)
+    Slavery.on_slave { User.slaveryable?.should == false }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,33 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'slavery'
+
+# Activate Slavery
+ActiveRecord::Base.send(:include, Slavery)
+
+# Prepare databases
+class User < ActiveRecord::Base
+end
+
+# Should be equal to Rails.env
+Slavery.env = 'test'
+
+ActiveRecord::Base.configurations = {
+  'test' =>        { adapter: 'sqlite3', database: 'test_db' },
+  'test_slave' =>  { adapter: 'sqlite3', database: 'test_slave_db' }
+}
+
+# Create two records on master
+ActiveRecord::Base.establish_connection(:test)
+ActiveRecord::Base.connection.create_table :users, force: true
+User.create
+User.create
+
+# Create one record on slave, emulating replication lag
+ActiveRecord::Base.establish_connection(:test_slave)
+ActiveRecord::Base.connection.create_table :users, force: true
+User.create
+
+# Reconnect to master
+ActiveRecord::Base.establish_connection(:test)

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: slavery
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Kenn Ejima
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Selective slave read for ActiveRecord
+email:
+- kenn.ejima@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/slavery.rb
+- lib/slavery/railtie.rb
+- lib/slavery/version.rb
+- slavery.gemspec
+- spec/slavery_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/kenn/slavery
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.19
+signing_key: 
+specification_version: 3
+summary: Selective slave read for ActiveRecord
+test_files:
+- spec/slavery_spec.rb
+- spec/spec_helper.rb
+has_rdoc: