apartment 0.15.0 → 0.16.0

data/.pryrc

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

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/HISTORY.md

@@ -1,3 +1,11 @@
+# 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
+  - 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
 

data/README.md

@@ -60,8 +60,9 @@ database, call switch with no arguments.
 
 You can have Apartment route to the appropriate database by adding some Rack middleware.
 Apartment can support many different "Elevators" that can take care of this routing to your data.
-In house, we use the subdomain elevator, which analyzes the subdomain of the request and switches
-to a database schema of the same name. It can be used like so:
+
+**Switch on subdomain**
+In house, we use the subdomain elevator, which analyzes the subdomain of the request and switches to a database schema of the same name. It can be used like so:
 
     # application.rb
     module My Application
@@ -71,6 +72,29 @@ to a database schema of the same name. It can be used like so:
       end
     end
 
+**Switch on domain**
+To switch based on full domain (excluding subdomains *ie 'www'* and top level domains *ie '.com'* ) use the following:
+
+    # application.rb
+    module My Application
+      class Application < Rails::Application
+
+        config.middleware.use 'Apartment::Elevators::Domain'
+      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. Apartment will use the return value of this proc to switch to the appropriate database.  Use like so:
+
+    # application.rb
+    module My Application
+      class Application < Rails::Application
+        # Obviously not a contrived example
+        config.middleware.use 'Apartment::Elevators::Generic', Proc.new { |request| request.host.reverse }
+      end
+    end
+
+
 ## Config
 
 The following config options should be set up in a Rails initializer such as:
@@ -85,20 +109,33 @@ To set config options, add this to your initializer:
 
 ### Excluding models
 
-If you have some models that should always access the 'root' database, you can specify this by configuring
-Apartment using `Apartment.configure`.  This will yield a config object for you.  You can set excluded models like so:
+If you have some models that should always access the 'root' database, you can specify this by configuring Apartment using `Apartment.configure`.  This will yield a config object for you.  You can set excluded models like so:
 
     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
 
-### Handling Environments
+### Postgresql Schemas
 
-By default, when not using postgresql schemas, Apartment will prepend the environment to the database name
-to ensure there is no conflict between your environments.  This is mainly for the benefit of your development
-and test environments.  If you wish to turn this option off in production, you could do something like:
+**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:
 
-    config.prepend_environment = !Rails.env.production?
+    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 `Apartment::Database` will return to this schema also
+
+**Persistent Schemas**
+Apartment 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:
+
+    config.persistent_schemas = ['some', 'other', 'schemas']
+
+This has 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 Hstore, you have to install to a specific schema and have that always in the `schema_search_path`.  This could be achieved like so:
+
+    # In a rake task, or on the console...
+    ActiveRecord::Base.connection.execute("CREATE SCHEMA hstore; CREATE EXTENSION HSTORE SCHEMA hstore")
+
+    # configure Apartment to maintain the `hstore` schema in the `schema_search_path`
+    config.persistent_schemas = ['hstore']
 
 ### Managing Migrations
 
@@ -119,7 +156,15 @@ You can then migration your databases using the rake task:
 This basically invokes `Apartment::Database.migrate(#{db_name})` for each database name supplied
 from `Apartment.database_names`
 
-### Delayed::Job
+### Handling Environments
+
+By default, when not using postgresql schemas, Apartment will prepend the environment to the database name
+to ensure there is no conflict between your environments.  This is mainly for the benefit of your development
+and test environments.  If you wish to turn this option off in production, you could do something like:
+
+    config.prepend_environment = !Rails.env.production?
+
+## Delayed::Job
 
 If using Rails ~> 3.2, you *must* use `delayed_job ~> 3.0`.  It has better Rails 3 support plus has some major changes that affect the serialization of models.
 I haven't been able to get `psych` working whatsoever as the YAML parser, so to get things to work properly, you must explicitly set the parser to `syck` *before* requiring `delayed_job`
@@ -139,18 +184,25 @@ In order to make ActiveRecord models play nice with DJ and Apartment, include `A
       include Apartment::Delayed::Requirements
     end
 
+Any classes that are being used as a Delayed::Job Job need to include the `Apartment::Delayed::Job::Hooks` module into the class.  This ensures that when a job runs, it switches to the appropriate tenant before performing its task.  It is also required (manually at the moment) that you set a `@database` attribute on your job so the hooks know what tennant to switch to
+
     class SomeDJ
 
-      def initialize(model)
-        @model = model
-        @model.database = Apartment::Database.current_database
+      include Apartment::Delayed::Job::Hooks
+
+      def initialize
+        @database = Apartment::Database.current_database
       end
 
       def perform
-        # do some stuff
+        # do some stuff (will automatically switch to @database before performing and switch back after)
       end
     end
 
+All jobs *must* stored in the global (public) namespace, so add it to the list of excluded models:
+
+    config.excluded_models = ["Delayed::Job"]
+
 ## Development
 
 * The Local setup for development assumes that a root user with no password exists for both mysql and postgresl

data/Rakefile

@@ -7,16 +7,17 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec => "db:test:prepare") do |spec|
   spec.pattern = "spec/**/*_spec.rb"
+  # spec.rspec_opts = '--order rand:16996'
 end
 
 namespace :spec do
-  
+
   [:tasks, :unit, :adapters, :integration].each do |type|
     RSpec::Core::RakeTask.new(type => :spec) do |spec|
       spec.pattern = "spec/#{type}/**/*_spec.rb"
     end
   end
-  
+
 end
 
 task :default => :spec
@@ -30,39 +31,39 @@ end
 namespace :postgres do
   require 'active_record'
   require "#{File.join(File.dirname(__FILE__), 'spec', 'support', 'config')}"
-  
+
   desc 'Build the PostgreSQL test databases'
   task :build_db do
-    %x{ createdb -E UTF8 #{pg_config['database']} } rescue "test db already exists"
+    %x{ createdb -E UTF8 #{pg_config['database']} -Upostgres } rescue "test db already exists"
     ActiveRecord::Base.establish_connection pg_config
     ActiveRecord::Migrator.migrate('spec/dummy/db/migrate')
   end
-  
+
   desc "drop the PostgreSQL test database"
   task :drop_db do
     puts "dropping database #{pg_config['database']}"
-    %x{ dropdb #{pg_config['database']} }
+    %x{ dropdb #{pg_config['database']} -Upostgres }
   end
-    
+
 end
 
 namespace :mysql do
   require 'active_record'
   require "#{File.join(File.dirname(__FILE__), 'spec', 'support', 'config')}"
-  
+
   desc 'Build the MySQL test databases'
   task :build_db do
     %x{ mysqladmin -u root create #{my_config['database']} } rescue "test db already exists"
     ActiveRecord::Base.establish_connection my_config
     ActiveRecord::Migrator.migrate('spec/dummy/db/migrate')
   end
-  
+
   desc "drop the MySQL test database"
   task :drop_db do
     puts "dropping database #{my_config['database']}"
     %x{ mysqladmin -u root drop #{my_config['database']} --force}
   end
-    
+
 end
 
 # TODO clean this up

data/apartment.gemspec

@@ -17,15 +17,16 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
-  
+
   s.add_dependency 'activerecord',    '>= 3.1.2'   # must be >= 3.1.2 due to bug in prepared_statements
-  s.add_dependency 'rack',            '~> 1.4.0'
-  
+  s.add_dependency 'rack',            '>= 1.3.6'
+
+  s.add_development_dependency 'pry', '~> 0.9.9'
   s.add_development_dependency 'rails', '>= 3.1.2'
   s.add_development_dependency 'rake', '~> 0.9.2'
   s.add_development_dependency 'sqlite3'
-  s.add_development_dependency 'rspec', '~> 2.8.0'
-  s.add_development_dependency 'rspec-rails', '~> 2.8.1'
+  s.add_development_dependency 'rspec', '~> 2.10.0'
+  s.add_development_dependency 'rspec-rails', '~> 2.10.0'
   s.add_development_dependency 'capybara', '~> 1.0.0'
   s.add_development_dependency 'pg', '>= 0.11.0'
   s.add_development_dependency 'mysql2', '~> 0.3.10'

data/lib/apartment.rb

@@ -3,8 +3,11 @@ require 'apartment/railtie' if defined?(Rails)
 module Apartment
 
   class << self
-    attr_accessor :use_postgres_schemas, :seed_after_create, :prepend_environment
-    attr_writer :database_names, :excluded_models
+    ACCESSOR_METHODS  = [:use_postgres_schemas, :seed_after_create, :prepend_environment]
+    WRITER_METHODS    = [:database_names, :excluded_models, :default_schema, :persistent_schemas]
+
+    attr_accessor(*ACCESSOR_METHODS)
+    attr_writer(*WRITER_METHODS)
 
     # configure apartment with available options
     def configure
@@ -21,6 +24,19 @@ module Apartment
       @excluded_models || []
     end
 
+    def default_schema
+      @default_schema || "public"
+    end
+
+    def persistent_schemas
+      @persistent_schemas || []
+    end
+
+    # Reset all the config for Apartment
+    def reset
+      (ACCESSOR_METHODS + WRITER_METHODS).each{|method| instance_variable_set(:"@#{method}", nil) }
+    end
+
   end
 
   autoload :Database, 'apartment/database'
@@ -33,7 +49,9 @@ module Apartment
   end
 
   module Elevators
-    autoload :Subdomain, 'apartment/elevators/subdomain'
+    autoload :Generic,    'apartment/elevators/generic'
+    autoload :Subdomain,  'apartment/elevators/subdomain'
+    autoload :Domain,     'apartment/elevators/domain'
   end
 
   module Delayed

data/lib/apartment/adapters/{mysql_adapter.rb → mysql2_adapter.rb}

@@ -1,16 +1,16 @@
 module Apartment
 
   module Database
-    
+
     def self.mysql2_adapter(config)
-      Adapters::MysqlAdapter.new config
+      Adapters::Mysql2Adapter.new config
     end
   end
-  
+
   module Adapters
-  
-    class MysqlAdapter < AbstractAdapter
-      
+
+    class Mysql2Adapter < AbstractAdapter
+
     protected
 
       #   Connect to new database
@@ -26,4 +26,4 @@ module Apartment
       end
     end
   end
-end
+end

data/lib/apartment/adapters/postgresql_adapter.rb

@@ -4,7 +4,7 @@ module Apartment
 
     def self.postgresql_adapter(config)
       Apartment.use_postgres_schemas ?
-        Adapters::PostgresqlSchemaAdapter.new(config, :schema_search_path => ActiveRecord::Base.connection.schema_search_path) :
+        Adapters::PostgresqlSchemaAdapter.new(config) :
         Adapters::PostgresqlAdapter.new(config)
     end
   end
@@ -33,27 +33,21 @@ module Apartment
     # Separate Adapter for Postgresql when using schemas
     class PostgresqlSchemaAdapter < AbstractAdapter
 
-      #   Get the current schema search path
-      #
-      #   @return {String} current schema search path
-      #
-      def current_database
-        ActiveRecord::Base.connection.schema_search_path
-      end
+      attr_reader :current_database
 
       #   Drop the database schema
       #
       #   @param {String} database Database (schema) to drop
       #
       def drop(database)
-        ActiveRecord::Base.connection.execute("DROP SCHEMA \"#{database}\" CASCADE")
+        ActiveRecord::Base.connection.execute(%{DROP SCHEMA "#{database}" CASCADE})
 
       rescue ActiveRecord::StatementInvalid
         raise SchemaNotFound, "The schema #{database.inspect} cannot be found."
       end
 
       #   Reset search path to default search_path
-      #   Set the table_name to always use the public namespace for excluded models
+      #   Set the table_name to always use the default namespace for excluded models
       #
       def process_excluded_models
         Apartment.excluded_models.each do |excluded_model|
@@ -66,14 +60,14 @@ module Apartment
 
           excluded_model.constantize.tap do |klass|
             # some models (such as delayed_job) seem to load and cache their column names before this,
-            # so would never get the public prefix, so reset first
+            # so would never get the default prefix, so reset first
             klass.reset_column_information
 
             # Ensure that if a schema *was* set, we override
             table_name = klass.table_name.split('.', 2).last
 
             # Not sure why, but Delayed::Job somehow ignores table_name_prefix...  so we'll just manually set table name instead
-            klass.table_name = "public.#{table_name}"
+            klass.table_name = "#{Apartment.default_schema}.#{table_name}"
           end
         end
       end
@@ -83,7 +77,8 @@ module Apartment
       #   @return {String} default schema search path
       #
       def reset
-        ActiveRecord::Base.connection.schema_search_path = @defaults[:schema_search_path]
+        @current_database = Apartment.default_schema
+        ActiveRecord::Base.connection.schema_search_path = full_search_path
       end
 
     protected
@@ -92,7 +87,9 @@ module Apartment
       #
       def connect_to_new(database = nil)
         return reset if database.nil?
-        ActiveRecord::Base.connection.schema_search_path = database
+
+        @current_database = database.to_s
+        ActiveRecord::Base.connection.schema_search_path = full_search_path
 
       rescue ActiveRecord::StatementInvalid
         raise SchemaNotFound, "The schema #{database.inspect} cannot be found."
@@ -101,12 +98,26 @@ module Apartment
       #   Create the new schema
       #
       def create_database(database)
-        ActiveRecord::Base.connection.execute("CREATE SCHEMA \"#{database}\"")
+        ActiveRecord::Base.connection.execute(%{CREATE SCHEMA "#{database}"})
 
       rescue ActiveRecord::StatementInvalid
         raise SchemaExists, "The schema #{database} already exists."
       end
 
+    private
+
+      #   Generate the final search path to set including persistent_schemas
+      #
+      def full_search_path
+        persistent_schemas = persistent_schema_string
+        @current_database.to_s + (persistent_schemas.empty? ? "" : ", #{persistent_schemas}")
+      end
+
+      #   Cached persistent schemas joined in a valid search path format (comma separated)
+      #
+      def persistent_schema_string
+        Apartment.persistent_schemas.join(', ')
+      end
     end
   end
 end

data/lib/apartment/database.rb

@@ -3,12 +3,15 @@ require 'active_support/core_ext/module/delegation'
 module Apartment
 
   #   The main entry point to Apartment functions
+  #
   module Database
 
     extend self
 
     delegate :create, :current_database, :drop, :process, :process_excluded_models, :reset, :seed, :switch, :to => :adapter
 
+    attr_writer :config
+
     #   Initialize Apartment config options such as excluded_models
     #
     def init

data/lib/apartment/elevators/domain.rb

@@ -0,0 +1,18 @@
+module Apartment
+  module Elevators
+    #   Provides a rack based db switching solution based on domain
+    #   Assumes that database name should match domain
+    #   Parses request host for second level domain
+    #   eg. example.com       => example
+    #       www.example.bc.ca => example
+    #
+    class Domain < Generic
+
+      def parse_database_name(request)
+        return nil if request.host.blank?
+
+        request.host.match(/(www.)?(?<sld>[^.]*)/)["sld"]
+      end
+    end
+  end
+end