multiple_connection_handler 0.1.0

data/README

@@ -0,0 +1,53 @@
+multiple_connection_handler
+=========
+
+A gem for Rails that provides a class, MultipleConnectionHandler, that allows
+for access to connections to any databases in the database.yml file for your
+Rails application. Quick and dirty implementation to let us do dirty things.
+
+
+Full disclosure
+=========
+
+Implemented as a singleton accessed solely through the class methods. Some
+instance methods are exposed, but you should NOT use them directly. You should
+also NOT try to instantiate multiple MultipleConnectionHandler objects.
+
+Have NOT evaluated any thread-safety of this code. In fact, it's probably
+not safe to multithread code that's will use the MultipleConnectionHandler,
+as there is no locking on cached db connections.
+
+  NOTE NOTE NOTE NOTE NOTE NOTE
+  -----------------------------
+  This should only be used if you're being bad and are executing queries via
+  raw SQL, and not using ActiveRecord methods. If you just want to specify
+  different databases for your various models, see ActiveRecord::Base
+  documentation.
+
+I admit up front this is pretty hacky in how we're piggy-backing on 
+ActiveRecord's connection pooling and ConnectionHandler. So please read
+through the code (esp. the connection() instance method) before proceeding.
+
+
+Example (yes, this is a terrible example)
+========
+
+dev_migrations = MultipleConnectionHandler.connection(:development).execute(
+  "SELECT * FROM schema_migrations")
+staging_migrations = MultipleConnectionHandler.connection(:staging).execute(
+  "SELECT * FROM schema_migrations")
+
+if dev_migrations != staging_migrations
+  Rails.logger.error "Can't push data from staging to dev right now cause " +
+                     "they're on different migrations"
+end
+
+
+Testing
+=========
+
+You may notice the lack of unit tests. Yeah, we just tested this manually.
+Probably the best, as you basically need acess to multiple dbs in order to test
+whether this functionality is working. I guess if you'd like, you could create
+some models tied to different db instances, use this to directly modify those
+models and then use the models to verify the changes. Meh.

data/lib/multiple_connection_handler.rb

@@ -0,0 +1,135 @@
+# grants access to db connections for several environments at once.
+# implemented as a singleton accessed through class methods.
+class MultipleConnectionHandler
+
+  # raised when the requested connection isn't recognized from the db config
+  # file
+  #-----------------------------------------------------------------------------
+  class UnrecognizedDatabaseError < Exception
+    def initialize(unrecognized_db_name, db_config_filename)
+      super("Database specification for '#{unrecognized_db_name}' not found " +
+            " in '#{db_config_filename}'.")
+    end
+  end
+
+  # raised when attempting to re-initialize the handler after it's already
+  # been initialized. prevents competition between two clients of the class
+  # who may attempt to change the database config file on top of one another
+  #-----------------------------------------------------------------------------
+  class DoubleInitializationError < Exception
+    def initialize
+      super("Re-initializing MultipleConnectionHandler not allowed")
+    end
+  end
+
+
+  # just a little token class to hand to the ActiveRecord ConnectionHandler 
+  # so we can piggy-back on its connection management infrastructure. it just
+  # requires an object that you can call .name on...though it's sort of
+  # expecting a (model) class object...
+  #-----------------------------------------------------------------------------
+  class DbKey
+    attr_accessor :name
+    def initialize(name)
+      self.name = name
+    end
+    def ==(other)
+      self.name == other.name
+    end
+  end
+
+  # return a db connection for the specified name, establishing new pools
+  # with the AR connection handler if necessary
+  #-----------------------------------------------------------------------------
+  def self.connection(spec_name)
+    instance.connection(spec_name)
+  end
+
+  # returns the db name for the given spec name
+  #-----------------------------------------------------------------------------
+  def self.db_name(spec_name)
+    instance.configurations[spec_name.to_s]['database']
+  end
+
+  @@static_initialized = false
+  # initialize the connections handler. only necessary to be called if
+  # overriding any default configuration. recommend against using this
+  # method explicitly and just allowing default.
+  #
+  # options:
+  #   - :config_file => the database config file to use. default is the
+  #                     rails default of ..../config/database.yml
+  #-----------------------------------------------------------------------------
+  def self.init(options = {})
+    # don't allow re-initializing. just ignore if we're already initialized
+    # unless we're asked to use a different config file
+    if @@static_initialized
+      if @@instantiated && options[:config_file] &&
+          options[:config_file] != instance.db_config_file
+
+        raise DoubleInitializationError
+      end
+    else
+      @@db_config_file = options[:config_file] || "#{RAILS_ROOT}/config/database.yml"
+      @@static_initialized = true
+    end
+
+  end
+
+  attr_accessor :db_config_file, :configurations, :handler
+  attr_accessor :established_connections
+
+  # NOTE: this method is not declared protected so that the class method can
+  # call it...but really shouldn't ever be called by external code.
+
+  # the meat of the work is done here. retrieve a connection using cached
+  # connections or get a new one.
+  #-----------------------------------------------------------------------------
+  def connection(spec_name)
+    db_key = DbKey.new(spec_name.to_s)
+
+    unless established_connections.member? db_key
+      unless configurations.include? db_key.name
+        raise UnrecognizedDatabaseError.new(db_key.name, db_config_file)
+      end
+
+      spec = configurations[db_key.name]
+
+      handler.establish_connection(db_key.name,
+        ActiveRecord::Base::ConnectionSpecification.new(spec,
+          "#{spec['adapter']}_connection"))
+
+      established_connections.add db_key.name
+    end # end connection not established yet
+
+    handler.retrieve_connection db_key
+  end
+
+  protected
+
+  # constructor
+  # arguments:
+  #   - db_config_file: filename of database configurations file (in yaml).
+  #-----------------------------------------------------------------------------
+  def initialize(config_file)
+    self.db_config_file = config_file
+    self.configurations = YAML::load(File.open(self.db_config_file))
+    self.handler = ActiveRecord::ConnectionAdapters::ConnectionHandler.new
+    self.established_connections = Set.new
+  end
+
+  @@db_config_file = nil
+  @@instantiated = false
+  # the singleton instance. create if not already created, using 
+  # config filename specified in init()
+  #-----------------------------------------------------------------------------
+  def self.instance
+    unless @@instantiated
+      self.init
+      @@instance = self.new(@@db_config_file)
+      @@instantiated = true
+    end
+    @@instance
+  end
+
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: multiple_connection_handler
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- bmpercy
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-15 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.1"
+    version: 
+description: "    Hacky utility to access dbs listed in Rails' database.yml. See README for more info.\n"
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/multiple_connection_handler.rb
+- README
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.1
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Rails utility for accessing arbitrary db connection listed in database.yml
+test_files: []
+