connection_manager 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+pkg/*
+*.gem
+.bundle
+.DS_Store
+

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in rails-connection_manager.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    activerecord-connection_manager (0.0.1)
+      activerecord (~> 3.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.6.2)
+    activemodel (3.1.3)
+      activesupport (= 3.1.3)
+      builder (~> 3.0.0)
+      i18n (~> 0.6)
+    activerecord (3.1.3)
+      activemodel (= 3.1.3)
+      activesupport (= 3.1.3)
+      arel (~> 2.2.1)
+      tzinfo (~> 0.3.29)
+    activesupport (3.1.3)
+      multi_json (~> 1.0)
+    arel (2.2.1)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    i18n (0.6.0)
+    metaclass (0.0.1)
+    mocha (0.10.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.0.3)
+    rspec (2.7.0)
+      rspec-core (~> 2.7.0)
+      rspec-expectations (~> 2.7.0)
+      rspec-mocks (~> 2.7.0)
+    rspec-core (2.7.1)
+    rspec-expectations (2.7.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.7.0)
+    tzinfo (0.3.31)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord-connection_manager!
+  autotest
+  mocha
+  rspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Joshua T. Mckinney
+
+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,135 @@
+# connection_manager
+Replication and Multi-Database ActiveRecord add on.
+
+## Goals
+* Take the lib I've been using finally make something out of it ;)
+* Use connection classes instead of establish_connection on every model to ensure connection pooling
+* Focus connection management at the model level
+* Use the default database.yml as single point for all database configurations (no extra .yml files)
+* When slave objects are used in html helpers like link_to and form_for the created urls that match the master
+
+## Installation
+
+connection_manager is available through [Rubygems](https://rubygems.org/gems/connection_manager) and can be installed via:
+
+    $ gem install connection_manager
+
+## Rails 3 setup (Rails 2 untested at this time please let me know if it works for you )
+
+connection_manager assumes the primary connection for the model is the master. For standard
+models using the default connection this means the main rails database connection is the master.
+
+Example database.yml
+
+    common: &common
+    adapter: mysql2
+    username: root
+    password: *****
+    database_timezone: local
+    pool: 100
+    connect_timeout: 20
+    timeout: 900
+    socket: /tmp/mysql.sock
+  
+    development:
+      <<: *common
+      database: test_app
+
+    slave_1_test_app_development:
+      <<: *common
+      database: portal_production
+  
+    slave_2_test_app_development:
+      <<: *common
+      database: test_app
+
+    user_data_development
+      <<: *common
+      database: user_data
+
+    slave_1_user_data_development
+      <<: *common
+      database: user_data
+
+    slave_2_user_data_development
+      <<: *common
+      database: user_data
+
+In the above database.yml the Master databases are listed as "development" and "user_data_development".
+As you can see the replication database name follow a strict standard for the connection names. 
+For slave_1_test_app_development, "slave" is the name of the replication, "1" is the count, "test_app"
+is the databases name and finally the "development" is the environment. (Of course in your database.yml
+each slave would have a different connection to is replication :)
+
+
+### Setup Multiple Databases
+
+At startup connection_manager builds connection classes  to ConnectionManager::Connections
+using the connections described in your database.yml based on the current rails environment.
+
+You can use a different master by having the model inherit from one of your ConnectionManager::Connections.
+
+To view your ConnectionManager::Connections, at the Rails console type:
+
+    ruby-1.9.2-p290 :001 > ConnectionManager::Connections.all => ["TestAppConnection", "Slave1TestAppConnection", "Slave2TestAppConnection"]
+
+If your using the example database.yml your array would look like this:
+    ["TestAppConnection", "Slave1TestAppConnection", "Slave2TestAppConnection", 
+    "UserDataConnection", "Slave1UserDataConnection", "Slave2UserDataConnection"]
+
+
+
+To use one of your ConnectionManager::Connections for your models default/master database
+setup you model like the following
+    
+    class User < ConnectionManager::Connections::UserDataConnection
+        # model code ...
+    end
+
+### Replication
+
+simply add 'replicated' to you model beneath any defined associations
+    
+    class User < ConnectionManager::Connections::UserDataConnection
+        has_one :job
+        has_many :teams
+        replicated # implement replication        
+        # model code ...
+    end
+
+The replicated method addeds subclass whose names match the replication connection name and count.
+Based on the above example database.yml User class would now have User::Slave1 and User::Slave2. 
+
+You can treat your subclass like normal activerecord objects.
+    User::Slave1.first => returns results from slave_1_use_data_development 
+    User::Slave2.where(['created_at BETWEEN ? and ?',Time.now - 3.hours, Time.now]).all => returns results from slave_2_use_data_development
+
+For a more elegant implementation, connection_manager also add class methods to you main model following the
+same naming standard as the subclass creation.
+    User.slave_1.first  => returns results from slave_1_use_data_development 
+    User.slave_2.where(['created_at BETWEEN ? and ?',Time.now - 3.hours, Time.now]).all  => returns results from slave_2_use_data_development 
+
+Finally connection_manager creates an addional class method that shifts through your 
+available slave connections each time it is called using a different connection on each action.
+    User.slave.first  => returns results from slave_1_use_data_development 
+    User.slave.last =>  => returns results from slave_2_use_data_development 
+    User.slave.where(['created_at BETWEEN ? and ?',Time.now - 3.hours, Time.now]).all  => returns results from slave_1_use_data_development 
+    User.slave.where(['created_at BETWEEN ? and ?',Time.now - 5.days, Time.now]).all  => returns results from slave_2_use_data_development 
+
+## TODO's
+* add more to readme
+* more specs
+* sharding
+
+## Other activerecord Connection gems
+* [Octopus](https://github.com/tchandy/octopus)
+
+## Contributing to connection_manager
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/connection_manager.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "connection_manager/version"
+
+Gem::Specification.new do |s|
+  s.name        = "connection_manager"
+  s.version     = ConnectionManager::VERSION
+  s.authors     = ["Joshua Mckinney"]
+  s.email       = ["joshmckin@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Simplifies connecting to Muliple and Replication databases with rails and active_record}
+  s.description = %q{Simplifies connecting to Muliple and Replication databases with rails and active_record}
+
+  s.rubyforge_project = "connection_manager"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_runtime_dependency 'activerecord', '~> 3.0'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'autotest'
+  s.add_development_dependency 'mocha'
+end

data/lib/connection_manager.rb

@@ -0,0 +1,9 @@
+require "connection_manager/version"
+
+module ConnectionManager
+  require 'connection_manager/connections'
+  require 'connection_manager/associations'
+  require 'connection_manager/replication_builder'
+  require 'connection_manager/connection_manager_railtie.rb' if defined?(Rails)  
+end
+

data/lib/connection_manager/associations.rb

@@ -0,0 +1,29 @@
+module ConnectionManager
+  module Associations
+    @defined_associations
+    
+    # Stores defined associtions and their options
+    def defined_associations
+      @defined_associations ||= {}
+    end
+        
+    def belongs_to(*options)
+      defined_associations[:belongs_to] ||= []
+      defined_associations[:belongs_to] << options
+      super
+    end
+    
+    def has_many(*options)
+      defined_associations[:has_many] ||= []
+      defined_associations[:has_many] << options
+      super
+    end
+    
+    def has_one(*options)
+      defined_associations[:has_one] ||= []
+      defined_associations[:has_one] << options
+      super
+    end   
+  end
+end
+ActiveRecord::Base.extend(ConnectionManager::Associations) 

data/lib/connection_manager/connection_manager_railtie.rb

@@ -0,0 +1,9 @@
+module ConnectionManager
+  class ConnectionManagerRailtie < ::Rails::Railtie
+    initializer "connection_manager.setup" do |app|
+      
+      ConnectionManager::Connections.initialize  
+      require 'connection_manager/connections' 
+    end
+  end
+end

data/lib/connection_manager/connections.rb

@@ -0,0 +1,110 @@
+module ConnectionManager
+  class Connections
+    class << self
+      @connection_keys
+      @all
+      @replication_connections
+      @env 
+    
+      def env
+        @env ||= fetch_env
+        @env
+      end
+    
+      def env=env
+        @env = env
+      end
+    
+      # Get the current Rails environment if defined
+      # TODO add sinatra
+      def fetch_env
+        Rails.env if defined?(Rails)
+      end
+    
+      # Grab only thoses connections that correspond to the current env. If env
+      # is blank it grabs all the connection keys
+      def connection_keys
+        @connection_keys ||= ActiveRecord::Base.configurations.keys.
+          select{|n| n.match(Regexp.new("(#{env}$)"))}
+      end
+    
+      # Contains all the connection classes built
+      def all
+        @all ||= []
+      end
+    
+      # Holds connections
+      def replication_connections
+        @replication_connections ||= {}
+      end
+    
+      # Returns the database value given a connection key from the database.yml
+      def database_name_from_yml(name_from_yml)
+        ActiveRecord::Base.configurations[name_from_yml]['database'].to_s
+      end
+    
+      # Given an connection key name from the database.yml, returns the string 
+      # equivelent of the class name for that entry.
+      def connection_class_name(name_from_yml)
+        name_from_yml = name_from_yml #clean up sqlite database names
+        new_class_name = name_from_yml.gsub(Regexp.new("#{env}$"),'')
+        new_class_name = database_name_from_yml(name_from_yml) if new_class_name.blank?
+      
+        #cleanup sqlite database names
+        if new_class_name.gsub!(/(^db\/)|(\.sqlite3$)/,'')  
+          new_class_name.gsub!(Regexp.new("(\\_#{env}$)"),'')
+        end
+      
+        new_class_name = new_class_name.gsub(/\_/,' ').titleize.gsub(/ /,'')
+        new_class_name << "Connection"
+        new_class_name
+      end 
+     
+   
+    
+      def add_replication_connection(name_from_yml,new_connection)    
+        rep_name = name_from_yml.split("_")[0]
+        db_name = database_name_from_yml(name_from_yml)
+        if db_name.gsub!(/(^db\/)|(\.sqlite3$)/,'')  
+          db_name.gsub!(Regexp.new("(\\_#{env}$)"),'')
+        end
+        rep_name << "_#{db_name}"
+        rep_name = rep_name.to_sym
+        replication_connections[rep_name] ||= []
+        replication_connections[rep_name] << new_connection
+        replication_connections
+      end
+    
+    
+      def connections_for_replication(rep_collection_key)
+        replication_connections[rep_collection_key.to_sym]
+      end
+    
+      # Sets class instance attributes, then builds connection classes, while populating
+      # available_connctions and replication_connection
+      def initialize(options={})  
+        options.each do |k,v|
+          send("#{k.to_s}=",v)
+        end     
+        connection_keys.each do |connection|
+          new_connection = connection_class_name(connection)     
+          add_replication_connection(connection,new_connection)
+          build_connection_class(new_connection,connection)       
+        end
+       all
+      end 
+    
+      # Addes a conneciton subclass to AvailableConnections using the supplied
+      # class name and connection key from database.yml
+      def build_connection_class(class_name,connection_key)
+        class_eval <<-STR, __FILE__, __LINE__
+        class #{class_name} < ActiveRecord::Base
+          self.abstract_class = true
+          establish_connection("#{connection_key}")
+        end
+        STR
+        all << class_name
+      end
+    end
+  end
+end

data/lib/connection_manager/replication_builder.rb

@@ -0,0 +1,135 @@
+module ConnectionManager
+  module ReplicationBuilder
+    
+    def database_name(db_name=nil)
+      db_name = "#{connection.instance_variable_get(:@config)[:database].to_s}" if db_name.blank?
+      db_name.gsub!(/(\.sqlite3$)/,'')
+      db_name = db_name.split("/").last
+      db_name
+    end
+    
+    def replication_association_options(method,association,class_name,options={})
+      new_options = {}.merge(options)
+      if new_options[:class_name].blank?
+        new_options[:class_name] = "#{association.to_s.singularize.classify}::#{class_name}"
+      else
+        new_options[:class_name] = "#{new_options[:class_name]}::#{class_name}"
+      end
+      
+      if [:has_one,:has_many].include?(method) && new_options[:foreign_key].blank? 
+        new_options[:foreign_key] = "#{table_name.singularize}_id"
+      end     
+      new_options
+    end
+    
+    def build_replication_associations(class_name)
+      str = ""
+      defined_associations.each do |method,defs|
+        unless defs.blank?
+          defs.each do |association,options|
+            options = {} if options.blank?
+            unless options[:no_readonly] || options[:class_name].to_s.match("::#{class_name}")
+              str << "#{method.to_s} :#{association}, #{replication_association_options(method,association,class_name,options)};" 
+            end
+          end
+        end
+      end
+      str
+    end
+    
+    def replication_connection_classes(options)
+      if options[:using] && options[:using].is_a?(Array)
+        connection_classes = options[:using].collection{|c| Connections.connection_class_name(c)}
+      else  
+        connection_classes = Connections.connections_for_replication("#{options[:name].to_s}_#{database_name}") 
+      end
+      connection_classes
+    end
+    
+    # Adds subclass with the class name of the type provided in the options, which 
+    # defaults to 'slave' if blank, that uses the connection from a connection class.
+    # If :database option is blank?, replicated will assume the database.yml has
+    # slave connections defined as: slave_database_name_test or slave_1_database_name_test, 
+    # where slave_1 is the replication instance, 'database_name' is the actual 
+    # name of the database and '_test' is the Rails environment
+    def replicated(*settings)   
+      options = {:name => "slave", :readonly => true}.merge(settings.extract_options!)   
+      connection_classes = replication_connection_classes(options)  
+      if connection_classes.blank?
+        raise ArgumentError, " a replication connection was not found. Check your database.yml."
+      else   
+        connection_methods = []
+        connection_classes.each do |c|
+          under_scored = c.underscore
+          method_name = under_scored.split("_")[0]
+          method_name = method_name.insert(method_name.index(/\d/),"_")
+          class_name = method_name.classify
+          connection_methods << method_name.to_sym
+          build_replication_class(class_name,c,options)
+          build_single_replication_method(method_name,class_name)
+        end
+      end
+      build_full_replication_method(options,connection_methods)   
+  
+    end
+    
+    # Creats a subclass that inherets from the model. The default model_name 
+    # class method is overriden to return the super's name, which ensures rails
+    # helpers like link_to called on a replication stance generate a url for the
+    # master database. If options include readonly, build_replication_class also 
+    # overrides the rails "readonly?" method to ensure saves are prevented. 
+    # Replication class can be called directly for operaitons.
+    # Usage: 
+    # => User::Slave1.where(:id => 1).first => returns results from slave_1 database
+    # => User::Slave2.where(:id => 2).first => returns results from slave_1 database
+    def build_replication_class(class_name,connection_name,options)
+      class_eval <<-STR, __FILE__, __LINE__
+      class #{class_name} < #{self.name}
+        #{build_replication_associations(class_name)}
+        class << self
+          delegate :connection, :to => Connections::#{connection_name}
+          def model_name
+            @_model_name ||= ActiveModel::Name.new(#{model_name})
+          end
+        end
+        #{'def readonly?; true; end;' if (options[:name] == "readonly" || options[:readonly])}       
+      end       
+      STR
+    end
+    
+    # Adds as class method to call a specific replication conneciton.
+    # Usage:
+    # => User.slave_1.where(:id => 2).first => returns results from slave_1 database
+    # => User.slave_2.where(:id => 2).first => returns results from slave_1 database
+    def build_single_replication_method(method_name,class_name)
+      class_eval <<-STR, __FILE__, __LINE__
+        class << self
+          def #{method_name}
+            self::#{class_name}
+          end      
+        end 
+      STR
+    end
+    
+    # add a class method that shifts through available connections methods
+    # on each call.
+    # Usage:
+    # => User.slave.where(:id => 2).first => can return results from slave_1 or slave_2 
+    def build_full_replication_method(options,connection_methods)
+      class_eval <<-STR, __FILE__, __LINE__
+      @connection_methods = #{connection_methods}
+      class << self
+        def #{options[:name].to_s}
+          current = @connection_methods.shift
+          @connection_methods << current
+          send(current)
+        end
+        def connection_methods
+          @connection_methods
+        end
+      end     
+      STR
+    end
+  end
+end
+ActiveRecord::Base.extend(ConnectionManager::ReplicationBuilder)