database_slave 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d29bdcf5bfb9d4ba3ef24383ff365cf3f6476408
+  data.tar.gz: d9229d9c018ac2abf96ace3ff7574666b0e7087e
+SHA512:
+  metadata.gz: 0b8219a825ccacffba30827b92a38743f8dfb41835380a74f4c1edba88df788002b7a8189cf4012a5b1f89465dc534d30d4d8d0eff8bcde5da98e11aee43008a
+  data.tar.gz: c38189f41332ab653580de3938a688b681e727daa2eb2edd3c5ab62ee72c7ee21d6d6f9639dbdee01946bd95b7ea0f8ed6416bf6b000a2560dd095b75ea37fda

data/.gitignore

@@ -0,0 +1,31 @@
+*.rbc
+capybara-*.html
+.rspec
+/log
+/tmp
+/db/*.sqlite3
+/public/system
+/coverage/
+/spec/tmp
+**.orig
+rerun.txt
+pickle-email-*.html
+
+# TODO Comment out these rules if you are OK with secrets being uploaded to the repo
+config/initializers/secret_token.rb
+config/secrets.yml
+
+## Environment normalisation:
+/.bundle
+/vendor/bundle
+
+# these should all be checked in to normalise the environment:
+# Gemfile.lock, .ruby-version, .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# if using bower-rails ignore default bower_components path bower.json files
+/vendor/assets/bower_components
+*.bowerrc
+bower.json

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Hayden Wei
+
+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,75 @@
+# Database_slave
+This gem provides master and slave databases support for Rails applications. It maintains a slave database configuration in config/shards.yml, and treats config/database.yml as master database. Then, you can choose which database you want to use in your ActiveRecord::Relation clauses.
+
+For example, you can use slave database to execute complicated and time-consuming database queries to balance the performance of master database, or separate read and write database operations.
+
+# Requirements
+
+* Ruby  >= 2.0.0
+* Rails >= 3.2.x
+
+# Preparing
+
+1. First of all, create a file named **shards.yml** in your Rails config directory,
+  its content is very similar to config/database.yml:
+
+  ```
+  development:
+    slave_database1:
+      adapter: mysql2
+      encoding: utf8
+      reconnect: false
+      port : 3306
+      pool: 5
+      username: root
+      password: test
+      host: 127.0.0.1
+      database: books
+
+    slave_database2:
+      adapter: mysql2
+      ...
+      ...
+  test:
+    slave_database1:
+      ...
+  production:
+    slave_database1:
+      ...
+  ```
+
+2. Then add following to your settings.yml file:
+
+  ```
+  using_slave: true
+  ```
+
+  **true** means you can use slave database, **false** means not.
+
+# Usage
+
+There are two ways to use slave database:
+
+1. **Single Use**: Append `using_slave(:slave_database_name)` to each ActiveRecord::Relation clause.
+
+  Example:
+
+  ```ruby
+  Book.where(id: 5).using_slave(:books_slave_database)
+  ```
+
+2. **With Block**: In this way, all of queries in the block will use slave_database to execute queries.
+  With this you don't need to append `using_slave()` to each queries.
+
+  Example:
+
+  ```ruby
+  Book.using_slave(:books_slave_database) do
+    books1 = Book.where(id: 9)
+    books2 = Book.where('id > 100')
+  end
+  ```
+
+# License
+
+See LICENSE file.

data/TODOLIST

@@ -0,0 +1,4 @@
+* 添加容错处理, 包括检查配置文件等
+* 添加测试代码
+* 需要优化代码: 只允许gem外部代码read slave_name, 不允许write(出于安全考虑)
+* 添加generator自动生成config/shards.yml.example

data/database_slave.gemspec

@@ -0,0 +1,17 @@
+path = File.expand_path("../lib", __FILE__)
+$:.unshift(path) unless $:.include? path
+require 'database_slave/version'
+
+Gem::Specification.new do |gem|
+  gem.name                  = 'database_slave'
+  gem.version               = DatabaseSlave::VERSION
+  gem.date                  = '2015-03-17'
+  gem.summary               = "Provide master and slave databases support for Rails applications."
+  gem.description           = "Provide master and slave databases support for Rails applications."
+  gem.authors               = ["Hayden Wei"]
+  gem.email                 = 'haidongrun@gmail.com'
+  gem.homepage              = 'https://github.com/Gnodiah/database_slave'
+  gem.license               = 'MIT'
+  gem.files                 = `git ls-files`.split("\n")
+  gem.required_ruby_version = '>= 2.0.0'
+end

data/lib/database_slave/base.rb

@@ -0,0 +1,16 @@
+module DatabaseSlave
+  module Base
+    extend ActiveSupport::Concern
+
+    included do
+      cattr_accessor :slave_connections
+      self.slave_connections = []
+
+      class << self
+        delegate :using_slave, to: :scoped
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:include, DatabaseSlave::Base)

data/lib/database_slave/configuration.rb

@@ -0,0 +1,21 @@
+module DatabaseSlave
+  def self.configurations
+    Configuration.new.config
+  end
+
+  # TODO 错误检查, 边界条件检查
+  class Configuration
+    attr_reader :config
+
+    def initialize(*)
+      @config = database_configuration[Rails.env]
+    end
+
+    private
+
+    def database_configuration
+      require 'erb'
+      YAML::load(ERB.new(IO.read("#{Rails.root}/config/shards.yml")).result)
+    end
+  end
+end

data/lib/database_slave/connection_handler.rb

@@ -0,0 +1,90 @@
+module DatabaseSlave
+  class ConnectionHandler
+    # === Description
+    #
+    # 该方法根据 DatabaseSlave::Configuration 的配置建立所有的数据库从库链接.
+    #
+    # Rails在启动时会调用 ActiveRecord::Base.establish_connection 来建立database.yml连接,
+    # 以上方法定义在 active_record/connection_adapters/abstract/connection_specification.rb
+    #
+    # 故该方法的设计参考了以上方法, 遵循了以上方法的设计逻辑.
+    #
+    # 注意下面方法中 **klass** 的实现:
+    #   因为remove_connection方法需要一个类名作为参数, 然后会在该类名上调用name方法.
+    #   查看源码可知原方法传入的是self, 即当前调用类; 类自带了name方法.
+    #
+    #   同理, 这里我们也应该传入一个类名, 但self不是所期望的, 于是这里使用了
+    #   
+    #     self.const_set(slave_name.to_s.strip.camelize, Class.new)
+    #
+    #   的方式动态地创建了一个类.
+    #
+    #   此外, 还可以通过定义一个代理类Proxy然后实现name方法的方式来达到目的.
+    #
+    def self.establish_connection
+      ActiveRecord::Base.slave_connections ||= []
+
+      DatabaseSlave.configurations.each do |slave_name, config|
+        adapter_method = "#{config['adapter']}_connection"
+        spec           = ActiveRecord::Base::ConnectionSpecification.new(config, adapter_method)
+        klass          = self.const_set(slave_name.to_s.strip.camelize, Class.new)
+
+        unless ActiveRecord::Base.respond_to?(spec.adapter_method)
+          raise "AdapterNotFound: database configuration specifies nonexistent #{config['adapter']} adapter"
+        end
+
+        ActiveRecord::Base.slave_connections << klass.name
+        ActiveRecord::Base.remove_connection klass
+        ActiveRecord::Base.connection_handler.establish_connection klass.name, spec
+      end
+    end
+  end
+
+  # === Description
+  # 
+  # 当真正要执行一条SQL语句的时候, Rails会调用
+  #   ActiveRecord::Base.connection
+  #
+  # 方法到连接池中获取一个数据库连接. 以上方法定义在:
+  #   activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
+  #
+  # 而ActiveRecord::Base.connection则调用的是:
+  #   ActiveRecord::Base.connection_handler.retrieve_connection(klass)
+  #
+  # 由此可知, 要想获取到的是从库连接而非主库连接, 那么上述方法的klass就需要
+  # 传入之前建立的从库连接的class名而不是默认的self.
+  #
+  # 因此, 我们在这里重写了ActiveRecord::Base.connection方法, 在其中增加了在什么时候应该使用
+  # 从库连接的判断, 并用Module#prepend方法将我们重写后的connection方法加载到ActiveRecord::Base
+  # 的前面, 以便我们重写后的connection方法比ActiveRecord::Base.connection方法先执行.
+  #
+  module Connection
+    def self.prepended(base)
+      class << base
+        prepend ClassMethods
+      end
+    end
+
+    module ClassMethods
+      def connection
+        klass = self
+
+        if Settings.using_slave && slave_connection_exists?
+          slave_name = DatabaseSlave::RuntimeRegistry.current_slave_name
+          klass      = DatabaseSlave.const_get(slave_name)
+        end
+
+        ActiveRecord::Base.connection_handler.retrieve_connection(klass)
+      end
+
+      private
+
+      def slave_connection_exists?
+        slave_name = DatabaseSlave::RuntimeRegistry.current_slave_name
+        slave_name && ActiveRecord::Base.slave_connections.include?(slave_name)
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:prepend, DatabaseSlave::Connection)

data/lib/database_slave/railtie.rb

@@ -0,0 +1,21 @@
+module DatabaseSlave
+  class Railtie < Rails::Railtie
+    # === Description
+    #
+    # 此处参考Rails启动时建立database.yml连接的方式, 来实现
+    # 在Rails启动时就建立好所有的从库链接.
+    #
+    #   参考文件为 activerecord/lib/active_record/railtie.rb
+    #   initializer "active_record.initialize_database"
+    #
+    #   在上面的initializer中Rails会调用
+    #     ActiveRecord::Base.establish_connection
+    #   来建立database.yml连接.
+    #
+    initializer 'database_slave.initialize_slave_database' do
+      Rails.logger.info "Connecting to slave database specified by shards.yml"
+
+      DatabaseSlave::ConnectionHandler.establish_connection
+    end
+  end
+end

data/lib/database_slave/relation.rb

@@ -0,0 +1,79 @@
+module DatabaseSlave
+  module Relation
+    attr_accessor :slave_name
+
+    def initialize(klass, table)
+      slave_name = nil
+      if (slave = ActiveRecord::Relation.class_variable_get(:@@slave_block_given)).present?
+        self.slave_name = slave
+      end
+
+      super
+    end
+
+    def using_slave?
+      slave_name.to_s.present?
+    end
+
+    def unusing_slave
+      slave_name = nil
+
+      self
+    end
+
+    def using_slave(slave_name)
+      if Settings.using_slave
+        if block_given?
+          name = "DatabaseSlave::ConnectionHandler::#{slave_name.to_s.strip.camelize}"
+          ActiveRecord::Relation.class_variable_set(:@@slave_block_given, name)
+          begin
+            yield
+          ensure
+            ActiveRecord::Relation.class_variable_set(:@@slave_block_given, nil)
+            DatabaseSlave::RuntimeRegistry.current_slave_name = nil
+          end
+        else
+          self.slave_name = "DatabaseSlave::ConnectionHandler::#{slave_name.to_s.strip.camelize}"
+          relation = clone
+
+          if ActiveRecord::Base.slave_connections.include? self.slave_name
+            relation
+          else
+            raise "#{slave_name} is not exist."
+          end
+        end
+      else
+        clone
+      end
+    end
+
+    # alias using using_slave
+
+    # === Description
+    #
+    # Rails中所有的relation最后都是调用to_a后返回最终结果.
+    #
+    # 这里我们重写ActiveRecord::Relation的to_a方法只是为了做一件事:
+    #
+    #   必须在当前relation返回后将是否使用从库的标识设置为否, 
+    #   以免影响执行下一个relation时的主从库选择错误.
+    #
+    # 对应到代码即:
+    #   DatabaseSlave::RuntimeRegistry.current_slave_name = nil
+    #
+    def to_a
+      DatabaseSlave::RuntimeRegistry.current_slave_name = slave_name if using_slave?
+
+      super
+    ensure
+      DatabaseSlave::RuntimeRegistry.current_slave_name = nil
+    end if defined?(Rails)
+  end
+
+  def self.prepended(klass)
+    klass.send :prepend, Relation
+  end
+end
+
+ActiveRecord::Relation.send(:prepend, DatabaseSlave::Relation)
+ActiveRecord::Relation.class_variable_set(:@@slave_block_given, nil)

data/lib/database_slave/runtime_registry.rb

@@ -0,0 +1,40 @@
+# 该类定义拷贝自Rails 4.0.0 的 lib/active_support/per_thread_registry.rb
+# 因为Rails 3.x 没有该文件.
+module ActiveSupport
+  module PerThreadRegistry
+    protected
+
+    def method_missing(name, *args, &block) # :nodoc:
+      # Caches the method definition as a singleton method of the receiver.
+      define_singleton_method(name) do |*a, &b|
+        per_thread_registry_instance.public_send(name, *a, &b)
+      end
+
+      send(name, *args, &block)
+    end
+
+    private
+
+    def per_thread_registry_instance
+      Thread.current[name] ||= new
+    end
+  end
+end
+
+module DatabaseSlave
+  # This is a thread locals registry for Active Record. For example:
+  #
+  #   ActiveRecord::RuntimeRegistry.connection_handler
+  #
+  # returns the connection handler local to the current thread.
+  #
+  # See the documentation of <tt>ActiveSupport::PerThreadRegistry</tt>
+  # for further details.
+  # 该类定义拷贝自Rails 4.0.0 的 lib/active_record/runtime_registry.rb
+  # 因为Rails 3.x 没有该文件.
+  class RuntimeRegistry # :nodoc:
+    extend ActiveSupport::PerThreadRegistry
+
+    attr_accessor :current_slave_name
+  end
+end

data/lib/database_slave/version.rb

@@ -0,0 +1,3 @@
+module DatabaseSlave
+  VERSION = '0.1.0'
+end

data/lib/database_slave.rb

@@ -0,0 +1,6 @@
+require 'database_slave/base'
+require 'database_slave/configuration'
+require 'database_slave/connection_handler'
+require 'database_slave/runtime_registry'
+require 'database_slave/relation'
+require 'database_slave/railtie'

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: database_slave
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hayden Wei
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-17 00:00:00.000000000 Z
+dependencies: []
+description: Provide master and slave databases support for Rails applications.
+email: haidongrun@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE
+- README.md
+- TODOLIST
+- database_slave.gemspec
+- lib/database_slave.rb
+- lib/database_slave/base.rb
+- lib/database_slave/configuration.rb
+- lib/database_slave/connection_handler.rb
+- lib/database_slave/railtie.rb
+- lib/database_slave/relation.rb
+- lib/database_slave/runtime_registry.rb
+- lib/database_slave/version.rb
+homepage: https://github.com/Gnodiah/database_slave
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Provide master and slave databases support for Rails applications.
+test_files: []