magic_multi_connections 1.0.0 → 1.2.1

data/website/index.txt

@@ -1,223 +1,286 @@
-h1. Magic Multi-Connections
-
-h1. → Ruby on Rails
-
-h1. → ActiveRecords
-
-h2. What
-
-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 *development*, *test* or *production*.
-
-But, what if you want to access two or more databases - have 2+ connections open - at the same time. ActiveRecord requires that you subclass <code>ActiveRecord::Base</code>. 
-	
-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.
-
-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.
-
-<pre syntax="ruby">class Person < ActiveRecord::Base; end
-ActiveRecord::Base.establish_connection :production
-Person.connection # => production
-
-module ContactRepository
-  establish_connection :contact_repo
-end
-ContactRepository::Person.connection # => contact_repo
-
-old_person = ContactRepository::Person.find_by_email(email)
-person = old_person.create_as(Person)
-</pre>
-
-You do not have to redefine your models for the multi-connection module <code>ContactRepository</code>, they are automatically picked up for you. Magically.
-
-h2. Installing
-
-<pre syntax="ruby">sudo gem install magic_multi_connections</pre>
-
-Rails: Add the following to the bottom of your <code>environment.rb</code> file
-
-<pre syntax="ruby">require 'magic_multi_connections'</pre>
-
-Ruby scripts: Add the following to the top of your script
-
-<pre syntax="ruby">require 'rubygems'
-require 'magic_multi_connections'</pre>
-
-
-h2. Demonstration with Rails
-
-A quick demonstration within Rails to provide a parallel "private" database for an application.
-
-h3. 1. Create rails app
-
-Using sqlite3 here, but use your preferred db:
-
-<pre>> rails privacy -d sqlite3
-> cd privacy
-> ruby script/generate model Person
-> cp config/environments/development.rb config/environments/private.rb
-</pre>
-
-The last line allows us to play with our *private* database within the console and rake tasks.
-
-h3. 2. Edit *config/database.yml* and add our private database:
-
-Add the following to the bottom of *config/database.yml*
-
-<pre syntax="yaml">
-private:
-  adapter: sqlite3
-  database: db/private.sqlite3
-</pre>
-
-h3. 3. Create a database schema
-
-Edit *db/migrate/001_create_people.rb*
-
-<pre syntax="ruby">class CreatePeople < ActiveRecord::Migration
-  def self.up
-    create_table :people do |t|
-      t.column :name, :string
-    end
-  end
-
-  def self.down
-    drop_table :people
-  end
-end
-</pre>
-
-From the command line, migrate this to our *development* and *private* databases:
-
-<pre>> rake db:migrate
-> rake db:migrate RAILS_ENV=private</pre>
-
-h3. 4. Add some data to databases
-
-<pre syntax="ruby">> ruby script/console development
->> Person.create(:name => 'Nic')
->> Person.create(:name => 'Banjo')
->> exit
-> ruby script/console private
->> Person.create(:name => 'Super Magical Nic')
->> exit</pre>
-
-Now it should be obvious which database our app is accessing.
-
-h3. 5. Update environment.rb
-
-Edit *config/environment.rb* to include the library and create the *Private* module.
-
-Add the following to the end of the file.
-
-<pre syntax="ruby">
-require "magic_multi_connections"
-
-module Private
-  establish_connection :private
-end
-</pre>
-
-This tells the *Private* module that any model class that is requested will be assigned a connection to the *private* database, as defined in the *config/database.yml* specification.
-
-h3. 6. Setup a controller
-
-Create a *people* controller with a *index* action
-
-<pre>> ruby script/generate controller people index</pre>
-
-Edit your controller *app/controllers/people_controller.rb*
-
-<pre syntax="ruby">class PeopleController < ApplicationController
-
-  before_filter :check_private
-  
-  def index
-    @people = @mod::Person.find(:all)
-  end
-
-  private
-  def check_private
-    @mod = params[:private] ? Private : Object
-  end
-end
-</pre>
-
-The *check_private* action is a hack to demonstrate one method for selecting the database. In reality, a stupid one for hiding a "private" database, but you get the point.
-
-After *check_private* is called, *@mod* is either the *Object* (default) module or the *Private* module. The *Person* class is accessible through either of them.
-
-Yes, <code>@mod::Person</code> is uglier than just <code>Person</code>. Sorry.
-
-h3. 7. Setup the index.rhtml view
-
-Edit *app/views/people/index.rhtml*
-
-<pre syntax="html"><h1><%= @mod::Person %></h1>
-<h2><%= @mod::Person.active_connection_name %></h2>
-
-<ol>
-  <% @people.each do |person| -%>
-  <li><%= "#{person.name} - #{person.class}" %></li>
-  <% end -%>
-</ol>
-</pre>
-
-h3. 8. Test our multi-connection Rails app
-
-Launch the app
-
-<pre>> mongrel_rails start</pre>
-
-In your browser, go to "http://localhost:3000/people":http://localhost:3000/people and see the list of people: Nic and Banjo.
-
-Now, to see the private database, go to "http://localhost:3000/people?private=1":http://localhost:3000/people?private=1 and see the private list. Its so private, I won't show it here.
-
-Note: you may need to refresh the private url to see the results. Perhaps Rails is caching the SQL even though its a different connection to a different database. If you know what's happening here, please "email me":mailto:drnicwilliams@gmail.com?subject=MMC+caching+problem or the "forum":mailto:magicmodels@googlegroups.com?subject=MMC+caching+problem. Thanks.
-
-h3. 9. End
-
-There ends our example of a Rails application using one model class to access multiple databases cleanly.
-
-h2. Pre-existing modules
-
-In Rails, model files are placed in the *app/models* folder. If you place them in a subfolder, say  *app/models/admin*, then those model classes are access via module namespaces. 
-
-So,  *app/models/admin/page.rb* represents the <code>Admin::Page</code> class.
-
-Magic Multi-Connections works for these model classes as well.
-
-<pre syntax="ruby">Admin.establish_connection :admin_dev
-Admin::Page.active_connection_name # => "Admin::Page"
-</pre>
-
-h2. Other tricks
-
-The Magic Multi-Connections includes <code>diff</code> and <code>diff?</code> methods extracted from the "Riff plugin":http://tfletcher.com/svn/rails-plugins/riff/README by "Tim Fletcher":http://tfletcher.com/, so that <code>id</code> values are ignored when comparing objects from different connections/namespaces.
-
-<pre syntax="ruby"># Detect differences between two activerecords, e.g.
-new_person = Person.find_by_username('drnic')
-old_person = ContactRepository::Person.find_by_username('drnic')
-
-new_person.diff?(old_person)   # => true
-
-new_person.diff(old_person)    # => { :name => ['Dr Nic', 'Nic'], :age => [32, 20] }
-</pre>
-
-h2. Dr Nic's Blog
-
-"http://www.drnicwilliams.com":http://www.drnicwilliams.com - for future announcements and
-other stories and things.
-
-h2. Forum
-
-Discussion about the Magic Multi-Connections is on the Magic Models forum:
-
-"http://groups.google.com/group/magicmodels":http://groups.google.com/group/magicmodels
-
-h2. Licence
-
-This code is free to use under the terms of the MIT licence. 
-
-h2. Contact
-
-Comments are welcome. Send an email to "Dr Nic Williams":mailto:drnicwilliams@gmail.com.
+h1. Magic Multi-Connections
+
+h1. &#x2192; Ruby on Rails
+
+h1. &#x2192; ActiveRecords
+
+h2. WARNING
+
+Despite the 1.2.0 version number, this gem is not quite production ready.  Various people have "experienced problems":http://joshknowles.com/2007/6/17/migrations-pains using the 1.0.0 version. A solution was found to deal with this issue but it has not been fully tested, so please subscribe to the "forum":http://groups.google.com/group/magicmodels or "RubyForge news":http://rubyforge.org/export/rss_sfnewreleases.php for any updates.
+
+h2. What
+
+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 *development*, *test* or *production*.
+
+But, what if you want to access two or more databases - have 2+ connections open - at the same time. ActiveRecord requires that you subclass <code>ActiveRecord::Base</code>. 
+	
+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.
+
+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.
+
+<pre syntax="ruby">class Person < ActiveRecord::Base; end
+ActiveRecord::Base.establish_connection :production
+Person.connection # => production
+
+module ContactRepository
+  establish_connection :contact_repo
+end
+ContactRepository::Person.connection # => contact_repo
+
+old_person = ContactRepository::Person.find_by_email(email)
+person = old_person.create_as(Person)
+</pre>
+
+You do not have to redefine your models for the multi-connection module <code>ContactRepository</code>, they are automatically picked up for you. Magically.  
+
+h3. But what about associations, do they change over as well? 
+
+Yup! These are now supported, though maybe not as magically:
+
+<pre syntax="ruby">class Person < ActiveRecord::Base
+  has_many :habits, :mirrors_db_connection => true
+end
+
+class Habit < ActiveRecord::Base
+  belongs_to :person, :mirrors_db_connection => true
+end
+ActiveRecord::Base.establish_connection :production
+
+module ContactRepository
+  establish_connection :contact_repo
+end
+
+old_person = ContactRepository::Person.find_by_email(email)
+old_person.habits.first.connection # => contact_repo
+</pre>
+
+h3. Hey wait a minute, wasn't there some kind of automatic namespacing association?
+
+Yes but that has been deprecated.  In the previous version of this gem associations were handled by automatically changing any assocation whose target class was in the same namespace.  While it is still possible to do this, this automatic namespace association was at best clunky and will be removed in the 2.0 release.  Here is an example of how it works:
+
+<pre syntax="ruby">ActiveRecord::Base.establish_connection :production
+
+module Military 
+  class Soldier < ActiveRecord::Base
+    has_many :assignments
+    has_many :paychecks
+  end
+
+  class Assignment < ActiveRecord::Base
+    belongs_to :person, :mirrors_db_connection => true
+  end
+
+  module Classified
+    establish_connection :classified
+  end
+end
+
+class Paycheck
+  belongs_to :soldier
+end
+
+Military::Classified::Soldier.reflections[:assignments].klass # => Military::Classified::Assignment
+Military::Classified::Soldier.reflections[:assignments].klass.connection # => :classified
+Military::Classified::Soldier.reflections[:paycheck].klass # => Paycheck
+Military::Classified::Soldier.reflections[:paycheck].klass.connection # => :production
+</pre>
+
+Again this method will be deprecated in the 2.0 release so try and avoid using this.
+
+h3. HOW TO TURN OFF DEFAULT NAMESPACE REFLECTION MIRRORING
+
+h2. Issues
+
+Despite the 1.1.0 version of this gem there are still a number of issues with this gem:
+<ul>
+<li>Single Table Inheritance is not currently supported</li>
+<li>No connection pooling for alternate databases</li>
+</ul>
+
+Any help would be greatly appreciated
+
+h2. Installing
+
+<pre syntax="ruby">sudo gem install magic_multi_connections</pre>
+
+Rails: Add the following to the bottom of your <code>environment.rb</code> file
+
+<pre syntax="ruby">require 'magic_multi_connections'</pre>
+
+Ruby scripts: Add the following to the top of your script
+
+<pre syntax="ruby">require 'rubygems'
+require 'magic_multi_connections'</pre>
+
+
+h2. Demonstration with Rails
+
+A quick demonstration within Rails to provide a parallel "private" database for an application.
+
+h3. 1. Create rails app
+
+Using sqlite3 here, but use your preferred db:
+
+<pre>> rails privacy -d sqlite3
+> cd privacy
+> ruby script/generate model Person
+> cp config/environments/development.rb config/environments/private.rb
+</pre>
+
+The last line allows us to play with our *private* database within the console and rake tasks.
+
+h3. 2. Edit *config/database.yml* and add our private database:
+
+Add the following to the bottom of *config/database.yml*
+
+<pre syntax="yaml">
+private:
+  adapter: sqlite3
+  database: db/private.sqlite3
+</pre>
+
+h3. 3. Create a database schema
+
+Edit *db/migrate/001_create_people.rb*
+
+<pre syntax="ruby">class CreatePeople < ActiveRecord::Migration
+  def self.up
+    create_table :people do |t|
+      t.column :name, :string
+    end
+  end
+
+  def self.down
+    drop_table :people
+  end
+end
+</pre>
+
+From the command line, migrate this to our *development* and *private* databases:
+
+<pre>> rake db:migrate
+> rake db:migrate RAILS_ENV=private</pre>
+
+h3. 4. Add some data to databases
+
+<pre syntax="ruby">> ruby script/console development
+>> Person.create(:name => 'Nic')
+>> Person.create(:name => 'Banjo')
+>> exit
+> ruby script/console private
+>> Person.create(:name => 'Super Magical Nic')
+>> exit</pre>
+
+Now it should be obvious which database our app is accessing.
+
+h3. 5. Update environment.rb
+
+Edit *config/environment.rb* to include the library and create the *Private* module.
+
+Add the following to the end of the file.
+
+<pre syntax="ruby">
+require "magic_multi_connections"
+
+module Private
+  establish_connection :private
+end
+</pre>
+
+This tells the *Private* module that any model class that is requested will be assigned a connection to the *private* database, as defined in the *config/database.yml* specification.
+
+h3. 6. Setup a controller
+
+Create a *people* controller with a *index* action
+
+<pre>> ruby script/generate controller people index</pre>
+
+Edit your controller *app/controllers/people_controller.rb*
+
+<pre syntax="ruby">class PeopleController < ApplicationController
+
+  before_filter :check_private
+  
+  def index
+    @people = @mod::Person.find(:all)
+  end
+
+  private
+  def check_private
+    @mod = params[:private] ? Private : Object
+  end
+end
+</pre>
+
+The *check_private* action is a hack to demonstrate one method for selecting the database. In reality, a stupid one for hiding a "private" database, but you get the point.
+
+After *check_private* is called, *@mod* is either the *Object* (default) module or the *Private* module. The *Person* class is accessible through either of them.
+
+Yes, <code>@mod::Person</code> is uglier than just <code>Person</code>. Sorry.
+
+h3. 7. Setup the index.rhtml view
+
+Edit *app/views/people/index.rhtml*
+
+<pre syntax="html"><h1><%= @mod::Person %></h1>
+<h2><%= @mod::Person.active_connection_name %></h2>
+
+<ol>
+  <% @people.each do |person| -%>
+  <li><%= "#{person.name} - #{person.class}" %></li>
+  <% end -%>
+</ol>
+</pre>
+
+h3. 8. Test our multi-connection Rails app
+
+Launch the app
+
+<pre>> mongrel_rails start</pre>
+
+In your browser, go to "http://localhost:3000/people":http://localhost:3000/people and see the list of people: Nic and Banjo.
+
+Now, to see the private database, go to "http://localhost:3000/people?private=1":http://localhost:3000/people?private=1 and see the private list. Its so private, I won't show it here.
+
+Note: you may need to refresh the private url to see the results. Perhaps Rails is caching the SQL even though its a different connection to a different database. If you know what's happening here, please "email me":mailto:drnicwilliams@gmail.com?subject=MMC+caching+problem or the "forum":mailto:magicmodels@googlegroups.com?subject=MMC+caching+problem. Thanks.
+
+h3. 9. End
+
+There ends our example of a Rails application using one model class to access multiple databases cleanly.
+
+h2. Pre-existing modules
+
+In Rails, model files are placed in the *app/models* folder. If you place them in a subfolder, say  *app/models/admin*, then those model classes are access via module namespaces. 
+
+So,  *app/models/admin/page.rb* represents the <code>Admin::Page</code> class.
+
+Magic Multi-Connections works for these model classes as well.
+
+<pre syntax="ruby">Admin.establish_connection :admin_dev
+Admin::Page.active_connection_name # => "Admin::Page"
+</pre>
+
+h2. Related articles
+
+* Original blog article - "Magic Multi-Connections: A “facility in Rails to talk to more than one database at a time":http://drnicwilliams.com/2007/04/12/magic-multi-connections-a-facility-in-rails-to-talk-to-more-than-one-database-at-a-time/
+* "Discussed by DHH":http://www.loudthinking.com/arc/000610.html
+
+
+h2. Dr Nic's Blog
+
+"http://www.drnicwilliams.com":http://www.drnicwilliams.com - for future announcements and
+other stories and things.
+
+h2. Forum
+
+Discussion about the Magic Multi-Connections is on the Magic Models forum:
+
+"http://groups.google.com/group/magicmodels":http://groups.google.com/group/magicmodels
+
+h2. Licence
+
+This code is free to use under the terms of the MIT licence. 
+
+h2. Contact
+
+Comments are welcome. Send an email to "Dr Nic Williams":mailto:drnicwilliams@gmail.com.