add documentation for connecting to multiple databases.

2 files changed, 61 insertions, 12 deletions

diff --git a/README.md b/README.md
index 7db80e4..70d5e15 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,66 @@
 # README
 
-This README would normally document whatever steps are necessary to get the
-application up and running.
+This is an example rails application that connects to multiple
+databases.
 
-Things you may want to cover:
 
-* Ruby version
+The work on this repository is based on the following posts:
 
-* System dependencies
+* http://www.ostinelli.net/setting-multiple-databases-rails-definitive-guide/
+* https://technology.customink.com/blog/2015/06/22/rails-multi-database-best-practices-roundup/
 
-* Configuration
+I encourage readers to also view the keynote by Eileen Uchitelle to
+learn about exciting changes coming to [Rails 6](http://confreaks.tv/videos/railsconf2018-keynote-the-future-of-rails-6-scalable-by-default).
 
-* Database creation
+In this example we have two databases:
 
-* Database initialization
+* db/development.sqlite3
+* db_legacy/development.sqlite3
 
-* How to run the test suite
+The `db/development.sqlite3` represents a new database that this
+application is migrating to. `db_legacy/development.sqlite3` represents
+the legacy database that this application is migrating away from.
 
-* Services (job queues, cache servers, search engines, etc.)
+The legacy database has a single model named `Business` and the new
+database has a single model named `Organization`.
 
-* Deployment instructions
+To control two different connection pools we have two [Layer
+Supertypes](https://martinfowler.com/eaaCatalog/layerSupertype.html).
+One called `LegacyRecord` and the other is `ApplicationRecord`.
 
-* ...
+```ruby
+class LegacyRecord < ActiveRecord::Base
+  establish_connection Rails.configuration.x.legacy[Rails.env]
+  self.abstract_class = true
+end
+
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+end
+```
+
+Any classes that inherit from `LegacyRecord` join the legacy database
+connection pool. The `LegacyRecord` establishes a connection to the
+legacy database using the `Rails.configuration.x.legacy` configuration
+which is loaded in an initializer.
+
+
+```ruby
+Rails.configuration.x.legacy = YAML.load(ERB.new(IO.read(Rails.root.join("config","database_legacy.yml"))).result)
+```
+
+The initializer above loads the file `config/database_legacy.yml` which
+contains the connection information to connect to the legacy database.
+
+
+Migrations for the new database are put in the `db/migrate` folder just
+like any other rails application. Migrations that need to run against
+the legacy database are put in `db_legacy/migrate' and can be run using
+the rake tasks defined in `lib/tasks/legacy.rake`.
+
+By moving the legacy database related code to the `legacy.rake` file and
+the `db_legacy`, we make it easier to clean up when we finally decouple
+from the legacy database.
+
+The primary database connection information is still read from
+`config/database.yml`.
diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index 09705d1..4be24bd 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -1,2 +1,9 @@
 class ApplicationController < ActionController::Base
+  around_action :cache_legacy_connections
+
+  private
+
+  def cache_legacy_connections
+    LegacyRecord.connection.cache { yield }
+  end
 end