slave_pools 0.1.2 → 1.0.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ca6c92616b9b71f41b9a8f0acf4487266dddc08e
+  data.tar.gz: 353fe4fd321793f797ca765a6a1fbac2cd942485
+SHA512:
+  metadata.gz: e8a36182804f50de04b2c049dd671244a1b6a90dc6ab53a0ba57df3898caf171da964af02c2871e19b2a1f673ba14560cb6e797e0b950ef463f228858524d606
+  data.tar.gz: e22b49cd625efcbfc5baff7b7868f79494f0f9499d992fafc8cdccfba6580855a55c59023e0b18492db0e784dc24f32974b807b8f0d2dbdaecd3d33e37569ea8

data/README.md

@@ -0,0 +1,196 @@
+# SlavePools
+
+Easy Single Master/ Multiple Slave Setup for use in Ruby/Rails projects
+
+[![Build
+Status](https://travis-ci.org/kickstarter/slave_pools.png?branch=owningit)](https://travis-ci.org/kickstarter/slave_pools)
+
+## Overview
+
+SlavePools 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 master connection.
+
+SlavePools 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 master, 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 master.
+* 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 master.
+  * All other queries are also sent to the master 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 master. (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 master.
+* Blacklisting poorly performing replicas. This could cause load spikes on your master. Whatever provisions your database.yml should make this choice.
+
+## Installation and Setup
+
+Add to your Gemfile:
+
+    gem 'slave_pools'
+
+### Adding Replicas
+
+Add entries to your database.yml in the form of `<environment>_pool_<pool_name>_name_<db_name>`
+
+For example:
+
+    # Master 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), SlavePools will create a default pool containing only master. 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/slave_pools.rb` if you want to change config settings:
+
+    SlavePools.config.defaults_to_master = true
+
+## Usage
+
+Toggle to next replica:
+
+    SlavePools.next_slave!
+
+Specify a pool besides the default:
+
+    SlavePools.with_pool('other_pool') { #do stuff }
+
+Specifically use the master for a call:
+
+    SlavePools.with_master { #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_slave
+
+      protected
+
+      def switch_to_next_slave
+        SlavePools.next_slave!
+      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
+        SlavePools.with_pool('special'){ yield }
+      end
+    end
+
+### Replica Lag
+
+By default, writes are sent to the master and reads are sent to replicas. But replicas might lag behind the master by seconds or even minutes. So if you write to master during a request you probably want to read from master in that request as well. You may even want to read from the master on the _next_ request, to cover redirects.
+
+Here's one way to accomplish that:
+
+    class ApplicationController < ActionController::Base
+
+      around_filter   :stick_to_master_for_updates
+      around_filter   :use_master_for_redirect #goes with above
+
+      def stick_to_master_for_updates
+        if request.get?
+          yield
+        else
+          SlavePools.with_master { yield }
+          session[:stick_to_master] = 1
+        end
+      end
+
+      def use_master_for_redirect
+        if session[:stick_to_master]
+          session[:stick_to_master] = nil
+          SlavePools.with_master { 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 master/slave plugin:
+
+* http://github.com/technoweenie/masochism

data/lib/slave_pools/active_record_extensions.rb

@@ -1,23 +1,18 @@
-module SlavePoolsModule
+module SlavePools
   module ActiveRecordExtensions
     def self.included(base)
-      base.send :include, InstanceMethods
       base.send :extend, ClassMethods
       base.cattr_accessor :connection_proxy
-      # handle subclasses which were defined by the framework or plugins
-      base.send(:descendants).each do |child|
-        child.hijack_connection
-      end
     end
 
-    module InstanceMethods
-      def reload(options = nil)
-        self.connection_proxy.with_master { super }
-      end
+    def reload(options = nil)
+      self.connection_proxy.with_master { super }
     end
 
     module ClassMethods
-      # Make sure transactions always switch to the master
+      # Make sure transactions run on master
+      # 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
@@ -25,30 +20,6 @@ module SlavePoolsModule
           self.connection_proxy.with_master { super }
         end
       end
-
-      # Make sure caching always uses master connection
-      def cache(&block)
-        if ActiveRecord::Base.configurations.blank?
-          yield
-        else
-          ActiveRecord::Base.connection.cache(&block)
-        end
-      end
-
-      def inherited(child)
-        super
-        child.hijack_connection
-      end
-
-      def hijack_connection
-        return if ConnectionProxy.master_models.include?(self.to_s)
-        # logger.info "[SlavePools] hijacking connection for #{self.to_s}" # commenting out noisy logging
-        class << self
-          def connection
-            self.connection_proxy
-          end
-        end
-      end      
     end
   end
-end
+end

data/lib/slave_pools/config.rb

@@ -0,0 +1,22 @@
+module SlavePools
+  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 master unless wrapped in with_pool{}.
+    # When false, all safe queries will go to the current replica unless wrapped in with_master{}.
+    # Defaults to false.
+    attr_accessor :defaults_to_master
+
+    # 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_master = false
+      @safe_methods       = []
+    end
+  end
+end

data/lib/slave_pools/connection_proxy.rb

@@ -1,282 +1,143 @@
 require 'active_record/connection_adapters/abstract/query_cache'
 require 'set'
 
-module SlavePoolsModule
+module SlavePools
   class ConnectionProxy
-    include ActiveRecord::ConnectionAdapters::QueryCache
-    include QueryCacheCompat
-
-    # Safe methods are those that should either go to the slave ONLY or go
-    # to the current active connection.
-    SAFE_METHODS = Set.new([ :select_all, :select_one, :select_value, :select_values,
-      :select_rows, :select, :verify!, :raw_connection, :active?, :reconnect!,
-      :disconnect!, :reset_runtime, :log, :log_info ])
-
-    if ActiveRecord.const_defined?(:SessionStore) # >= Rails 2.3
-      DEFAULT_MASTER_MODELS = ['ActiveRecord::SessionStore::Session']
-    else # =< Rails 2.3
-      DEFAULT_MASTER_MODELS = ['CGI::Session::ActiveRecordStore::Session']
-    end
+    include SlavePools::QueryCache
 
     attr_accessor :master
-    attr_accessor :master_depth, :current, :current_pool
+    attr_accessor :master_depth, :current, :current_pool, :slave_pools
 
     class << self
-
-      # defaults to Rails.env if multi_db is used with Rails
-      # defaults to 'development' when used outside Rails
-      attr_accessor :environment
-
-      # a list of models that should always go directly to the master
-      #
-      # Example:
-      #
-      #  SlavePool::ConnectionProxy.master_models = ['MySessionStore', 'PaymentTransaction']
-      attr_accessor :master_models
-
-      #true or false - whether you want to include the ActionController helpers or not
-      #this allow
-
-      # if master should be the default db
-      attr_accessor :defaults_to_master
-
-      # #setting a config instance variable so that thinking sphinx,and other gems that use the connection.instance_variable_get(:@config), work correctly
-      attr_accessor :config
-
-      # Replaces the connection of ActiveRecord::Base with a proxy and
-      # establishes the connections to the slaves.
-      def setup!
-        self.master_models ||= DEFAULT_MASTER_MODELS
-        self.environment   ||= (defined?(Rails.env) ? Rails.env : 'development')
-
-        slave_pools = init_slave_pools
-        # if there are no slave pools, we just want to silently exit and not edit the ActiveRecord::Base.connection
-        if !slave_pools.empty?
-          master = ActiveRecord::Base
-          master.send :include, SlavePoolsModule::ActiveRecordExtensions
-          ActiveRecord::Observer.send :include, SlavePoolsModule::ObserverExtensions
-
-          master.connection_proxy = new(master, slave_pools)
-          master.logger.info("** slave_pools with master and #{slave_pools.length} slave_pool#{"s" if slave_pools.length > 1} (#{slave_pools.keys}) loaded.")
-        else
-          ActiveRecord::Base.logger.info(" No Slave Pools specified for this environment") #this is currently not logging
+      def generate_safe_delegations
+        SlavePools.config.safe_methods.each do |method|
+          generate_safe_delegation(method) unless instance_methods.include?(method)
         end
       end
 
       protected
 
-      def init_slave_pools
-        slave_pools = {}
-        ActiveRecord::Base.configurations.each do |name, db_config|
-          # look for dbs matching the slave_pool format and verify a test connection before adding it to the pools
-          if name.to_s =~ /#{self.environment}_pool_(.*)_name_(.*)/ && connection_valid?(db_config)
-            slave_pools = add_to_pool(slave_pools, $1, $2, name, db_config)
+      def generate_safe_delegation(method)
+        class_eval <<-END, __FILE__, __LINE__ + 1
+          def #{method}(*args, &block)
+            route_to(current, :#{method}, *args, &block)
           end
-        end
-        return slave_pools
+        END
       end
+    end
 
-      private :new
-
-    end # end class << self
-
-    def initialize(master, slave_pools)
-      @slave_pools = {}
-      slave_pools.each do |pool_name, slaves|
-        @slave_pools[pool_name.to_sym] = SlavePool.new(pool_name, slaves)
-      end
-      @master    = master
-      @reconnect = false
+    def initialize(master, pools)
+      @master       = master
+      @slave_pools  = pools
+      @master_depth = 0
       @current_pool = default_pool
-      if self.class.defaults_to_master
-        @current = @master
-        @master_depth = 1
-        @config = master.connection.instance_variable_get(:@config)
+
+      if SlavePools.config.defaults_to_master
+        @current = master
       else
-        @current = slave
-        @master_depth = 0
-        @config = @current.config_hash #setting this
+        @current = current_slave
       end
 
-    end
-
-    def default_pool
-      @slave_pools[:default] || @slave_pools.values.first #if there is no default specified, use the first pool found
-    end
-
-    def slave_pools
-      @slave_pools
-    end
-
-    def slave
-      @current_pool.current
+      # 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')
-      @current_pool = @slave_pools[pool_name.to_sym] || default_pool
-      @current = slave unless within_master_block?
+      last_conn, last_pool = self.current, self.current_pool
+      self.current_pool = slave_pools[pool_name.to_sym] || default_pool
+      self.current = current_slave unless within_master_block?
       yield
     ensure
-      @current_pool = default_pool
-      @current = slave unless within_master_block?
+      self.current_pool = last_pool
+      self.current      = last_conn
     end
 
     def with_master
-      @current = @master
-      @master_depth += 1
+      last_conn = self.current
+      self.current = master
+      self.master_depth += 1
       yield
     ensure
-      @master_depth -= 1
-      @master_depth = 0 if @master_depth < 0 # ensure that master depth never gets below 0
-      @current = slave if !within_master_block?
-    end
-
-    def within_master_block?
-      @master_depth > 0
+      self.master_depth = [master_depth - 1, 0].max
+      self.current = last_conn
     end
 
-    def transaction(start_db_transaction = true, &block)
-      with_master { @master.retrieve_connection.transaction(start_db_transaction, &block) }
+    def transaction(*args, &block)
+      with_master { master.transaction(*args, &block) }
     end
 
-    # Calls the method on master/slave and dynamically creates a new
-    # method on success to speed up subsequent calls
-    def method_missing(method, *args, &block)
-      send(target_method(method), method, *args, &block).tap do
-        create_delegation_method!(method)
-      end
-    end
-
-    # Switches to the next slave database for read operations.
-    # Fails over to the master database if all slaves are unavailable.
     def next_slave!
-      return if within_master_block? # don't if in with_master block
-      @current = @current_pool.next
-    rescue
-      @current = @master
-    end
-
-   protected
-
-    def create_delegation_method!(method)
-      self.instance_eval %Q{
-        def #{method}(*args, &block)
-          #{target_method(method)}(:#{method}, *args, &block)
-        end
-      }, __FILE__, __LINE__
-    end
-
-    def target_method(method)
-      unsafe?(method) ? :send_to_master : :send_to_current
-    end
-
-    def send_to_master(method, *args, &block)
-      reconnect_master! if @reconnect
-      @master.retrieve_connection.send(method, *args, &block)
-    rescue => e
-      log_errors(e, 'send_to_master', method)
-      raise_master_error(e)
-    end
-
-    def send_to_current(method, *args, &block)
-      reconnect_master! if @reconnect && master?
-      # logger.debug "[SlavePools] Using #{@current.name}"
-      @current = @master if unsafe?(method) #failsafe to avoid sending dangerous method to master
-      @current.retrieve_connection.send(method, *args, &block)
-    rescue Mysql2::Error, ActiveRecord::StatementInvalid => e
-      log_errors(e, 'send_to_current', method)
-      raise_master_error(e) if master?
-      logger.warn "[SlavePools] Error reading from slave database"
-      logger.error %(#{e.message}\n#{e.backtrace.join("\n")})
-      if e.message.match(/Timeout waiting for a response from the last query/)
-        # Verify that the connection is active & re-raise
-        logger.error "[SlavePools] Slave Query Timeout - do not send to master"
-        @current.retrieve_connection.verify!
-        raise e
-      else
-        logger.error "[SlavePools] Slave Query Error - sending to master"
-        send_to_master(method, *args, &block) # if cant connect, send the query to master
-      end
+      return if within_master_block?
+      self.current = current_pool.next
     end
 
-    def reconnect_master!
-      @master.retrieve_connection.reconnect!
-      @reconnect = false
+    def current_slave
+      current_pool.current
     end
 
-    def raise_master_error(error)
-      logger.fatal "[SlavePools] Error accessing master database. Scheduling reconnect"
-      @reconnect = true
-      raise error
-    end
+    protected
 
-    def unsafe?(method)
-      !SAFE_METHODS.include?(method)
+    def default_pool
+      slave_pools[:default] || slave_pools.values.first
     end
 
-    def master?
-      @current == @master
+    # Proxies any unknown methods to master.
+    # 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 logger
-      ActiveRecord::Base.logger
+    def within_master_block?
+      master_depth > 0
     end
 
-    private
-
-    def self.add_to_pool(slave_pools, pool_name, slave_name, full_db_name, db_config)
-      slave_pools[pool_name] ||= []
-      db_config_with_symbols = db_config.inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo}
-      SlavePoolsModule.module_eval %Q{
-        class #{pool_name.camelize}#{slave_name.camelize} < ActiveRecord::Base
-          self.abstract_class = true
-          establish_connection :#{full_db_name}
-          def self.config_hash
-            #{db_config_with_symbols.inspect}
-          end
+    def generate_unsafe_delegation(method)
+      self.class_eval <<-END, __FILE__, __LINE__ + 1
+        def #{method}(*args, &block)
+          route_to(master, :#{method}, *args, &block)
         end
-      }, __FILE__, __LINE__
-      slave_pools[pool_name] << "SlavePoolsModule::#{pool_name.camelize}#{slave_name.camelize}".constantize
-      return slave_pools
+      END
     end
 
-    # method to verify whether DB connection is active?
-    def self.connection_valid?(db_config = nil)
-      is_connected = false
-      if db_config
-        begin
-          ActiveRecord::Base.establish_connection(db_config)
-          ActiveRecord::Base.connection
-          is_connected = ActiveRecord::Base.connected?
-        rescue => e
-          log_errors(e, 'self.connection_valid?')
-        ensure
-          ActiveRecord::Base.establish_connection(environment) #rollback to the current environment to avoid issues
-        end
+    def route_to(conn, method, *args, &block)
+      conn.retrieve_connection.send(method, *args, &block)
+    rescue => e
+      SlavePools.log :error, "Error during ##{method}: #{e}"
+      log_proxy_state
+      raise if conn == master
+
+      if safe_to_replay(e)
+        SlavePools.log :error, %(#{e.message}\n#{e.backtrace.join("\n")})
+        SlavePools.log :error, "Replaying on master."
+        route_to(master, method, *args, &block)
+      else
+        current.retrieve_connection.verify! # may reconnect
+        raise e
       end
-      return is_connected
     end
 
-    # logging instance errors
-    def log_errors(error, sp_method, db_method)
-      logger.error "[SlavePools] - Error: #{error}"
-      logger.error "[SlavePools] - SlavePool Method: #{sp_method}"
-      logger.error "[SlavePools] - Master Value: #{@master}"
-      logger.error "[SlavePools] - Master Depth: #{@master_depth}"
-      logger.error "[SlavePools] - Current Value: #{@current}"
-      logger.error "[SlavePools] - Current Pool: #{@current_pool}"
-      logger.error "[SlavePools] - Current Pool Slaves: #{@current_pool.slaves}" if @current_pool
-      logger.error "[SlavePools] - Current Pool Name: #{@current_pool.name}" if @current_pool
-      logger.error "[SlavePools] - Reconnect Value: #{@reconnect}"
-      logger.error "[SlavePools] - Default Pool: #{default_pool}"
-      logger.error "[SlavePools] - DB Method: #{db_method}"
+    # decides whether to replay query against master based on the
+    # exception raised. this could become more sophisticated.
+    def safe_to_replay(e)
+      # don't replay queries that time out. we don't have the time, and they
+      # could be dangerous.
+      ! e.message.match(/Timeout waiting for a response from the last query/)
     end
 
-    # logging class errors
-    def self.log_errors(error, sp_method)
-      logger = ActiveRecord::Base.logger
-      logger.error "[SlavePools] - Error: #{error}"
-      logger.error "[SlavePools] - SlavePool Method: #{sp_method}"
+    private
+
+    def log_proxy_state
+      SlavePools.log :error, "Master Value: #{master}"
+      SlavePools.log :error, "Master Depth: #{master_depth}"
+      SlavePools.log :error, "Current Value: #{current}"
+      SlavePools.log :error, "Current Pool: #{current_pool}"
+      SlavePools.log :error, "Current Pool Slaves: #{current_pool.slaves}" if current_pool
+      SlavePools.log :error, "Current Pool Name: #{current_pool.name}" if current_pool
+      SlavePools.log :error, "Default Pool: #{default_pool}"
     end
   end
 end

data/lib/slave_pools/engine.rb

@@ -0,0 +1,24 @@
+require 'rails/engine'
+
+module SlavePools
+  class Engine < Rails::Engine
+    initializer 'slave_pools.defaults' do
+      SlavePools.config.environment = Rails.env
+
+      SlavePools.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
+          ]
+        else
+          warn "Unsupported ActiveRecord version #{ActiveRecord.version}. Please whitelist the safe methods."
+        end
+    end
+
+    config.after_initialize do
+      SlavePools.setup!
+    end
+  end
+end