replica_pools 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 87d48e4179aaed026e490fc8449b9b9b68f288cc
+  data.tar.gz: 4892116bdad80f053398ca6939104ce7f2de74a6
+SHA512:
+  metadata.gz: d98d3a9401f909fffdfad0eb313c1735c50d016d5bcd54186d61459ad20be23c5d2c83d97a451e1fbb2e39c11449058239790584c88e10f7088b11c06924c75a
+  data.tar.gz: ff7aaeb624ca01d426b6938778500e12677bde3a9ed627b37cea77eaf1da7ebf8f42f17c7ae37e7b9b033b93ff03dfb608e5148fcf8667c42c77f4051a0a34b3

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT license:
+Copyright (c) 2012 Kickstarter
+ 
+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,196 @@
+# ReplicaPools
+
+Easy Single Leader / Multiple Replica Setup for use in Ruby/Rails projects
+
+[![Build
+Status](https://travis-ci.org/kickstarter/replica_pools.png?branch=owningit)](https://travis-ci.org/kickstarter/replica_pools)
+
+## Overview
+
+ReplicaPools replaces ActiveRecord's connection with a proxy that routes database interactions to the proper connection. Safe (whitelisted) methods may go to the current replica, and all other methods go to the leader connection.
+
+ReplicaPools also provides helpers so you can customize your replica strategy. You can organize replicas into pools and cycle through them (e.g. in a before_filter). You can make the connection default to the leader, or the default replica pool, and then use block helpers to temporarily change the behavior (e.g. in an around_filter).
+
+* Uses a naming convention in database.yml to designate replica pools.
+* Defaults to a given replica pool, but may also be configured to default to leader.
+* Routes database interactions (queries) to the right connection
+  * Whitelisted queries go to the current connection (might be a replica).
+  * All queries inside a transaction run on leader.
+  * All other queries are also sent to the leader connection.
+* Supports ActiveRecord's in-memory query caching.
+* Helper methods can be used to easily load balance replicas, route traffic to different replica pools, or run directly against leader. (examples below)
+
+## Not Supported
+
+* Sharding.
+* Automatic load balancing strategies.
+* Replica weights. You can accomplish this in your own load balancing strategy.
+* Whitelisting models that always use leader.
+* Blacklisting poorly performing replicas. This could cause load spikes on your leader. Whatever provisions your database.yml should make this choice.
+
+## Installation and Setup
+
+Add to your Gemfile:
+
+    gem 'replica_pools'
+
+### Adding Replicas
+
+Add entries to your database.yml in the form of `<environment>_pool_<pool_name>_name_<db_name>`
+
+For example:
+
+    # Leader connection for production environment
+    production:
+      adapter: mysql
+      database: myapp_production
+      username: root
+      password:
+      host: localhost
+
+    # Default pool for production environment
+    production_pool_default_name_replica1:
+      adapter: mysql
+      database: replica_db1
+      username: root
+      password:
+      host: 10.0.0.2
+    production_pool_default_name_replica2:
+      ...
+
+    # Special pool for production environment
+    production_pool_admin_name_replica1:
+      ...
+    production_pool_admin_name_another_replica:
+      ...
+
+### Simulating Replicas
+
+If you don't have any replicas (e.g. in your development environment), ReplicaPools will create a default pool containing only leader. But if you want to mimic your production environment more closely you can create a read-only mysql user and use it like a replica.
+
+    # Development connection
+    development: &dev
+      adapter: mysql
+      database: myapp_development
+      username: root
+      password:
+      host: localhost
+
+    development_pool_default_name_replica1:
+      username: readonly
+      <<: &dev
+
+Don't do this in your test environment if you use transactional tests though! The replica connections won't be able to see any fixtures or factory data.
+
+### Configuring
+
+Add a `config/initializers/replica_pools.rb` if you want to change config settings:
+
+    ReplicaPools.config.defaults_to_leader = true
+
+## Usage
+
+Toggle to next replica:
+
+    ReplicaPools.next_replica!
+
+Specify a pool besides the default:
+
+    ReplicaPools.with_pool('other_pool') { #do stuff }
+
+Specifically use the leader for a call:
+
+    ReplicaPools.with_leader { #do stuff }
+
+### Load Balancing
+
+If you have multiple replicas in a pool and you'd like to load balance requests between them, you can easily accomplish this with a `before_filter`:
+
+    class ApplicationController < ActionController::Base
+      after_filter    :switch_to_next_replica
+
+      protected
+
+      def switch_to_next_replica
+        ReplicaPools.next_replica!
+      end
+    end
+
+### Specialty Pools
+
+If you have specialized replica pools and would like to use them for different controllers or actions, you can use an `around_filter`:
+
+    class ApplicationController < ActionController::Base
+      around_filter   :use_special_replicas
+
+      protected
+
+      def use_special_replicas
+        ReplicaPools.with_pool('special'){ yield }
+      end
+    end
+
+### Replica Lag
+
+By default, writes are sent to the leader and reads are sent to replicas. But replicas might lag behind the leader by seconds or even minutes. So if you write to leader during a request you probably want to read from leader in that request as well. You may even want to read from the leader on the _next_ request, to cover redirects.
+
+Here's one way to accomplish that:
+
+    class ApplicationController < ActionController::Base
+
+      around_filter   :stick_to_leader_for_updates
+      around_filter   :use_leader_for_redirect #goes with above
+
+      def stick_to_leader_for_updates
+        if request.get?
+          yield
+        else
+          ReplicaPools.with_leader { yield }
+          session[:stick_to_leader] = 1
+        end
+      end
+
+      def use_leader_for_redirect
+        if session[:stick_to_leader]
+          session[:stick_to_leader] = nil
+          ReplicaPools.with_leader { yield }
+        else
+          yield
+        end
+      end
+    end
+
+## Running specs
+
+If you haven't already, install the rspec gem, then set up your database
+with a test database and a read_only user.
+
+To match spec/config/database.yml, you can run:
+
+    rake bootstrap
+
+From the plugin directory, run:
+
+    rspec spec
+
+## Authors
+
+Author: Dan Drabik, Lance Ivy
+
+Copyright (c) 2012-2013, Kickstarter
+
+Released under the MIT license
+
+## See also
+
+### MultiDb
+
+The project is based on:
+
+* https://github.com/schoefmax/multi_db
+
+### Masochism
+
+The original leader/replica plugin:
+
+* http://github.com/technoweenie/masochism

data/lib/replica_pools.rb

@@ -0,0 +1,63 @@
+require 'active_record'
+require 'replica_pools/config'
+require 'replica_pools/pool'
+require 'replica_pools/pools'
+require 'replica_pools/active_record_extensions'
+require 'replica_pools/hijack'
+require 'replica_pools/query_cache'
+require 'replica_pools/connection_proxy'
+
+require 'replica_pools/engine' if defined? Rails
+ActiveRecord::Base.send :include, ReplicaPools::ActiveRecordExtensions
+
+module ReplicaPools
+  class << self
+
+    def config
+      @config ||= ReplicaPools::Config.new
+    end
+
+    def setup!
+      ConnectionProxy.generate_safe_delegations
+
+      ActiveRecord::Base.send(:extend, ReplicaPools::Hijack)
+
+      log :info, "Proxy loaded with: #{pools.keys.join(', ')}"
+    end
+
+    def proxy
+      Thread.current[:replica_pools_proxy] ||= ReplicaPools::ConnectionProxy.new(
+        ActiveRecord::Base,
+        ReplicaPools.pools
+      )
+    end
+
+    def current
+      proxy.current
+    end
+
+    def next_replica!
+      proxy.next_replica!
+    end
+
+    def with_pool(*a)
+      proxy.with_pool(*a){ yield }
+    end
+
+    def with_leader
+      proxy.with_leader{ yield }
+    end
+
+    def pools
+      Thread.current[:replica_pools] ||= ReplicaPools::Pools.new
+    end
+
+    def log(level, message)
+      logger.send(level, "[ReplicaPools] #{message}")
+    end
+
+    def logger
+      ActiveRecord::Base.logger
+    end
+  end
+end

data/lib/replica_pools/active_record_extensions.rb

@@ -0,0 +1,28 @@
+module ReplicaPools
+  module ActiveRecordExtensions
+    def self.included(base)
+      base.send :extend, ClassMethods
+    end
+
+    def reload(options = nil)
+      self.class.connection_proxy.with_leader { super }
+    end
+
+    module ClassMethods
+      def connection_proxy
+        ReplicaPools.proxy
+      end
+
+      # Make sure transactions run on leader
+      # Even if they're initiated from ActiveRecord::Base
+      # (which doesn't have our hijack).
+      def transaction(options = {}, &block)
+        if self.connection.kind_of?(ConnectionProxy)
+          super
+        else
+          self.connection_proxy.with_leader { super }
+        end
+      end
+    end
+  end
+end

data/lib/replica_pools/config.rb

@@ -0,0 +1,22 @@
+module ReplicaPools
+  class Config
+    # The current environment. Normally set to Rails.env, but
+    # will default to 'development' outside of Rails apps.
+    attr_accessor :environment
+
+    # When true, all queries will go to leader unless wrapped in with_pool{}.
+    # When false, all safe queries will go to the current replica unless wrapped in with_leader{}.
+    # Defaults to false.
+    attr_accessor :defaults_to_leader
+
+    # The list of methods considered safe to send to a readonly connection.
+    # Defaults are based on Rails version.
+    attr_accessor :safe_methods
+
+    def initialize
+      @environment        = 'development'
+      @defaults_to_leader = false
+      @safe_methods       = []
+    end
+  end
+end

data/lib/replica_pools/connection_proxy.rb

@@ -0,0 +1,125 @@
+require 'active_record/connection_adapters/abstract/query_cache'
+require 'set'
+
+module ReplicaPools
+  class ConnectionProxy
+    include ReplicaPools::QueryCache
+
+    attr_accessor :leader
+    attr_accessor :leader_depth, :current, :current_pool, :replica_pools
+
+    class << self
+      def generate_safe_delegations
+        ReplicaPools.config.safe_methods.each do |method|
+          generate_safe_delegation(method) unless instance_methods.include?(method)
+        end
+      end
+
+      protected
+
+      def generate_safe_delegation(method)
+        class_eval <<-END, __FILE__, __LINE__ + 1
+          def #{method}(*args, &block)
+            route_to(current, :#{method}, *args, &block)
+          end
+        END
+      end
+    end
+
+    def initialize(leader, pools)
+      @leader       = leader
+      @replica_pools  = pools
+      @leader_depth = 0
+      @current_pool = default_pool
+
+      if ReplicaPools.config.defaults_to_leader
+        @current = leader
+      else
+        @current = current_replica
+      end
+
+      # this ivar is for ConnectionAdapter compatibility
+      # some gems (e.g. newrelic_rpm) will actually use
+      # instance_variable_get(:@config) to find it.
+      @config = current.connection_config
+    end
+
+    def with_pool(pool_name = 'default')
+      last_conn, last_pool = self.current, self.current_pool
+      self.current_pool = replica_pools[pool_name.to_sym] || default_pool
+      self.current = current_replica unless within_leader_block?
+      yield
+    ensure
+      self.current_pool = last_pool
+      self.current      = last_conn
+    end
+
+    def with_leader
+      last_conn = self.current
+      self.current = leader
+      self.leader_depth += 1
+      yield
+    ensure
+      self.leader_depth = [leader_depth - 1, 0].max
+      self.current = last_conn
+    end
+
+    def transaction(*args, &block)
+      with_leader { leader.transaction(*args, &block) }
+    end
+
+    def next_replica!
+      return if within_leader_block?
+      self.current = current_pool.next
+    end
+
+    def current_replica
+      current_pool.current
+    end
+
+    protected
+
+    def default_pool
+      replica_pools[:default] || replica_pools.values.first
+    end
+
+    # Proxies any unknown methods to leader.
+    # Safe methods have been generated during `setup!`.
+    # Creates a method to speed up subsequent calls.
+    def method_missing(method, *args, &block)
+      generate_unsafe_delegation(method)
+      send(method, *args, &block)
+    end
+
+    def within_leader_block?
+      leader_depth > 0
+    end
+
+    def generate_unsafe_delegation(method)
+      self.class_eval <<-END, __FILE__, __LINE__ + 1
+        def #{method}(*args, &block)
+          route_to(leader, :#{method}, *args, &block)
+        end
+      END
+    end
+
+    def route_to(conn, method, *args, &block)
+      conn.retrieve_connection.send(method, *args, &block)
+    rescue => e
+      ReplicaPools.log :error, "Error during ##{method}: #{e}"
+      log_proxy_state
+
+      current.retrieve_connection.verify! # may reconnect
+      raise e
+    end
+
+    private
+
+    def log_proxy_state
+      ReplicaPools.log :error, "Current Connection: #{current}"
+      ReplicaPools.log :error, "Current Pool Name: #{current_pool.name}"
+      ReplicaPools.log :error, "Current Pool Members: #{current_pool.replicas}"
+      ReplicaPools.log :error, "leader Depth: #{leader_depth}"
+    end
+  end
+end

data/lib/replica_pools/engine.rb

@@ -0,0 +1,30 @@
+require 'rails/engine'
+
+module ReplicaPools
+  class Engine < Rails::Engine
+    initializer 'replica_pools.defaults' do
+      ReplicaPools.config.environment = Rails.env
+
+      ReplicaPools.config.safe_methods =
+        if ActiveRecord::VERSION::MAJOR == 3
+          [
+            :select_all, :select_one, :select_value, :select_values,
+            :select_rows, :select, :verify!, :raw_connection, :active?, :reconnect!,
+            :disconnect!, :reset_runtime, :log, :log_info
+          ]
+        elsif ActiveRecord::VERSION::MAJOR == 4
+          [
+            :select_all, :select_one, :select_value, :select_values,
+            :select_rows, :select, :verify!, :raw_connection, :active?, :reconnect!,
+            :disconnect!, :reset_runtime, :log
+          ]
+        else
+          warn "Unsupported ActiveRecord version #{ActiveRecord.version}. Please whitelist the safe methods."
+        end
+    end
+
+    config.after_initialize do
+      ReplicaPools.setup!
+    end
+  end
+end

data/lib/replica_pools/hijack.rb

@@ -0,0 +1,24 @@
+module ReplicaPools
+  # The hijack is added to ActiveRecord::Base but only applies to
+  # its descendants. The Base.connection is left in place.
+  module Hijack
+    def self.extended(base)
+      # hijack models that have already been loaded
+      base.send(:descendants).each do |child|
+        child.hijack_connection
+      end
+    end
+
+    # hijack models that get loaded later
+    def inherited(child)
+      super
+      child.hijack_connection
+    end
+
+    def hijack_connection
+      class << self
+        alias_method :connection, :connection_proxy
+      end
+    end
+  end
+end

data/lib/replica_pools/pool.rb

@@ -0,0 +1,21 @@
+module ReplicaPools
+  class Pool
+    attr_reader :name, :replicas, :current, :size
+
+    def initialize(name, connections)
+      @name      = name
+      @replicas  = connections
+      @size      = connections.size
+      self.reset
+    end
+
+    def reset
+      @cycle   = replicas.cycle
+      self.next
+    end
+
+    def next
+      @current = @cycle.next
+    end
+  end
+end

data/lib/replica_pools/pools.rb

@@ -0,0 +1,52 @@
+require 'delegate'
+
+module ReplicaPools
+  class Pools < ::SimpleDelegator
+    include Enumerable
+
+    def initialize
+      pools = {}
+      pool_configurations.group_by{|_, name, _| name }.each do |name, set|
+        pools[name.to_sym] = ReplicaPools::Pool.new(
+          name,
+          set.map{ |conn_name, _, replica_name|
+            connection_class(name, replica_name, conn_name)
+          }
+        )
+      end
+
+      if pools.empty?
+        ReplicaPools.log :info, "No pools found for #{ReplicaPools.config.environment}. Loading a default pool with leader instead."
+        pools[:default] = ReplicaPools::Pool.new('default', [ActiveRecord::Base])
+      end
+
+      super pools
+    end
+
+    private
+
+    # finds valid pool configs
+    def pool_configurations
+      ActiveRecord::Base.configurations.map do |name, config|
+        next unless name.to_s =~ /#{ReplicaPools.config.environment}_pool_(.*)_name_(.*)/
+        [name, $1, $2]
+      end.compact
+    end
+
+    # generates a unique ActiveRecord::Base subclass for a single replica
+    def connection_class(pool_name, replica_name, connection_name)
+      class_name = "#{pool_name.camelize}#{replica_name.camelize}"
+
+      ReplicaPools.module_eval %Q{
+        class #{class_name} < ActiveRecord::Base
+          self.abstract_class = true
+          establish_connection :#{connection_name}
+          def self.connection_config
+            configurations[#{connection_name.to_s.inspect}]
+          end
+        end
+      }, __FILE__, __LINE__
+      ReplicaPools.const_get(class_name)
+    end
+  end
+end

data/lib/replica_pools/query_cache.rb

@@ -0,0 +1,35 @@
+module ReplicaPools
+  # duck-types with ActiveRecord::ConnectionAdapters::QueryCache
+  # but relies on ActiveRecord::Base.query_cache for state so we
+  # don't fragment the cache across multiple connections
+  #
+  # we could use more of ActiveRecord's QueryCache if it only
+  # used accessors for its internal ivars.
+  module QueryCache
+    query_cache_methods = ActiveRecord::ConnectionAdapters::QueryCache.instance_methods(false)
+
+    # these methods can all use the leader connection
+    (query_cache_methods - [:select_all]).each do |method_name|
+      module_eval <<-END, __FILE__, __LINE__ + 1
+        def #{method_name}(*a, &b)
+          ActiveRecord::Base.connection.#{method_name}(*a, &b)
+        end
+      END
+    end
+
+    # select_all is trickier. it needs to use the leader
+    # connection for cache logic, but ultimately pass its query
+    # through to whatever connection is current.
+    def select_all(arel, name = nil, binds = [])
+      if query_cache_enabled && !locked?(arel)
+        sql = to_sql(arel, binds)
+        cache_sql(sql, binds) { route_to(current, :select_all, sql, name, binds) }
+      else
+        route_to(current, :select_all, arel, name, binds)
+      end
+    end
+
+    # these can use the unsafe delegation built into ConnectionProxy
+    # [:insert, :update, :delete]
+  end
+end

data/lib/replica_pools/version.rb

@@ -0,0 +1,3 @@
+module ReplicaPools
+  VERSION = "1.3.0"
+end

data/spec/config/test_model.rb

@@ -0,0 +1,2 @@
+class TestModel < ActiveRecord::Base
+end

data/spec/connection_proxy_spec.rb

@@ -0,0 +1,238 @@
+require_relative 'spec_helper'
+require_relative 'config/test_model'
+
+describe ReplicaPools do
+
+  before(:each) do
+    @sql = 'SELECT NOW()'
+
+    @proxy = ReplicaPools.proxy
+    @leader = @proxy.leader.retrieve_connection
+
+    reset_proxy(@proxy)
+    create_replica_aliases(@proxy)
+  end
+
+  it 'AR::B should respond to #connection_proxy' do
+    ActiveRecord::Base.should respond_to(:connection_proxy)
+    ActiveRecord::Base.connection_proxy.should be_kind_of(ReplicaPools::ConnectionProxy)
+  end
+
+  it 'TestModel#connection should return an instance of ReplicaPools::ConnectionProxy' do
+    TestModel.connection.should be_kind_of(ReplicaPools::ConnectionProxy)
+  end
+
+  it "should generate classes for each entry in the database.yml" do
+    defined?(ReplicaPools::DefaultDb1).should_not be_nil
+    defined?(ReplicaPools::DefaultDb2).should_not be_nil
+    defined?(ReplicaPools::SecondaryDb1).should_not be_nil
+    defined?(ReplicaPools::SecondaryDb2).should_not be_nil
+    defined?(ReplicaPools::SecondaryDb3).should_not be_nil
+  end
+
+  context "with_leader" do
+    it 'should revert to previous replica connection' do
+      @proxy.current = @proxy.current_replica
+      @proxy.with_leader do
+        @proxy.current.should equal(@proxy.leader)
+      end
+      @proxy.current.name.should eq('ReplicaPools::DefaultDb1')
+    end
+
+    it 'should revert to previous leader connection' do
+      @proxy.current = @proxy.leader
+      @proxy.with_leader do
+        @proxy.current.should equal(@proxy.leader)
+      end
+      @proxy.current.should equal(@proxy.leader)
+    end
+
+    it 'should know when in block' do
+      @proxy.send(:within_leader_block?).should_not be
+      @proxy.with_leader do
+        @proxy.send(:within_leader_block?).should be
+      end
+      @proxy.send(:within_leader_block?).should_not be
+    end
+  end
+
+  context "transaction" do
+    it 'should send all to leader' do
+      @leader.should_receive(:select_all).exactly(1)
+      @default_replica1.should_receive(:select_all).exactly(0)
+
+      TestModel.transaction do
+        @proxy.select_all(@sql)
+      end
+    end
+
+    it 'should send all to leader even if transactions begins on AR::Base' do
+      @leader.should_receive(:select_all).exactly(1)
+      @default_replica1.should_receive(:select_all).exactly(0)
+
+      ActiveRecord::Base.transaction do
+        @proxy.select_all(@sql)
+      end
+    end
+  end
+
+  it 'should perform transactions on the leader, and selects outside of transaction on the replica' do
+    @default_replica1.should_receive(:select_all).exactly(2) # before and after the transaction go to replicas
+    @leader.should_receive(:select_all).exactly(5)
+    @proxy.select_all(@sql)
+    ActiveRecord::Base.transaction do
+      5.times {@proxy.select_all(@sql)}
+    end
+    @proxy.select_all(@sql)
+  end
+
+  it 'should not switch replicas automatically on selects' do
+    @default_replica1.should_receive(:select_one).exactly(6)
+    @default_replica2.should_receive(:select_one).exactly(0)
+    6.times { @proxy.select_one(@sql) }
+  end
+
+  context "next_replica!" do
+    it 'should switch to the next replica' do
+      @default_replica1.should_receive(:select_one).exactly(1)
+      @default_replica2.should_receive(:select_one).exactly(1)
+
+      @proxy.select_one(@sql)
+      @proxy.next_replica!
+      @proxy.select_one(@sql)
+    end
+
+    it 'should not switch when in a with_leader-block' do
+      @leader.should_receive(:select_one).exactly(2)
+      @default_replica1.should_not_receive(:select_one)
+      @default_replica2.should_not_receive(:select_one)
+
+      @proxy.with_leader do
+        @proxy.select_one(@sql)
+        @proxy.next_replica!
+        @proxy.select_one(@sql)
+      end
+    end
+  end
+
+  it 'should send dangerous methods to the leader' do
+    meths = [:insert, :update, :delete, :execute]
+    meths.each do |meth|
+      @default_replica1.stub(meth).and_raise(RuntimeError)
+      @leader.should_receive(meth).and_return(true)
+      @proxy.send(meth, @sql)
+    end
+  end
+
+  it "should not allow leader depth to get below 0" do
+    @proxy.instance_variable_set("@leader_depth", -500)
+    @proxy.instance_variable_get("@leader_depth").should == -500
+    @proxy.with_leader {@sql}
+    @proxy.instance_variable_get("@leader_depth").should == 0
+  end
+
+  it 'should pre-generate safe methods' do
+    @proxy.should respond_to(:select_value)
+  end
+
+  it 'should dynamically generate unsafe methods' do
+    @leader.should_receive(:unsafe).and_return(true)
+
+    @proxy.should_not respond_to(:unsafe)
+    @proxy.unsafe(@sql)
+    @proxy.should respond_to(:unsafe)
+  end
+
+  it 'should not replay errors on leader' do
+    @default_replica1.should_receive(:select_all).once.and_raise(ArgumentError.new('random message'))
+    @default_replica2.should_not_receive(:select_all)
+    @leader.should_not_receive(:select_all)
+    lambda { @proxy.select_all(@sql) }.should raise_error(ArgumentError)
+  end
+
+  it 'should reload models from the leader' do
+    foo = TestModel.create!
+    @leader.should_receive(:select_all).and_return(ActiveRecord::Result.new(["id"], ["1"]))
+    @default_replica1.should_not_receive(:select_all)
+    @default_replica2.should_not_receive(:select_all)
+    foo.reload
+  end
+
+  context "with_pool" do
+
+    it "should switch to the named pool" do
+      @proxy.with_pool('secondary') do
+        @proxy.current_pool.name.should eq('secondary')
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb1')
+      end
+    end
+
+    it "should switch to default pool if an unknown pool is specified" do
+      @proxy.with_pool('unknown') do
+        @proxy.current_pool.name.should eq('default')
+        @proxy.current.name.should eq('ReplicaPools::DefaultDb1')
+      end
+    end
+
+    it "should switch to default pool if no pool is specified" do
+      @proxy.with_pool do
+        @proxy.current_pool.name.should eq('default')
+        @proxy.current.name.should eq('ReplicaPools::DefaultDb1')
+      end
+    end
+
+    it "should cycle replicas only within the pool" do
+      @proxy.with_pool('secondary') do
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb1')
+        @proxy.next_replica!
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb2')
+        @proxy.next_replica!
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb3')
+        @proxy.next_replica!
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb1')
+      end
+    end
+
+    it "should allow switching back to leader" do
+      @proxy.with_pool('secondary') do
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb1')
+        @proxy.with_leader do
+          @proxy.current.name.should eq('ActiveRecord::Base')
+        end
+      end
+    end
+
+    it "should not switch to pool when nested inside with_leader" do
+      @proxy.current.name.should eq('ReplicaPools::DefaultDb1')
+      @proxy.with_leader do
+        @proxy.with_pool('secondary') do
+          @proxy.current.name.should eq('ActiveRecord::Base')
+        end
+      end
+    end
+
+    it "should switch back to previous pool and replica" do
+      @proxy.next_replica!
+
+      @proxy.current_pool.name.should eq('default')
+      @proxy.current.name.should eq('ReplicaPools::DefaultDb2')
+
+      @proxy.with_pool('secondary') do
+        @proxy.current_pool.name.should eq('secondary')
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb1')
+
+        @proxy.with_pool('default') do
+          @proxy.current_pool.name.should eq('default')
+          @proxy.current.name.should eq('ReplicaPools::DefaultDb2')
+        end
+
+        @proxy.current_pool.name.should eq('secondary')
+        @proxy.current.name.should eq('ReplicaPools::SecondaryDb1')
+      end
+
+      @proxy.current_pool.name.should eq('default')
+      @proxy.current.name.should eq('ReplicaPools::DefaultDb2')
+    end
+  end
+end
+

data/spec/pool_spec.rb

@@ -0,0 +1,35 @@
+require_relative 'spec_helper'
+
+describe ReplicaPools::Pool do
+
+  context "Multiple replicas" do
+    before do
+      @replicas = ["db1", "db2", "db3"]
+      @replica_pool = ReplicaPools::Pool.new("name", @replicas.clone)
+    end
+
+    specify {@replica_pool.size.should == 3}
+
+    it "should return items in a round robin fashion" do
+      @replica_pool.current.should == @replicas[0]
+      @replica_pool.next.should == @replicas[1]
+      @replica_pool.next.should == @replicas[2]
+      @replica_pool.next.should == @replicas[0]
+    end
+  end
+
+  context "Single replica" do
+    before do
+      @replicas = ["db1"]
+      @replica_pool = ReplicaPools::Pool.new("name", @replicas.clone)
+    end
+
+    specify {@replica_pool.size.should == 1}
+
+    it "should return items in a round robin fashion" do
+      @replica_pool.current.should == @replicas[0]
+      @replica_pool.next.should == @replicas[0]
+    end
+  end
+end
+

data/spec/query_cache_spec.rb

@@ -0,0 +1,86 @@
+require 'rack'
+require_relative 'spec_helper'
+
+describe ReplicaPools::QueryCache do
+  before(:each) do
+    @sql = 'SELECT NOW()'
+
+    @proxy = ReplicaPools.proxy
+    @leader = @proxy.leader.retrieve_connection
+
+    @leader.clear_query_cache
+
+    reset_proxy(@proxy)
+    create_replica_aliases(@proxy)
+  end
+
+  it 'should cache queries using select_all' do
+    ActiveRecord::Base.cache do
+      # next_replica will be called and switch to the replicaDatabase2
+      @default_replica1.should_receive(:select_all).exactly(1).and_return([])
+      @default_replica2.should_not_receive(:select_all)
+      @leader.should_not_receive(:select_all)
+      3.times { @proxy.select_all(@sql) }
+      @leader.query_cache.keys.size.should == 1
+    end
+  end
+
+  it 'should invalidate the cache on insert, delete and update' do
+    ActiveRecord::Base.cache do
+      meths = [:insert, :update, :delete, :insert, :update]
+      meths.each do |meth|
+        @leader.should_receive("exec_#{meth}").and_return(true)
+      end
+
+      @default_replica1.should_receive(:select_all).exactly(5).and_return([])
+      @default_replica2.should_receive(:select_all).exactly(0)
+      5.times do |i|
+        @proxy.select_all(@sql)
+        @proxy.select_all(@sql)
+        @leader.query_cache.keys.size.should == 1
+        @proxy.send(meths[i], '')
+        @leader.query_cache.keys.size.should == 0
+      end
+    end
+  end
+
+  describe "using querycache middleware" do
+    it 'should cache queries using select_all' do
+      mw = ActiveRecord::QueryCache.new lambda { |env|
+        @default_replica1.should_receive(:select_all).exactly(1).and_return([])
+        @default_replica2.should_not_receive(:select_all)
+        @leader.should_not_receive(:select_all)
+        3.times { @proxy.select_all(@sql) }
+        @proxy.next_replica!
+        3.times { @proxy.select_all(@sql) }
+        @proxy.next_replica!
+        3.times { @proxy.select_all(@sql)}
+        @leader.query_cache.keys.size.should == 1
+        [200, {}, nil]
+      }
+      mw.call({})
+    end
+
+    it 'should invalidate the cache on insert, delete and update' do
+      mw = ActiveRecord::QueryCache.new lambda { |env|
+        meths = [:insert, :update, :delete, :insert, :update]
+        meths.each do |meth|
+          @leader.should_receive("exec_#{meth}").and_return(true)
+        end
+
+        @default_replica1.should_receive(:select_all).exactly(5).and_return([])
+        @default_replica2.should_receive(:select_all).exactly(0)
+        5.times do |i|
+          @proxy.select_all(@sql)
+          @proxy.select_all(@sql)
+          @leader.query_cache.keys.size.should == 1
+          @proxy.send(meths[i], '')
+          @leader.query_cache.keys.size.should == 0
+        end
+        [200, {}, nil]
+      }
+      mw.call({})
+    end
+  end
+
+end

data/spec/slave_pools_spec.rb

@@ -0,0 +1,31 @@
+require_relative 'spec_helper'
+
+describe ReplicaPools do
+
+  before(:each) do
+    ReplicaPools.pools.each{|_, pool| pool.reset }
+    @proxy = ReplicaPools.proxy
+  end
+
+  it 'should delegate next_replica! call to connection proxy' do
+    @proxy.should_receive(:next_replica!).exactly(1)
+    ReplicaPools.next_replica!
+  end
+
+  it 'should delegate with_pool call to connection proxy' do
+    @proxy.should_receive(:with_pool).exactly(1)
+    ReplicaPools.with_pool('test')
+  end
+
+  it 'should delegate with_leader call to connection proxy' do
+    @proxy.should_receive(:with_leader).exactly(1)
+    ReplicaPools.with_leader
+  end
+
+  it 'should delegate current call to connection proxy' do
+    @proxy.should_receive(:current).exactly(1)
+    ReplicaPools.current
+  end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'logger'
+
+module Rails
+  def self.env
+    ActiveSupport::StringInquirer.new("test")
+  end
+end
+
+require 'active_record'
+spec_dir = File.dirname(__FILE__)
+ActiveRecord::Base.logger = Logger.new(spec_dir + "/debug.log")
+ActiveRecord::Base.configurations = YAML::load(File.open(spec_dir + '/config/database.yml'))
+
+ActiveRecord::Base.establish_connection :test
+ActiveRecord::Migration.verbose = false
+ActiveRecord::Migration.create_table(:test_models, :force => true) {}
+
+require 'replica_pools'
+ReplicaPools::Engine.initializers.each(&:run)
+ActiveSupport.run_load_hooks(:after_initialize, ReplicaPools::Engine)
+
+module ReplicaPools::Testing
+  # Creates aliases for the replica connections in each pool
+  # for easy reference in tests.
+  def create_replica_aliases(proxy)
+    proxy.replica_pools.each do |name, pool|
+      pool.replicas.each.with_index do |replica, i|
+        instance_variable_set("@#{name}_replica#{i + 1}", replica.retrieve_connection)
+      end
+    end
+  end
+
+  def reset_proxy(proxy)
+    proxy.replica_pools.each{|_, pool| pool.reset }
+    proxy.current_pool = proxy.replica_pools[:default]
+    proxy.current      = proxy.current_replica
+  end
+end
+
+RSpec.configure do |c|
+  c.include ReplicaPools::Testing
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: replica_pools
+version: !ruby/object:Gem::Version
+  version: 1.3.0
+platform: ruby
+authors:
+- Dan Drabik
+- Lance Ivy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.12
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.12
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.11
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.11
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Connection proxy for ActiveRecord for leader / replica setups.
+email: dan@kickstarter.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/replica_pools/active_record_extensions.rb
+- lib/replica_pools/config.rb
+- lib/replica_pools/connection_proxy.rb
+- lib/replica_pools/engine.rb
+- lib/replica_pools/hijack.rb
+- lib/replica_pools/pool.rb
+- lib/replica_pools/pools.rb
+- lib/replica_pools/query_cache.rb
+- lib/replica_pools/version.rb
+- lib/replica_pools.rb
+- LICENSE
+- README.md
+- spec/config/test_model.rb
+- spec/connection_proxy_spec.rb
+- spec/pool_spec.rb
+- spec/query_cache_spec.rb
+- spec/slave_pools_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/kickstarter/replica_pools
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '1.2'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: Connection proxy for ActiveRecord for leader / replica setups.
+test_files:
+- spec/config/test_model.rb
+- spec/connection_proxy_spec.rb
+- spec/pool_spec.rb
+- spec/query_cache_spec.rb
+- spec/slave_pools_spec.rb
+- spec/spec_helper.rb
+has_rdoc: