magic_multi_connections 1.0.0

data/test/connections/native_postgresql/connection.rb

@@ -0,0 +1,20 @@
+print "Using native Postgresql\n"
+require 'logger'
+
+ActiveRecord::Base.logger = Logger.new("debug.log")
+
+db_connection_options = {
+  :adapter  => "postgresql",
+  :encoding => "utf8",
+  :database => 'magic_multi_connections_unittest'
+}
+
+db_extra_connection_options = {
+  :adapter  => "postgresql",
+  :encoding => "utf8",
+  :database => 'magic_multi_connections_extra_unittest'
+}
+
+
+ActiveRecord::Base.configurations = { 'production' => db_connection_options, 'contact_repo' => db_extra_connection_options }
+ActiveRecord::Base.establish_connection(:production)

data/test/fixtures/contact_repository.rb

@@ -0,0 +1,3 @@
+module ContactRepository
+  establish_connection :contact_repo
+end

data/test/fixtures/db_definitions/postgresql.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "people" (
+  "id" SERIAL,
+  "name" varchar(255),
+  "email" varchar(255),
+	"age" int,
+  PRIMARY KEY  ("id")
+);

data/test/fixtures/people.yml

@@ -0,0 +1,5 @@
+first:
+  id: 1
+  name: Dr Nic
+  age: 30
+  email: drnicwilliams@gmail.com

data/test/fixtures/person.rb

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

data/test/test_helper.rb

@@ -0,0 +1,71 @@
+require 'test/unit'
+require 'rubygems'
+require 'active_record'
+require 'active_record/fixtures'
+
+begin
+  require 'connection'
+rescue MissingSourceFile => e
+  # required for tests not run via test_#{adapter} rake tests, e.g. autotest
+  adapter = 'postgresql' #'sqlite'
+  require "#{File.dirname(__FILE__)}/connections/native_#{adapter}/connection"
+end
+
+require File.dirname(__FILE__) + '/../lib/magic_multi_connections'
+
+
+models = %w[person contact_repository]
+models.each { |model| require File.join(File.dirname(__FILE__), 'fixtures', model) }
+
+class Test::Unit::TestCase #:nodoc:
+  self.fixture_path = File.dirname(__FILE__) + "/fixtures/"
+  self.use_instantiated_fixtures = false
+  self.use_transactional_fixtures = true #(ENV['AR_NO_TX_FIXTURES'] != "yes")
+
+  def create_fixtures(*table_names, &block)
+    Fixtures.create_fixtures(File.dirname(__FILE__) + "/fixtures/", table_names, {}, &block)
+  end
+  
+  def assert_date_from_db(expected, actual, message = nil)
+    # SQL Server doesn't have a separate column type just for dates, 
+    # so the time is in the string and incorrectly formatted
+    if current_adapter?(:SQLServerAdapter)
+      assert_equal expected.strftime("%Y/%m/%d 00:00:00"), actual.strftime("%Y/%m/%d 00:00:00")
+    elsif current_adapter?(:SybaseAdapter)
+      assert_equal expected.to_s, actual.to_date.to_s, message
+    else
+      assert_equal expected.to_s, actual.to_s, message
+    end
+  end
+
+  def assert_queries(num = 1)
+    ActiveRecord::Base.connection.class.class_eval do
+      self.query_count = 0
+      alias_method :execute, :execute_with_query_counting
+    end
+    yield
+  ensure
+    ActiveRecord::Base.connection.class.class_eval do
+      alias_method :execute, :execute_without_query_counting
+    end
+    assert_equal num, ActiveRecord::Base.connection.query_count, "#{ActiveRecord::Base.connection.query_count} instead of #{num} queries were executed."
+  end
+
+  def assert_no_queries(&block)
+    assert_queries(0, &block)
+  end
+end
+
+def current_adapter?(type)
+  ActiveRecord::ConnectionAdapters.const_defined?(type) &&
+    ActiveRecord::Base.connection.instance_of?(ActiveRecord::ConnectionAdapters.const_get(type))
+end
+
+ActiveRecord::Base.connection.class.class_eval do
+  cattr_accessor :query_count
+  alias_method :execute_without_query_counting, :execute
+  def execute_with_query_counting(sql, name = nil)
+    self.query_count += 1
+    execute_without_query_counting(sql, name)
+  end
+end

data/test/test_magic_multi_connections.rb

@@ -0,0 +1,26 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+module NormalModule; end
+
+class TestMagicMultiConnection < Test::Unit::TestCase
+
+  def setup
+    create_fixtures :people
+  end
+  
+  def test_classes
+    assert_nothing_raised(Exception) { Person }
+    assert_equal('ActiveRecord::Base', Person.active_connection_name)
+    assert(normal_person = Person.find(1), "Cannot get Person instances")
+    assert_nothing_raised(Exception) { ContactRepository::Person }
+    assert_equal(Person, ContactRepository::Person.superclass)
+    assert_equal('ContactRepository::Person', ContactRepository::Person.name)
+    assert_equal('ContactRepository::Person', ContactRepository::Person.active_connection_name)
+    assert_equal(0, ContactRepository::Person.count)
+  end
+  
+  def test_normal_modules_shouldnt_do_anything
+    assert_raise(NameError) { NormalModule::Person }
+    
+  end
+end

data/test/test_parent_module.rb

@@ -0,0 +1,18 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+module A
+  module B
+    module C
+      class Z
+      end
+    end
+  end
+end
+
+class TestParentModule < Test::Unit::TestCase
+
+  def test_method
+    assert_equal(A::B::C, A::B::C::Z.parent_module)
+    assert_equal(Object, A.parent_module)
+  end
+end

data/test/test_preexisting_module.rb

@@ -0,0 +1,39 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+module Preexisting
+  class Person < ActiveRecord::Base
+  end
+  
+  Foo = "foo" # just to ensure it doesn't do anything stupid with non-classes
+  
+  class NotAciveRecord; end # similarly, this class should be ignored
+end
+
+module AnotherPre
+end
+
+class TestPreexistingModule < Test::Unit::TestCase
+
+  def setup
+    create_fixtures :people
+  end
+  
+  def test_update_existing_classes
+    assert_equal("ActiveRecord::Base", Preexisting::Person.active_connection_name)
+    Preexisting.establish_connection :contact_repo
+    assert_equal("Preexisting::Person", Preexisting::Person.active_connection_name)
+  end
+  
+  # Rails can dynamically load classes when requested
+  def test_update_on_load
+    AnotherPre.establish_connection :contact_repo
+    AnotherPre.class_eval <<-EOS
+      class Person < ActiveRecord::Base
+        def tester; end
+      end
+    EOS
+    assert(AnotherPre::Person.instance_methods.include?("tester"), "AnotherPre::Person should include #tester method")
+    assert_equal("AnotherPre::Person", AnotherPre::Person.name)
+    assert_equal("AnotherPre::Person", AnotherPre::Person.active_connection_name)
+  end
+end

data/website/index.html

@@ -0,0 +1,340 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>
+      Magic Multi-Connections
+  </title>
+  <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
+<style>
+
+</style>
+  <script type="text/javascript">
+    window.onload = function() {
+      settings = {
+          tl: { radius: 10 },
+          tr: { radius: 10 },
+          bl: { radius: 10 },
+          br: { radius: 10 },
+          antiAlias: true,
+          autoPad: true,
+          validTags: ["div"]
+      }
+      var versionBox = new curvyCorners(settings, document.getElementById("version"));
+      versionBox.applyCornersToAll();
+    }
+  </script>
+</head>
+<body>
+<div id="main">
+		<p><a href="/">&#x21A9; More Magic</a></p>
+    <h1 class=primary>Magic Multi-Connections</h1>
+    <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/magicmodels"; return false'>
+      Get Version
+      <a href="http://rubyforge.org/projects/magicmodels" class="numbers">1.0.0</a>
+    </div>
+    <h1>&#x2192; Ruby on Rails</h1>
+
+
+	<h1>&#x2192; ActiveRecords</h1>
+
+
+	<h2>What</h2>
+
+
+	<p>ActiveRecord models are allowed one connection to a database at a time, per class. Ruby on Rails sets up the default connection based on your database.yml configuration to automatically select <strong>development</strong>, <strong>test</strong> or <strong>production</strong>.</p>
+
+
+	<p>But, what if you want to access two or more databases &#8211; have 2+ connections open &#8211; at the same time. ActiveRecord requires that you subclass <code>ActiveRecord::Base</code>.</p>
+
+
+	<p>That prevents you doing migrations from one database to another. It prevents you using one set of model classes on two or more databases with the same schema.</p>
+
+
+	<p>Magic Multi-Connections allows you to write your models once, and use them for multiple database Rails databases at the same time. How? Using magical namespacing.</p>
+
+
+	<p><pre class="syntax"><span class="keyword">class </span><span class="class">Person</span> <span class="punct">&lt;</span> <span class="constant">ActiveRecord</span><span class="punct">::</span><span class="constant">Base</span><span class="punct">;</span> <span class="keyword">end</span>
+<span class="constant">ActiveRecord</span><span class="punct">::</span><span class="constant">Base</span><span class="punct">.</span><span class="ident">establish_connection</span> <span class="symbol">:production</span>
+<span class="constant">Person</span><span class="punct">.</span><span class="ident">connection</span> <span class="comment"># =&gt; production</span>
+
+<span class="keyword">module </span><span class="module">ContactRepository</span>
+  <span class="ident">establish_connection</span> <span class="symbol">:contact_repo</span>
+<span class="keyword">end</span>
+<span class="constant">ContactRepository</span><span class="punct">::</span><span class="constant">Person</span><span class="punct">.</span><span class="ident">connection</span> <span class="comment"># =&gt; contact_repo</span>
+
+<span class="ident">old_person</span> <span class="punct">=</span> <span class="constant">ContactRepository</span><span class="punct">::</span><span class="constant">Person</span><span class="punct">.</span><span class="ident">find_by_email</span><span class="punct">(</span><span class="ident">email</span><span class="punct">)</span>
+<span class="ident">person</span> <span class="punct">=</span> <span class="ident">old_person</span><span class="punct">.</span><span class="ident">create_as</span><span class="punct">(</span><span class="constant">Person</span><span class="punct">)</span>
+</pre></p>
+
+
+	<p>You do not have to redefine your models for the multi-connection module <code>ContactRepository</code>, they are automatically picked up for you. Magically.</p>
+
+
+	<h2>Installing</h2>
+
+
+	<p><pre class="syntax"><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">magic_multi_connections</span></pre></p>
+
+
+	<p>Rails: Add the following to the bottom of your <code>environment.rb</code> file</p>
+
+
+	<p><pre class="syntax"><span class="ident">require</span> <span class="punct">'</span><span class="string">magic_multi_connections</span><span class="punct">'</span></pre></p>
+
+
+	<p>Ruby scripts: Add the following to the top of your script</p>
+
+
+	<p><pre class="syntax"><span class="ident">require</span> <span class="punct">'</span><span class="string">rubygems</span><span class="punct">'</span>
+<span class="ident">require</span> <span class="punct">'</span><span class="string">magic_multi_connections</span><span class="punct">'</span></pre></p>
+
+
+	<h2>Demonstration with Rails</h2>
+
+
+	<p>A quick demonstration within Rails to provide a parallel &#8220;private&#8221; database for an application.</p>
+
+
+	<h3>1. Create rails app</h3>
+
+
+	<p>Using sqlite3 here, but use your preferred db:</p>
+
+
+<pre>&gt; rails privacy -d sqlite3
+&gt; cd privacy
+&gt; ruby script/generate model Person
+&gt; cp config/environments/development.rb config/environments/private.rb
+</pre>
+
+	<p>The last line allows us to play with our <strong>private</strong> database within the console and rake tasks.</p>
+
+
+	<h3>2. Edit <strong>config/database.yml</strong> and add our private database:</h3>
+
+
+	<p>Add the following to the bottom of <strong>config/database.yml</strong></p>
+
+
+	<p><pre class="syntax">
+<span class="key">private</span><span class="punct">:</span>
+  <span class="key">adapter</span><span class="punct">:</span> sqlite3
+  <span class="key">database</span><span class="punct">:</span> db/private.sqlite3
+</pre></p>
+
+
+	<h3>3. Create a database schema</h3>
+
+
+	<p>Edit <strong>db/migrate/001_create_people.rb</strong></p>
+
+
+	<p><pre class="syntax"><span class="keyword">class </span><span class="class">CreatePeople</span> <span class="punct">&lt;</span> <span class="constant">ActiveRecord</span><span class="punct">::</span><span class="constant">Migration</span>
+  <span class="keyword">def </span><span class="method">self.up</span>
+    <span class="ident">create_table</span> <span class="symbol">:people</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">t</span><span class="punct">|</span>
+      <span class="ident">t</span><span class="punct">.</span><span class="ident">column</span> <span class="symbol">:name</span><span class="punct">,</span> <span class="symbol">:string</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+
+  <span class="keyword">def </span><span class="method">self.down</span>
+    <span class="ident">drop_table</span> <span class="symbol">:people</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre></p>
+
+
+	<p>From the command line, migrate this to our <strong>development</strong> and <strong>private</strong> databases:</p>
+
+
+<pre>&gt; rake db:migrate
+&gt; rake db:migrate RAILS_ENV=private</pre>
+
+	<h3>4. Add some data to databases</h3>
+
+
+	<p><pre class="syntax"><span class="punct">&gt;</span> <span class="ident">ruby</span> <span class="ident">script</span><span class="punct">/</span><span class="ident">console</span> <span class="ident">development</span>
+<span class="punct">&gt;&gt;</span> <span class="constant">Person</span><span class="punct">.</span><span class="ident">create</span><span class="punct">(</span><span class="symbol">:name</span> <span class="punct">=&gt;</span> <span class="punct">'</span><span class="string">Nic</span><span class="punct">')</span>
+<span class="punct">&gt;&gt;</span> <span class="constant">Person</span><span class="punct">.</span><span class="ident">create</span><span class="punct">(</span><span class="symbol">:name</span> <span class="punct">=&gt;</span> <span class="punct">'</span><span class="string">Banjo</span><span class="punct">')</span>
+<span class="punct">&gt;&gt;</span> <span class="ident">exit</span>
+<span class="punct">&gt;</span> <span class="ident">ruby</span> <span class="ident">script</span><span class="punct">/</span><span class="ident">console</span> <span class="ident">private</span>
+<span class="punct">&gt;&gt;</span> <span class="constant">Person</span><span class="punct">.</span><span class="ident">create</span><span class="punct">(</span><span class="symbol">:name</span> <span class="punct">=&gt;</span> <span class="punct">'</span><span class="string">Super Magical Nic</span><span class="punct">')</span>
+<span class="punct">&gt;&gt;</span> <span class="ident">exit</span></pre></p>
+
+
+	<p>Now it should be obvious which database our app is accessing.</p>
+
+
+	<h3>5. Update environment.rb</h3>
+
+
+	<p>Edit <strong>config/environment.rb</strong> to include the library and create the <strong>Private</strong> module.</p>
+
+
+	<p>Add the following to the end of the file.</p>
+
+
+	<p><pre class="syntax">
+<span class="ident">require</span> <span class="punct">&quot;</span><span class="string">magic_multi_connections</span><span class="punct">&quot;</span>
+
+<span class="keyword">module </span><span class="module">Private</span>
+  <span class="ident">establish_connection</span> <span class="symbol">:private</span>
+<span class="keyword">end</span>
+</pre></p>
+
+
+	<p>This tells the <strong>Private</strong> module that any model class that is requested will be assigned a connection to the <strong>private</strong> database, as defined in the <strong>config/database.yml</strong> specification.</p>
+
+
+	<h3>6. Setup a controller</h3>
+
+
+	<p>Create a <strong>people</strong> controller with a <strong>index</strong> action</p>
+
+
+<pre>&gt; ruby script/generate controller people index</pre>
+
+	<p>Edit your controller <strong>app/controllers/people_controller.rb</strong></p>
+
+
+	<p><pre class="syntax"><span class="keyword">class </span><span class="class">PeopleController</span> <span class="punct">&lt;</span> <span class="constant">ApplicationController</span>
+
+  <span class="ident">before_filter</span> <span class="symbol">:check_private</span>
+  
+  <span class="keyword">def </span><span class="method">index</span>
+    <span class="attribute">@people</span> <span class="punct">=</span> <span class="attribute">@mod</span><span class="punct">::</span><span class="constant">Person</span><span class="punct">.</span><span class="ident">find</span><span class="punct">(</span><span class="symbol">:all</span><span class="punct">)</span>
+  <span class="keyword">end</span>
+
+  <span class="ident">private</span>
+  <span class="keyword">def </span><span class="method">check_private</span>
+    <span class="attribute">@mod</span> <span class="punct">=</span> <span class="ident">params</span><span class="punct">[</span><span class="symbol">:private</span><span class="punct">]</span> <span class="punct">?</span> <span class="constant">Private</span> <span class="punct">:</span> <span class="constant">Object</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre></p>
+
+
+	<p>The <strong>check_private</strong> action is a hack to demonstrate one method for selecting the database. In reality, a stupid one for hiding a &#8220;private&#8221; database, but you get the point.</p>
+
+
+	<p>After <strong>check_private</strong> is called, <strong>@mod</strong> is either the <strong>Object</strong> (default) module or the <strong>Private</strong> module. The <strong>Person</strong> class is accessible through either of them.</p>
+
+
+	<p>Yes, <code>@mod::Person</code> is uglier than just <code>Person</code>. Sorry.</p>
+
+
+	<h3>7. Setup the index.rhtml view</h3>
+
+
+	<p>Edit <strong>app/views/people/index.rhtml</strong></p>
+
+
+	<p><pre class="syntax">&lt;h1&gt;&lt;%= @mod::Person %&gt;&lt;/h1&gt;
+&lt;h2&gt;&lt;%= @mod::Person.active_connection_name %&gt;&lt;/h2&gt;
+
+&lt;ol&gt;
+  &lt;% @people.each do |person| -%&gt;
+  &lt;li&gt;&lt;%= &quot;#{person.name} - #{person.class}&quot; %&gt;&lt;/li&gt;
+  &lt;% end -%&gt;
+&lt;/ol&gt;
+</pre></p>
+
+
+	<h3>8. Test our multi-connection Rails app</h3>
+
+
+	<p>Launch the app</p>
+
+
+<pre>&gt; mongrel_rails start</pre>
+
+	<p>In your browser, go to <a href="http://localhost:3000/people">http://localhost:3000/people</a> and see the list of people: Nic and Banjo.</p>
+
+
+	<p>Now, to see the private database, go to <a href="http://localhost:3000/people?private=1">http://localhost:3000/people?private=1</a> and see the private list. Its so private, I won&#8217;t show it here.</p>
+
+
+	<p>Note: you may need to refresh the private url to see the results. Perhaps Rails is caching the <span class="caps">SQL</span> even though its a different connection to a different database. If you know what&#8217;s happening here, please <a href="mailto:drnicwilliams@gmail.com?subject=MMC+caching+problem">email me</a> or the <a href="mailto:magicmodels@googlegroups.com?subject=MMC+caching+problem">forum</a>. Thanks.</p>
+
+
+	<h3>9. End</h3>
+
+
+	<p>There ends our example of a Rails application using one model class to access multiple databases cleanly.</p>
+
+
+	<h2>Pre-existing modules</h2>
+
+
+	<p>In Rails, model files are placed in the <strong>app/models</strong> folder. If you place them in a subfolder, say  <strong>app/models/admin</strong>, then those model classes are access via module namespaces.</p>
+
+
+	<p>So,  <strong>app/models/admin/page.rb</strong> represents the <code>Admin::Page</code> class.</p>
+
+
+	<p>Magic Multi-Connections works for these model classes as well.</p>
+
+
+	<p><pre class="syntax"><span class="constant">Admin</span><span class="punct">.</span><span class="ident">establish_connection</span> <span class="symbol">:admin_dev</span>
+<span class="constant">Admin</span><span class="punct">::</span><span class="constant">Page</span><span class="punct">.</span><span class="ident">active_connection_name</span> <span class="comment"># =&gt; &quot;Admin::Page&quot;</span>
+</pre></p>
+
+
+	<h2>Other tricks</h2>
+
+
+	<p>The Magic Multi-Connections includes <code>diff</code> and <code>diff?</code> methods extracted from the <a href="http://tfletcher.com/svn/rails-plugins/riff/README">Riff plugin</a> by <a href="http://tfletcher.com/">Tim Fletcher</a>, so that <code>id</code> values are ignored when comparing objects from different connections/namespaces.</p>
+
+
+	<p><pre class="syntax"><span class="comment"># Detect differences between two activerecords, e.g.</span>
+<span class="ident">new_person</span> <span class="punct">=</span> <span class="constant">Person</span><span class="punct">.</span><span class="ident">find_by_username</span><span class="punct">('</span><span class="string">drnic</span><span class="punct">')</span>
+<span class="ident">old_person</span> <span class="punct">=</span> <span class="constant">ContactRepository</span><span class="punct">::</span><span class="constant">Person</span><span class="punct">.</span><span class="ident">find_by_username</span><span class="punct">('</span><span class="string">drnic</span><span class="punct">')</span>
+
+<span class="ident">new_person</span><span class="punct">.</span><span class="ident">diff?</span><span class="punct">(</span><span class="ident">old_person</span><span class="punct">)</span>   <span class="comment"># =&gt; true</span>
+
+<span class="ident">new_person</span><span class="punct">.</span><span class="ident">diff</span><span class="punct">(</span><span class="ident">old_person</span><span class="punct">)</span>    <span class="comment"># =&gt; { :name =&gt; ['Dr Nic', 'Nic'], :age =&gt; [32, 20] }</span>
+</pre></p>
+
+
+	<h2>Dr Nic&#8217;s Blog</h2>
+
+
+	<p><a href="http://www.drnicwilliams.com">http://www.drnicwilliams.com</a> &#8211; for future announcements and
+other stories and things.</p>
+
+
+	<h2>Forum</h2>
+
+
+	<p>Discussion about the Magic Multi-Connections is on the Magic Models forum:</p>
+
+
+	<p><a href="http://groups.google.com/group/magicmodels">http://groups.google.com/group/magicmodels</a></p>
+
+
+	<h2>Licence</h2>
+
+
+	<p>This code is free to use under the terms of the <span class="caps">MIT</span> licence.</p>
+
+
+	<h2>Contact</h2>
+
+
+	<p>Comments are welcome. Send an email to <a href="mailto:drnicwilliams@gmail.com">Dr Nic Williams</a>.</p>
+    <p class="coda">
+      <a href="mailto:drnicwilliams@gmail.com">Dr Nic</a>, 9th April 2007<br>
+      Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
+    </p>
+</div>
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
+</script>
+<script type="text/javascript">
+_uacct = "UA-567811-2";
+urchinTracker();
+</script>
+
+</body>
+</html>