innkeeper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 560d0c28790b3fe5ca5be5aaf652504314fc25c3678ceb57759ac443592b11de
+  data.tar.gz: 37cfd45f70289bbda7bfb73ee868d3b379eaf108ac51581f7a5e41e486bbccc0
+SHA512:
+  metadata.gz: 5bfd05b70e590c273e78249f6c74d859038d1711f4e551e775dc8cd5b176c6020596e0362f12708dd5216d61e630bb14df8e1fa2cd1a3719dbbd6797272eec78
+  data.tar.gz: 4256631c4d73af87b7f38f27493cb81ec4b2837faf8a47955067736bd4d97fe290eadcc08990304dc163da1809eef021e16f7aeb9b97b7f98ae3a62829fcaee8

data/.gitignore

@@ -0,0 +1,15 @@
+*.gem
+.bundle
+*.lock
+gemfiles/*.lock
+pkg/*
+*.log
+.idea
+*.sw[pno]
+test/databases.yml
+test/dummy/config/database.yml
+cookbooks
+tmp
+test/dummy/db/*.sqlite3
+.DS_Store
+test/debug.log

data/.pryrc

@@ -0,0 +1,3 @@
+if defined?(Rails) && Rails.env
+  extend Rails::ConsoleMethods
+end

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 2.2.4
+  - 2.3.1
+  - jruby-9.0.5.0
+gemfile:
+  - gemfiles/rails_5_1.gemfile
+bundler_args: --without local
+before_install:
+  - gem install bundler -v '> 1.5.0'
+env:
+  RUBY_GC_MALLOC_LIMIT: 90000000
+  RUBY_FREE_MIN: 200000
+matrix:
+  fast_finish: true

data/Appraisals

@@ -0,0 +1,20 @@
+appraise "rails-3-2" do
+  gem "rails", "~> 3.2"
+  gem "test-unit", "~> 3.0"
+end
+
+appraise "rails-4-0" do
+  gem "rails", "~> 4.0"
+end
+
+appraise "rails-4-1" do
+  gem "rails", "~> 4.1"
+end
+
+appraise "rails-4-2" do
+  gem "rails", "~> 4.2"
+end
+
+appraise "rails-5-0" do
+  gem "rails", "~> 5.0"
+end

data/Gemfile

@@ -0,0 +1,10 @@
+source 'http://rubygems.org'
+
+gemspec
+
+gem 'rails',        '>= 5.1.0'
+
+group :local do
+  gem 'pry'
+  gem 'guard-rspec', '~> 4.2'
+end

data/Guardfile

@@ -0,0 +1,24 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/innkeeper/(.+)\.rb$})     { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch(%r{^lib/innkeeper/(.+)\.rb$})     { |m| "spec/integration/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # # Rails example
+  # watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  # watch(%r{^app/(.*)(\.erb|\.haml|\.slim)$})          { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  # watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  # watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  # watch('config/routes.rb')                           { "spec/routing" }
+  # watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # # Capybara features specs
+  # watch(%r{^app/views/(.+)/.*\.(erb|haml|slim)$})     { |m| "spec/features/#{m[1]}_spec.rb" }
+
+  # # Turnip features and steps
+  # watch(%r{^spec/acceptance/(.+)\.feature$})
+  # watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end

data/HISTORY.md

@@ -0,0 +1,337 @@
+# 1.2.0
+  * July 28, 2016
+
+  - Official Rails 5 support
+
+# 1.1.0
+  * May 26, 2016
+
+  - Reset tenant after each request
+  - [Support callbacks](https://github.com/influitive/apartment/commit/ff9c9d092a781026502f5997c0bbedcb5748bc83) on switch [cbeer]
+  - Preliminary support for [separate database hosts](https://github.com/influitive/apartment/commit/abdffbf8cd9fba87243f16c86390da13e318ee1f) [apneadiving]
+
+# 1.0.2
+  * July 2, 2015
+
+  - Fix pg_dump env vars - pull/208 [MitinPavel]
+  - Allow custom seed data file - pull/234 [typeoneerror]
+
+# 1.0.1
+  * April 28, 2015
+
+  - Fix `Apartment::Deprecation` which was rescuing all exceptions
+
+# 1.0.0
+  * Feb 3, 2015
+
+  - [BREAKING CHANGE] `Apartment::Tenant.process` is deprecated in favour of `Apartment::Tenant.switch`
+  - [BREAKING CHANGE] `Apartment::Tenant.switch` without a block is deprecated in favour of `Apartment::Tenant.switch!`
+  - Raise proper `TenantNotFound`, `TenantExists` exceptions
+  - Deprecate old `SchemaNotFound`, `DatabaseNotFound` exceptions
+
+# 0.26.1
+  * Jan 13, 2015
+
+  - Fixed [schema quoting bug](https://github.com/influitive/apartment/issues/198#issuecomment-69782651) [jonsgreen]
+
+# 0.26.0
+  * Jan 5, 2015
+
+  - Rails 4.2 support
+
+# 0.25.2
+  * Sept 8, 2014
+
+  - Heroku fix on `assets:precompile` - pull/169 [rabbitt]
+
+# 0.25.1
+  * July 17, 2014
+
+  - Fixed a few vestiges of Apartment::Database
+
+# 0.25.0
+  * July 3, 2014
+
+  - [BREAKING CHANGE] - `Apartment::Database` is not deprecated in favour of
+    `Apartment::Tenant`
+  - ActiveRecord (and Rails) 4.1 now supported
+  - A new sql based adapter that dumps the schema using sql
+
+# 0.24.3
+  * March 5, 2014
+
+  - Rake enhancements weren't removed from the generator template
+
+# 0.24.2
+  * February 24, 2014
+
+  - Better warnings if `apartment:migrate` is run
+
+# 0.24.1
+  * February 21, 2014
+
+  - requiring `apartment/tasks/enhancements` in an initializer doesn't work
+  - One can disable tenant migrations using `Apartment.db_migrate_tenants = false` in the Rakefile
+
+# 0.24
+  * February 21, 2014 (In honour of the Women's Gold Medal in Hockey at Sochi)
+
+  - [BREAKING CHANGE] `apartment:migrate` task no longer depends on `db:migrate`
+    - Instead, you can `require 'apartment/tasks/enhancements'` in your Apartment initializer
+    - This will enhance `rake db:migrate` to also run `apartment:migrate`
+    - You can now forget about ever running `apartment:migrate` again
+  - Numerous deprecations for things referencing the word 'database'
+    - This is an ongoing effort to completely replace 'database' with 'tenant' as a better abstraction
+    - Note the obvious `Apartment::Database` still exists but will hopefully become `Apartment::Tenant` soon
+
+# 0.23.2
+  * January 9, 2014
+
+  - Increased visibility of #parse_database_name warning
+
+# 0.23.1
+  * January 8, 2014
+
+  - Schema adapters now initialize with default and persistent schemas
+  - Deprecated Apartment::Elevators#parse_database_name
+
+# 0.23.0
+  * August 21, 2013
+
+  - Subdomain Elevator now allows for exclusions
+  - Delayed::Job has been completely removed
+
+# 0.22.1
+  * August 21, 2013
+
+  - Fix bug where if your ruby process importing the database schema is run
+    from a directory other than the app root, Apartment wouldn't know what
+    schema_migrations to insert into the database (Rails only)
+
+# 0.22.0
+  * June 9, 2013
+
+  - Numerous bug fixes:
+    - Mysql reset could connect to wrong database [eric88]
+    - Postgresql schema names weren't quoted properly [gdott9]
+    - Fixed error message on SchemaNotFound in `process`
+  - HostHash elevator allows mapping host based on hash contents [gdott9]
+  - Official Sidekiq support with the [apartment-sidekiq gem](https://github.com/influitive/apartment-sidekiq)
+
+
+# 0.21.1
+  * May 31, 2013
+
+  - Clearing the AR::QueryCache after switching databases.
+    - Fixes issue with stale model being loaded for schema adapters
+
+# 0.21.0
+  * April 24, 2013
+
+  - JDBC support!! [PetrolMan]
+
+# 0.20.0
+  * Feb 6, 2013
+
+  - Mysql now has a 'schema like' option to perform like Postgresql (default)
+    - This should be significantly more performant than using connections
+  - Psych is now supported for Delayed::Job yaml parsing
+
+# 0.19.2
+  * Jan 30, 2013
+
+  - Database schema file can now be set manually or skipped altogether
+
+# 0.19.1
+  * Jan 30, 2013
+
+  - Allow schema.rb import file to be specified in config or skip schema.rb import altogether
+
+# 0.19.0
+  * Dec 29, 2012
+
+  - Apartment is now threadsafe
+  - New postgis adapter [zonpantli]
+  - Removed ActionDispatch dependency for use with Rack apps (regression)
+
+# 0.18.0
+  * Nov 27, 2012
+
+  - Added `append_environment` config option [virtualstaticvoid]
+  - Cleaned up the readme and generator documentation
+  - Added `connection_class` config option [smashtank]
+  - Fixed a [bug](https://github.com/influitive/apartment/issues/17#issuecomment-10758327) in pg adapter when missing schema
+
+# 0.17.1
+  * Oct 30, 2012
+
+  - Fixed a bug where switching to an unknown db in mysql2 would crash the app [Frodotus]
+
+# 0.17.0
+  * Sept 26, 2012
+
+  - Apartment has [a new home!](https://github.com/influitive/apartment)
+  - Support Sidekiq hooks to switch dbs [maedhr]
+  - Allow VERSION to be used on apartment:migrate [Bhavin Kamani]
+
+# 0.16.0
+  * June 1, 2012
+
+  - Apartment now supports a default_schema to be set, rather than relying on ActiveRecord's default schema_search_path
+  - Additional schemas can always be maintained in the schema_search_path by configuring persistent_schemas [ryanbrunner]
+    - This means Hstore is officially supported!!
+  - There is now a full domain based elevator to switch dbs based on the whole domain [lcowell]
+  - There is now a generic elevator that takes a Proc to switch dbs based on the return value of that proc.
+
+# 0.15.0
+  * March 18, 2012
+
+  - Remove Rails dependency, Apartment can now be used with any Rack based framework using ActiveRecord
+
+# 0.14.4
+  * March 8, 2012
+
+  - Delayed::Job Hooks now return to the previous database, rather than resetting
+
+# 0.14.3
+  * Feb 21, 2012
+
+  - Fix yaml serialization of non DJ models
+
+# 0.14.2
+  * Feb 21, 2012
+
+  - Fix Delayed::Job yaml encoding with Rails > 3.0.x
+
+# 0.14.1
+  * Dec 13, 2011
+
+  - Fix ActionDispatch::Callbacks deprecation warnings
+
+# 0.14.0
+  * Dec 13, 2011
+
+  - Rails 3.1 Support
+
+# 0.13.1
+  * Nov 8, 2011
+
+  - Reset prepared statement cache for rails 3.1.1 before switching dbs when using postgresql schemas
+    - Only necessary until the next release which will be more schema aware
+
+# 0.13.0
+  * Oct 25, 2011
+
+  - `process` will now rescue with reset if the previous schema/db is no longer available
+  - `create` now takes an optional block which allows you to process within the newly created db
+  - Fixed Rails version >= 3.0.10 and < 3.1 because there have been significant testing problems with 3.1, next version will hopefully fix this
+
+# 0.12.0
+  * Oct 4, 2011
+
+  - Added a `drop` method for removing databases/schemas
+  - Refactored abstract adapter to further remove duplication in concrete implementations
+  - Excluded models now take string references so they are properly reloaded in development
+  - Better silencing of `schema.rb` loading using `verbose` flag
+
+# 0.11.1
+  * Sep 22, 2011
+
+  - Better use of Railties for initializing apartment
+  - The following changes were necessary as I haven't figured out how to properly hook into Rails reloading
+    - Added reloader middleware in development to init Apartment on each request
+    - Override `reload!` in console to also init Apartment
+
+# 0.11.0
+  * Sep 20, 2011
+
+  - Excluded models no longer use a different connection when using postgresql schemas.  Instead their table_name is prefixed with `public.`
+
+# 0.10.3
+  * Sep 20, 2011
+
+  - Fix improper raising of exceptions on create and reset
+
+# 0.10.2
+  * Sep 15, 2011
+
+  - Remove all the annoying logging for loading db schema and seeding on create
+
+# 0.10.1
+  * Aug 11, 2011
+
+  - Fixed bug in DJ where new objects (that hadn't been pulled from the db) didn't have the proper database assigned
+
+# 0.10.0
+  * July 29, 2011
+
+  - Added better support for Delayed Job
+  - New config option that enables Delayed Job wrappers
+  - Note that DJ support uses a work-around in order to get queues stored in the public schema, not sure why it doesn't work out of the box, will look into it, until then, see documentation on queue'ng jobs
+
+# 0.9.2
+  * July 4, 2011
+
+  - Migrations now run associated rails migration fully, fixes schema.rb not being reloaded after migrations
+
+# 0.9.1
+  * June 24, 2011
+
+  - Hooks now take the payload object as an argument to fetch the proper db for DJ hooks
+
+# 0.9.0
+  * June 23, 2011
+
+  - Added module to provide delayed job hooks
+
+# 0.8.0
+  * June 23, 2011
+
+  - Added #current_database which will return the current database (or schema) name
+
+# 0.7.0
+  * June 22, 2011
+
+  - Added apartment:seed rake task for seeding all dbs
+
+# 0.6.0
+  * June 21, 2011
+
+  - Added #process to connect to new db, perform operations, then ensure a reset
+
+# 0.5.1
+  * June 21, 2011
+
+  - Fixed db migrate up/down/rollback
+  - added db:redo
+
+# 0.5.0
+  * June 20, 2011
+
+  - Added the concept of an "Elevator", a rack based strategy for db switching
+  - Added the Subdomain Elevator middleware to enabled db switching based on subdomain
+
+# 0.4.0
+  * June 14, 2011
+
+  - Added `configure` method on Apartment instead of using yml file, allows for dynamic setting of db names to migrate for rake task
+  - Added `seed_after_create` config option to import seed data to new db on create
+
+# 0.3.0
+  * June 10, 2011
+
+  - Added full support for database migration
+  - Added in method to establish new connection for excluded models on startup rather than on each switch
+
+# 0.2.0
+  * June 6, 2011 *
+
+  - Refactor to use more rails/active_support functionality
+  - Refactor config to lazily load apartment.yml if exists
+  - Remove OStruct and just use hashes for fetching methods
+  - Added schema load on create instead of migrating from scratch
+
+# 0.1.3
+  * March 30, 2011 *
+
+  - Original pass from Ryan

data/README.md

@@ -0,0 +1,485 @@
+# Innkeeper
+
+[![Code Climate](https://codeclimate.com/github/cpoms/innkeeper.png)](https://codeclimate.com/github/cpoms/innkeeper)
+[![Build Status](https://secure.travis-ci.org/cpoms/innkeeper.png?branch=development)](http://travis-ci.org/cpoms/innkeeper)
+
+*Multitenancy for Rails and ActiveRecord*
+
+Innkeeper provides tools to help you deal with multiple tenants in your Rails
+application. If you need to have certain data sequestered based on account or
+company, but still allow some data to exist in a common tenant, Innkeeper can
+help.
+
+## Installation
+
+### Rails
+
+Add the following to your Gemfile:
+
+```ruby
+gem 'innkeeper'
+```
+
+Then generate your `Innkeeper` config file using
+
+```ruby
+bundle exec rails generate innkeeper:install
+```
+
+This will create a `config/initializers/innkeeper.rb` initializer file.
+Configure as needed using the docs below.
+
+That's all you need to set up the Innkeeper libraries. If you want to switch
+tenants on a per-user basis, look under "Usage - Switching tenants per request",
+below.
+
+## Usage
+
+### Creating new Tenants
+
+Before you can switch to a new innkeeper tenant, you will need to create it.
+Whenever you need to create a new tenant, you can run the following command:
+
+```ruby
+Innkeeper::Tenant.create('tenant_name')
+```
+
+If you're using PostgreSQL, this will create the database and schema from the
+derived tenant configuration. For example, if you're using the Schema resolver,
+this will create a schema named 'tenant_name', assuming you're not using a
+decorator. If you're customising the tenant name with a decorator, it is the
+decorated name that will be used.
+
+When you create a new tenant, the schema is loaded on to that tenant, so it will
+be up to date when create returns.
+
+### Switching Tenants
+
+To switch tenants using Innkeeper, use the following command:
+
+```ruby
+Innkeeper::Tenant.switch!('tenant_name')
+```
+
+When switch is called, all requests coming to ActiveRecord will be routed to the
+tenant you specify (with the exception of excluded models, see below). To return
+to the 'root' tenant, call switch with no arguments.
+
+### Switching Tenants per request
+
+You can have Innkeeper route to the appropriate tenant by adding some Rack
+middleware. Innkeeper can support many different "Elevators" that can take care
+of this routing to your data.
+
+**NOTE: when switching tenants per-request, keep in mind that the order of your
+Rack middleware is important.** See the
+[Middleware Considerations](#middleware-considerations) section for more.
+
+The initializer above will generate the appropriate code for the Subdomain
+elevator by default. You can see this in `config/initializers/innkeeper.rb`
+after running that generator. If you're *not* using the generator, you can
+specify your elevator below. Note that in this case you will **need** to require
+the elevator manually in your `application.rb` like so:
+
+```ruby
+# config/application.rb
+require 'innkeeper/elevators/subdomain' # or 'domain' or 'generic'
+```
+
+#### Switch on subdomain
+
+In house, we use the subdomain elevator, which analyzes the subdomain of the
+request and switches to a tenant schema of the same name. It can be used like
+so:
+
+```ruby
+# application.rb
+module MyApplication
+  class Application < Rails::Application
+    config.middleware.use 'Innkeeper::Elevators::Subdomain'
+  end
+end
+```
+
+If you want to exclude a domain, for example if you don't want your application
+to treat www like a subdomain, in an initializer in your application, you can
+set the following:
+
+```ruby
+# config/initializers/innkeeper/subdomain_exclusions.rb
+Innkeeper::Elevators::Subdomain.excluded_subdomains = ['www']
+```
+
+This functions much in the same way as Innkeeper.excluded_models. This example
+will prevent switching your tenant when the subdomain is www. Handy for
+subdomains like: "public", "www", and "admin" :)
+
+#### Switch on domain
+
+To switch based on full domain (excluding subdomains *ie 'www'* and top level
+domains *ie '.com'* ) use the following:
+
+```ruby
+# application.rb
+module MyApplication
+  class Application < Rails::Application
+    config.middleware.use 'Innkeeper::Elevators::Domain'
+  end
+end
+```
+
+#### Switch on full host using a hash
+
+To switch based on full host with a hash to find corresponding tenant name use
+the following:
+
+```ruby
+# application.rb
+module MyApplication
+  class Application < Rails::Application
+    config.middleware.use 'Innkeeper::Elevators::HostHash', {'example.com' => 'example_tenant'}
+  end
+end
+```
+
+#### Custom Elevator
+
+A Generic Elevator exists that allows you to pass a `Proc` (or anything that
+responds to `call`) to the middleware. This Object will be passed in an
+`ActionDispatch::Request` object when called for you to do your magic. Innkeeper
+will use the return value of this proc to switch to the appropriate tenant. Use
+like so:
+
+```ruby
+# application.rb
+module MyApplication
+  class Application < Rails::Application
+    # Obviously not a contrived example
+    config.middleware.use 'Innkeeper::Elevators::Generic', Proc.new { |request| request.host.reverse }
+  end
+end
+```
+
+Your other option is to subclass the Generic elevator and implement your own
+switching mechanism. This is exactly how the other elevators work. Look at the
+`subdomain.rb` elevator to get an idea of how this should work. Basically all
+you need to do is subclass the generic elevator and implement your own
+`parse_tenant_name` method that will ultimately return the name of the tenant
+based on the request being made. It *could* look something like this:
+
+```ruby
+# app/middleware/my_custom_elevator.rb
+class MyCustomElevator < Innkeeper::Elevators::Generic
+
+  # @return {String} - The tenant to switch to
+  def parse_tenant_name(request)
+    # request is an instance of Rack::Request
+
+    # example: look up some tenant from the db based on this request
+    tenant_name = SomeModel.from_request(request)
+
+    return tenant_name
+  end
+end
+```
+
+#### Middleware Considerations
+
+In the examples above, we show the Innkeeper middleware being appended to the
+Rack stack with
+
+```ruby
+Rails.application.config.middleware.use 'Innkeeper::Elevators::Subdomain'
+```
+
+By default, the Subdomain middleware switches into a Tenant based on the
+subdomain at the beginning of the request, and when the request is finished, it
+switches back to the "public" Tenant. This happens in the
+[Generic](https://github.com/cpoms/innkeeper/blob/development/lib/innkeeper/elevators/generic.rb#L22)
+elevator, so all elevators that inherit from this elevator will operate as such.
+
+It's also good to note that Innkeeper switches back to the "public" tenant any
+time an error is raised in your application.
+
+This works okay for simple applications, but it's important to consider that you
+may want to maintain the "selected" tenant through different parts of the Rack
+application stack. For example, the
+[Devise](https://github.com/plataformatec/devise) gem adds the `Warden::Manager`
+middleware at the end of the stack in the examples above, our
+`Innkeeper::Elevators::Subdomain` middleware would come after it. Trouble is,
+Innkeeper resets the selected tenant after the request is finish, so some 
+edirects (e.g. authentication) in Devise will be run in the context of the
+"public" tenant. The same issue would also effect a gem such as the
+[better_errors](https://github.com/charliesome/better_errors) gem which inserts
+a middleware quite early in the Rails middleware stack.
+
+To resolve this issue, consider adding the Innkeeper middleware at a location
+in the Rack stack that makes sense for your needs, e.g.:
+
+```ruby
+Rails.application.config.middleware.insert_before 'Warden::Manager', 'Innkeeper::Elevators::Subdomain'
+```
+
+Now work done in the Warden middleware is wrapped in the
+`Innkeeper::Tenant.switch` context started in the Generic elevator.
+
+### Dropping Tenants
+
+To drop tenants using Innkeeper, use the following command:
+
+```ruby
+Innkeeper::Tenant.drop('tenant_name')
+```
+
+When method is called, the schema is dropped and all data from itself will be
+lost. Be careful with this method.
+
+## Config
+
+The following config options should be set up in a Rails initializer such as:
+
+    config/initializers/innkeeper.rb
+
+To set config options, add this to your initializer:
+
+```ruby
+Innkeeper.configure do |config|
+  # set your options (described below) here
+end
+```
+
+### Excluding models
+
+If you have some models that should always access the 'public' tenant, you can
+specify this by configuring Innkeeper using `Innkeeper.configure`. This will
+yield a config object for you. You can set excluded models like so:
+
+```ruby
+config.excluded_models = ["User", "Company"] # these models will not be multi-tenanted, but remain in the global (public) namespace
+```
+
+Note that a string representation of the model name is now the standard so that
+models are properly constantized when reloaded in development.
+
+Rails will always access the 'public' tenant when accessing these models, but
+note that tables will be created in all schemas. This may not be ideal, but its
+done this way because otherwise rails wouldn't be able to properly generate the
+schema.rb file.
+
+> **NOTE - Many-To-Many Excluded Models:**
+> Since model exclusions must come from referencing a real ActiveRecord model,
+`has_and_belongs_to_many` is NOT supported. In order to achieve a many-to-many
+relationship for excluded models, you MUST use `has_many :through`. This way you
+can reference the join model in the excluded models configuration.
+
+### Postgresql Schemas
+
+## Providing a Different default_schema
+
+By default, ActiveRecord will use `"$user", public` as the default
+`schema_search_path`. This can be modified if you wish to use a different
+default schema be setting:
+
+```ruby
+config.default_schema = "some_other_schema"
+```
+
+With that set, all excluded models will use this schema as the table name prefix
+instead of `public` and `reset` on `Innkeeper::Tenant` will return to this
+schema as well.
+
+## Persistent Schemas
+
+Innkeeper will normally just switch the `schema_search_path` whole hog to the
+one passed in. This can lead to problems if you want other schemas to always be
+searched as well. Enter `persistent_schemas`. You can configure a list of other
+schemas that will always remain in the search path, while the default gets
+swapped out:
+
+```ruby
+config.persistent_schemas = ['some', 'other', 'schemas']
+```
+
+### Installing Extensions into Persistent Schemas
+
+Persistent Schemas have numerous useful applications.
+[Hstore](http://www.postgresql.org/docs/9.1/static/hstore.html), for instance,
+is a popular storage engine for Postgresql. In order to use extensions such as
+Hstore, you have to install it to a specific schema and have that always in the
+`schema_search_path`.
+
+When using extensions, keep in mind:
+
+* Extensions can only be installed into one schema per database, so we will want
+  to install it into a schema that is always available in the
+  `schema_search_path`
+* The schema and extension need to be created in the database *before* they are
+  referenced in migrations, database.yml or innkeeper.
+* There does not seem to be a way to create the schema and extension using
+  standard rails migrations.
+* Rails db:test:prepare deletes and recreates the database, so it needs to be
+  easy for the extension schema to be recreated here.
+
+#### 1. Ensure the extensions schema is created when the database is created
+
+```ruby
+# lib/tasks/db_enhancements.rake
+
+####### Important information ####################
+# This file is used to setup a shared extensions #
+# within a dedicated schema. This gives us the   #
+# advantage of only needing to enable extensions #
+# in one place.                                  #
+#                                                #
+# This task should be run AFTER db:create but    #
+# BEFORE db:migrate.                             #
+##################################################
+
+namespace :db do
+  desc 'Also create shared_extensions Schema'
+  task :extensions => :environment  do
+    # Create Schema
+    ActiveRecord::Base.connection.execute 'CREATE SCHEMA IF NOT EXISTS shared_extensions;'
+    # Enable Hstore
+    ActiveRecord::Base.connection.execute 'CREATE EXTENSION IF NOT EXISTS HSTORE SCHEMA shared_extensions;'
+    # Enable UUID-OSSP
+    ActiveRecord::Base.connection.execute 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp" SCHEMA shared_extensions;'
+  end
+end
+
+Rake::Task["db:create"].enhance do
+  Rake::Task["db:extensions"].invoke
+end
+
+Rake::Task["db:test:purge"].enhance do
+  Rake::Task["db:extensions"].invoke
+end
+```
+
+#### 2. Ensure the schema is in Rails' default connection
+
+Next, your `database.yml` file must mimic what you've set for your default and
+persistent schemas in Innkeeper. When you run migrations with Rails, it won't
+know about the extensions schema because Innkeeper isn't injected into the
+default connection, it's done on a per-request basis, therefore Rails doesn't
+know about `hstore` or `uuid-ossp` during migrations.  To do so, add the
+following to your `database.yml` for all environments
+
+```yaml
+# database.yml
+...
+adapter: postgresql
+schema_search_path: "public,shared_extensions"
+...
+```
+
+This would be for a config with `default_schema` set to `public` and
+`persistent_schemas` set to `['shared_extensions']`.
+
+#### 3. Ensure the schema is in the innkeeper config
+
+```ruby
+# config/initializers/innkeeper.rb
+...
+config.persistent_schemas = ['shared_extensions']
+...
+```
+
+#### Alternative: Creating schema by default
+
+Another way that we've successfully configured hstore for our applications is to
+add it into the postgresql template1 database so that every tenant that gets
+created has it by default.
+
+One caveat with this approach is that it can interfere with other projects in
+development using the same extensions and template, but not using innkeeper with
+this approach.
+
+You can do so using a command like so:
+
+```bash
+psql -U postgres -d template1 -c "CREATE SCHEMA shared_extensions AUTHORIZATION some_username;"
+psql -U postgres -d template1 -c "CREATE EXTENSION IF NOT EXISTS hstore SCHEMA shared_extensions;"
+```
+
+The *ideal* setup would actually be to install `hstore` into the `public` schema
+and leave the public schema in the `search_path` at all times. We won't be able
+to do this though until public doesn't also contain the tenanted tables, which
+is an open issue with no real milestone to be completed. Happy to accept PR's on
+the matter.
+
+### Managing Migrations
+
+In order to migrate all of your tenants (or postgresql schemas) you need to
+provide a list of dbs to Innkeeper. You can make this dynamic by providing a
+Proc object to be called on migrations. This object should yield an array of
+string representing each tenant name. Example:
+
+```ruby
+# Dynamically get tenant names to migrate
+config.tenant_names = lambda{ Customer.pluck(:tenant_name) }
+
+# Use a static list of tenant names for migrate
+config.tenant_names = ['tenant1', 'tenant2']
+```
+
+You can then migrate your tenants using the normal rake task:
+
+```ruby
+rake db:migrate
+```
+
+This just invokes `Innkeeper::Tenant.migrate(#{tenant_name})` for each tenant
+name supplied from `Innkeeper.tenant_names`.
+
+#### Parallel Migrations
+
+Innkeeper supports parallelizing migrations into multiple threads when
+you have a large number of tenants. By default, parallel migrations is
+turned off. You can enable this by setting `parallel_migration_threads` to 
+the number of threads you want to use in your initializer.
+
+Keep in mind that because migrations are going to access the database,
+the number of threads indicated here should be less than the pool size
+that Rails will use to connect to your database.
+
+## Tenants on different servers
+
+Innkeeper supports tenant-based sharding at the application level. The `switch`,
+`create`, and `drop` methods all support full database configurations (as a
+hash) as well as tenant names. In fact, even when you pass a tenant name, it
+gets resolved to a full configuration using the configured `tenant_resolver`. If
+you wish to switch to a tenant on a different host, you can pass the full config
+with the host key.
+
+Innkeeper will compare the config to it's current one and work out whether it
+needs to switch host, database, schema, etc, and only do the minimal switch. For
+tenants (databases for mysql, schemas for pg) on the same host, the switch will
+be a lightweight 'local' switch, which is one that occurs as a SQL query only,
+rather than a re-establishment of the database connection.
+
+You could make use of a custom resolver to do multi-host tenant switching by
+name. You could map tenant names to a host (shard) IP via the hash of the host
+name, or something similar, and divide the hash space across available hosts.
+
+## Sidekiq
+
+See [innkeeper-sidekiq](https://github.com/cpoms/innkeeper-sidekiq)
+
+## Contributing
+
+* In `test/`, you will see `databases.yml.sample` files
+  * Copy them into the same directory but with the name `databases.yml`
+  * Edit them to fit your own settings
+* Rake tasks (see the Rakefile) will help you setup your dbs necessary to run
+  tests
+* Please issue pull requests to the `development` branch. All development
+  happens here, master is used for releases.
+* Ensure that your code is accompanied with tests. No code will be merged
+  without tests
+
+## License
+
+Innkeeper is released under the [MIT License](http://www.opensource.org/licenses/MIT).
+
+[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/cpoms/innkeeper/trend.png)](https://bitdeli.com/free "Bitdeli Badge")