docs update

MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 [name of plugin creator]
+
+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.

README

@@ -1,4 +1,86 @@
 UseDb
+by David Stevenson
+ds@elctech.com
 =====
+USAGE
 
-Description goes here
+This plugin allows you to use multiple databases in your rails application.  
+You can switch the database for a model in the following manner:
+
+class MyModel < ActiveRecord::Base
+	use_db :prefix => "secdb_", :suffix => "_cool"
+end
+
+"use_db" takes a prefix and a suffix (only 1 of which is required) which are prepended and appended onto the current RAILS_ENV.  
+In the above example, I would have to make the following database entries to my database.yml:
+
+secdb_development_cool:
+  adapter: mysql
+  database: secdb_dev_db
+  ...
+
+secdb_test_cool:
+  adapater: mysql
+  database: secdb_test_db
+  ...
+
+It's often useful to create a single abstract model which all models using a different database extend from:
+
+class SecdbBase < ActiveRecord::Base
+	use_db :prefix => "secdb_"
+	self.abstract_class = true
+end
+
+class MyModel < SecdbBase
+  # this model will use a different database automatically now
+end
+
+==========
+MIGRATIONS
+
+To write a migration which executes on a different database, add the following method to your
+migration:
+
+class MyMigration < ActiveRecord::Migration
+  def self.database_model
+    return "SecdbBase"
+  end
+
+  def self.up
+    ...
+  end
+
+  ...
+end
+
+The "self.database_model" call must return a string which is the name of the model whose connection
+you want to borrow when performing the migration.  If this method is undefined, the default ActiveRecord::Base
+connection is used.
+
+=======
+TESTING
+
+In order to test multiple databases, you must invoke a task which clones the development database
+structure and copies it into the test database, clearing out the existing test data.  There is a single
+helper method which executes this task and you invoke it as follows:
+
+UseDbTest.prepare_test_db(:prefix => "secdb_")
+
+Even though it might not be the best place for it, I often place a call to this in my test helper.
+You don't want it to execute for every test, so put the following guards around it:
+
+unless defined?(CLONED_SEC_DB_FOR_TEST)
+  UseDbTest.prepare_test_db(:prefix => "secdb_")
+  CLONED_SEC_DB_FOR_TEST = true
+end
+
+========
+FIXTURES
+
+Fixtures will automatically be loaded into the correct database as long as the fixture name corresponds
+to the name of a model.  For example, if I have a model called SecdbUser who uses a different database and
+I create a fixture file called secdb_users.yml, the fixture loader will use whatever database connection
+belongs to hte SecdbUser model.
+
+There is currently no other way to force a fixture to use a specific database (sorry, no join tables yet),
+like there is for migrations.

lib/override_test_case.rb

@@ -25,7 +25,7 @@ def setup_with_fixtures
 
           for klass in UseDbPlugin.all_use_dbs
 
-            # puts "Establishing TRANSACTION for #{klass}..."
+            puts "Establishing TRANSACTION for #{klass}..." if UseDbPlugin.debug_print
 
             klass.send :increment_open_transactions
             klass.connection.begin_db_transaction
@@ -49,7 +49,7 @@ def teardown_with_fixtures
 
         for klass in UseDbPlugin.all_use_dbs
 
-          # puts "Finishing TRANSACTION for #{klass}..."
+          puts "Finishing TRANSACTION for #{klass}..." if UseDbPlugin.debug_print
 
           # Rollback changes if a transaction is active.
           if use_transactional_fixtures? && Thread.current['open_transactions'] != 0

lib/use_db.rb

@@ -10,13 +10,19 @@ module UseDbPlugin
   #   :username
   #   :password
   #     ... etc ... same as the options in establish_connection
+  #  
+  # Set the following to true in your test environment 
+  # to enable extended debugging printing during testing ...
+  # UseDbPlugin.debug_print = true   
+  #
 
   @@use_dbs = [ActiveRecord::Base]
+  @@debug_print = false
 
   def use_db(options)
     options_dup = options.dup
     conn_spec = get_use_db_conn_spec(options)
-    puts "Establishing connecting on behalf of #{self.to_s} to #{conn_spec.inspect}"
+    puts "Establishing connecting on behalf of #{self.to_s} to #{conn_spec.inspect}" if UseDbPlugin.debug_print
     establish_connection(conn_spec)
     extend ClassMixin
     @@use_dbs << self unless @@use_dbs.include?(self) || self.to_s.starts_with?("TestModel")
@@ -26,6 +32,14 @@ def self.all_use_dbs
     return @@use_dbs
   end
 
+  def self.debug_print
+    return @@debug_print
+  end
+
+  def self.debug_print=(newval)
+    @@debug_print = newval
+  end
+
   module ClassMixin
     def uses_db?
       true