innkeeper 0.1.0

data/Rakefile

@@ -0,0 +1,92 @@
+require 'bundler' rescue 'You must `gem install bundler` and `bundle install` to run rake tasks'
+Bundler.setup
+Bundler::GemHelper.install_tasks
+require "rake/testtask"
+require 'yaml'
+
+Rake::TestTask.new do |t|
+  t.libs = ["lib"]
+  t.warning = false
+  # t.verbose = true
+  t.test_files = FileList['test/*_test.rb']
+end
+
+require 'appraisal'
+# require "#{File.join(File.dirname(__FILE__), 'test', 'test_helper')}"
+
+task :console do
+  require 'pry'
+  require 'innkeeper'
+  ARGV.clear
+  Pry.start
+end
+
+task default: :test
+
+namespace :db do
+  namespace :test do
+    task prepare: %w{postgres:drop_db postgres:build_db mysql:drop_db mysql:build_db}
+  end
+
+  desc "copy sample database credential files over if real files don't exist"
+  task :copy_credentials do
+    require 'fileutils'
+    innkeeper_db_file = 'test/databases.yml'
+    rails_db_file = 'test/dummy/config/database.yml'
+
+    FileUtils.copy(innkeeper_db_file + '.sample', innkeeper_db_file, :verbose => true) unless File.exists?(innkeeper_db_file)
+    FileUtils.copy(rails_db_file + '.sample', rails_db_file, :verbose => true)         unless File.exists?(rails_db_file)
+  end
+end
+
+namespace :postgres do
+  require 'active_record'
+
+  desc 'Build the PostgreSQL test databases'
+  task :build_db do
+    %x{ createdb -E UTF8 #{pg_config['database']} -U#{pg_config['username']} } rescue "test db already exists"
+    ActiveRecord::Base.establish_connection pg_config
+    ActiveRecord::Migration.suppress_messages do
+      load(File.join(File.dirname(__FILE__), "test/dummy/db/schema.rb"))
+    end
+  end
+
+  desc "drop the PostgreSQL test database"
+  task :drop_db do
+    puts "dropping database #{pg_config['database']}"
+    %x{ dropdb #{pg_config['database']} -U#{pg_config['username']} }
+  end
+
+end
+
+namespace :mysql do
+  require 'active_record'
+
+  desc 'Build the MySQL test databases'
+  task :build_db do
+    %x{ /usr/local/mysql/bin/mysqladmin -u #{my_config['username']} --password=#{my_config['password']} create #{my_config['database']} } rescue "test db already exists"
+    ActiveRecord::Base.establish_connection my_config
+    ActiveRecord::Migration.suppress_messages do
+      load(File.join(File.dirname(__FILE__), "test/dummy/db/schema.rb"))
+    end
+  end
+
+  desc "drop the MySQL test database"
+  task :drop_db do
+    puts "dropping database #{my_config['database']}"
+    %x{ /usr/local/mysql/bin/mysqladmin -u #{my_config['username']} --password=#{my_config['password']} drop #{my_config['database']} --force}
+  end
+
+end
+
+def config
+  @config ||= YAML.load(ERB.new(IO.read('test/databases.yml')).result)['connections']
+end
+
+def pg_config
+  config['postgresql']
+end
+
+def my_config
+  config['mysql']
+end

data/TODO.md

@@ -0,0 +1,51 @@
+# Innkeeper TODOs
+
+### Below is a list of tasks in the approximate order to be completed of for Innkeeper
+### Any help along the way is greatly appreciated (on any items, not particularly in order)
+
+1.  Innkeeper was originally written (and TDD'd) with just Postgresql in mind. Different adapters were added at a later date.
+    As such, the test suite is a bit of a mess. There's no formal structure for fully integration testing all adapters to ensure
+    proper quality and prevent regressions.
+
+    There's also a test order dependency as some tests run assuming a db connection and if that test randomly ran before a previous
+    one that makes the connection, it would fail.
+
+    I'm proposing the first thing to be done is to write up a standard, high livel integration test case that can be applied to all adapters
+    and makes no assumptions about implementation. It should ensure that each adapter conforms to the Innkeeper Interface and CRUD's properly.
+    It would be nice if a user can 'register' an adapter such that it would automatically be tested (nice to have). Otherwise one could just use
+    a shared behaviour to run through all of this.
+
+    Then, I'd like to see all of the implementation specific tests just in their own test file for each adapter (ie the postgresql schema adapter checks a lot of things with `schema_search_path`)
+
+    This should ensure that going forward nothing breaks, and we should *ideally* be able to randomize the test order
+
+2.  <del>`Innkeeper::Database` is the wrong abstraction. When dealing with a multi-tenanted system, users shouldn't thing about 'Databases', they should
+    think about Tenants. I proprose that we deprecate the `Innkeeper::Database` constant in favour of `Innkeeper::Tenant` for a nicer abstraction. See
+    http://myronmars.to/n/dev-blog/2011/09/deprecating-constants-and-classes-in-ruby for ideas on how to achieve this.</del>
+
+4.  Innkeeper::Database.process should be deprecated in favour of just passing a block to `switch`
+5.  Innkeeper::Database.switch should be renamed to switch! to indicate that using it on its own has side effects
+
+6.  Migrations right now can be a bit of a pain. Innkeeper currently migrates a single tenant completely up to date, then goes onto the next. If one of these
+    migrations fails on a tenant, the previous one does NOT get reverted and leaves you in an awkward state. Ideally we'd want to wrap all of the migrations in
+    a transaction so if one fails, the whole thing reverts. Once we can ensure an all-or-nothing approach to migrations, we can optimize the migration strategy
+    to not even iterate over the tenants if there are no migrations to run on public.
+
+7.  Innkeeper has be come one of the most popular/robust Multi-tenant gems for Rails, but it still doesn't work for everyone's use case. It's fairly limited in implementation to either schema based (ie postgresql schemas) or connection based. I'd like to abstract out these implementation details such that one could write a pluggable strategy for Innkeeper and choose it based on a config selection (something like `config.strategy = :schema`). The next implementation I'd like to see is a scoped based approach that uses a `tenant_id` scoping on all records for multi-tenancy. This is probably the most popular multi-tenant approach and is db independent and really the simplest mechanism for a type of multi-tenancy.
+
+8.  Right now excluded tables still live in all tenanted environments. This is basically because it doesn't matter if they're there, we always query from the public.
+    It's a bit of an annoyance though and confuses lots of people. I'd love to see only tenanted tables in the tenants and only excluded tables in the public tenant.
+    This will be hard because Rails uses public to generate schema.rb. One idea is to have an `excluded` schema that holds all the excluded models and the public can
+    maintain everything.
+
+9.  This one is pretty lofty, but I'd also like to abstract out the fact that Innkeeper uses ActiveRecord. With the new DataMapper coming out soon and other popular
+    DBMS's (ie. mongo, couch etc...), it'd be nice if Innkeeper could be the de-facto interface for multi-tenancy on these systems.
+
+
+===================
+
+Quick TODOs
+
+1. `default_tenant` should be up to the adapter, not the Innkeeper class, deprecate `default_schema`
+2. deprecation.rb rescues everything, we have a hard dependency on ActiveSupport so this is unnecessary
+3.

data/gemfiles/rails_5_1.gemfile

@@ -0,0 +1,12 @@
+# This file was generated by Appraisal
+
+source "http://rubygems.org"
+
+gem "rails", "~> 5.1.0"
+
+group :local do
+  gem "pry"
+  gem "guard-rspec", "~> 4.2"
+end
+
+gemspec :path => "../"

data/innkeeper.gemspec

@@ -0,0 +1,42 @@
+# -*- encoding: utf-8 -*-
+$: << File.expand_path("../lib", __FILE__)
+require "innkeeper/version"
+
+Gem::Specification.new do |s|
+  s.name = %q{innkeeper}
+  s.version = Innkeeper::VERSION
+
+  s.authors       = ["Mike Campbell"]
+  s.summary       = %q{A Ruby gem for managing database multitenancy}
+  s.description   = %q{Innkeeper allows Rack applications to deal with database multitenancy through ActiveRecord}
+  s.email         = ["mike@ydd.io"]
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ["lib"]
+
+  s.homepage = %q{https://github.com/cpoms/innkeeper}
+  s.licenses = ["MIT"]
+
+  s.add_dependency 'activerecord',    '>= 5.1.0'
+  s.add_dependency 'rack',            '>= 1.3.6'
+  s.add_dependency 'public_suffix',   '~> 2.0.5'
+  s.add_dependency 'parallel',        '>= 0.7.1'
+
+  s.add_development_dependency 'appraisal'
+  s.add_development_dependency 'rake',         '~> 0.9'
+  s.add_development_dependency 'capybara',     '~> 2.0'
+
+  if defined?(JRUBY_VERSION)
+    s.add_development_dependency 'activerecord-jdbc-adapter'
+    s.add_development_dependency 'activerecord-jdbcpostgresql-adapter'
+    s.add_development_dependency 'activerecord-jdbcmysql-adapter'
+    s.add_development_dependency 'jdbc-postgres', '9.2.1002'
+    s.add_development_dependency 'jdbc-mysql'
+    s.add_development_dependency 'jruby-openssl'
+  else
+    s.add_development_dependency 'mysql2', '>= 0.3.10'
+    s.add_development_dependency 'pg',     '>= 0.11.0'
+    s.add_development_dependency 'sqlite3'
+  end
+end

data/lib/generators/innkeeper/install/USAGE

@@ -0,0 +1,5 @@
+Description:
+  Creates an initializer for innkeeper.
+
+Example:
+  `rails generate innkeeper:install`

data/lib/generators/innkeeper/install/install_generator.rb

@@ -0,0 +1,10 @@
+module Innkeeper
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
+
+    def copy_files
+      template "innkeeper.rb", File.join("config", "initializers", "innkeeper.rb")
+    end
+
+  end
+end

data/lib/generators/innkeeper/install/templates/innkeeper.rb

@@ -0,0 +1,76 @@
+# 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.
+# Require whichever Elevator you're using below or none if you have a custom one.
+#
+# require 'innkeeper/elevators/generic'
+# require 'innkeeper/elevators/domain'
+require 'innkeeper/elevators/subdomain'
+# require 'innkeeper/resolvers/schema'
+
+#
+# Innkeeper Configuration
+#
+Innkeeper.configure do |config|
+  # Add any models that you do not want to be multi-tenanted, but remain in the global (public) namespace.
+  # A typical example would be a Customer or Tenant model that stores each Tenant's information.
+  #
+  # config.excluded_models = %w{ Tenant }
+
+  # In order to migrate all of your Tenants you need to provide a list of Tenant names to Innkeeper.
+  # You can make this dynamic by providing a Proc object to be called on migrations.
+  # This object should yield either:
+  # - an array of strings representing each Tenant name.
+  # - a hash which keys are tenant names, and values custom db config (must contain all key/values required in database.yml)
+  #
+  # config.tenant_names = lambda{ Customer.pluck(:tenant_name) }
+  # config.tenant_names = ['tenant1', 'tenant2']
+  # config.tenant_names = [
+  #   {
+  #     adapter: 'postgresql',
+  #     host: 'some_server',
+  #     port: 5555,
+  #     database: 'postgres' # this is not the name of the tenant's db
+  #                          # but the name of the database to connect to before creating the tenant's db
+  #                          # mandatory in postgresql
+  #     schema_search_path: '"tenant1"'
+  #   },
+  #   'tenant2' => {
+  #     adapter:  'postgresql',
+  #     database: 'postgres' # this is not the name of the tenant's db
+  #                          # but the name of the database to connect to before creating the tenant's db
+  #                          # mandatory in postgresql
+  #     
+  #   }
+  # }
+  #
+  config.tenant_names = lambda { ToDo_Tenant_Or_User_Model.pluck :database }
+
+  # The tenant decorator setting should be a callable which receives the tenant
+  # as an argument, and returns the a modified version of the tenant name which
+  # you want to use in the resolver as a database or schema name, for example.
+  #
+  # A typical use-case might be prepending or appending the rails environment,
+  # as shown below.
+  #
+  # config.tenant_decorator = ->(tenant){ "#{Rails.env}_#{tenant}" }
+
+  # The resolver is used to convert a tenant name into a full spec. The two
+  # provided resolvers are Database and Schema. When you issue
+  # Innkeeper.switch("some_tenant"){ ... }, Innkeeper passes "some_tenant" to
+  # the selected resolver (after it's been decorated). The Database resolver
+  # takes the decorated tenant name, and inserts it into the :database key of a
+  # full connection specification (the full spec is whatever the database spec
+  # was at Innkeeper initialization. The schema resolver, does the same but
+  # for the :schema_search_path option in the configuration.
+  #
+  # config.tenant_resolver = Innkeeper::Resolvers::Schema
+end
+
+# Setup a custom Tenant switching middleware. The Proc should return the name of the Tenant that
+# you want to switch to.
+# Rails.application.config.middleware.use 'Innkeeper::Elevators::Generic', lambda { |request|
+#   request.host.split('.').first
+# }
+
+# Rails.application.config.middleware.use 'Innkeeper::Elevators::Domain'
+Rails.application.config.middleware.use 'Innkeeper::Elevators::Subdomain'

data/lib/innkeeper.rb

@@ -0,0 +1,110 @@
+require 'innkeeper/railtie' if defined?(Rails)
+require 'active_support/core_ext/object/blank'
+require 'forwardable'
+require 'active_record'
+require 'innkeeper/tenant'
+
+module Innkeeper
+  class << self
+    extend Forwardable
+
+    ACCESSOR_METHODS = [
+      :use_sql, :seed_after_create, :tenant_decorator,
+      :force_reconnect_on_switch, :pool_per_config
+    ]
+    WRITER_METHODS   = [
+      :tenant_names, :database_schema_file, :excluded_models,
+      :persistent_schemas, :connection_class, :tld_length, :db_migrate_tenants,
+      :seed_data_file, :default_tenant, :parallel_migration_threads
+    ]
+    OTHER_METHODS    = [:tenant_resolver, :resolver_class]
+
+    attr_accessor(*ACCESSOR_METHODS)
+    attr_writer(*WRITER_METHODS)
+
+    def_delegators :connection_class, :connection, :connection_config,
+      :establish_connection, :connection_handler
+
+    def configure
+      yield self if block_given?
+    end
+
+    def tenant_resolver
+      @tenant_resolver ||= @resolver_class.new(connection_config)
+    end
+
+    def tenant_resolver=(resolver_class)
+      remove_instance_variable(:@tenant_resolver) if instance_variable_defined?(:@tenant_resolver)
+      @resolver_class = resolver_class
+    end
+
+    def tenant_names
+      @tenant_names.respond_to?(:call) ? @tenant_names.call : (@tenant_names || [])
+    end
+
+    def tenants_with_config
+      extract_tenant_config
+    end
+
+    # Whether or not db:migrate should also migrate tenants
+    # defaults to true
+    def db_migrate_tenants
+      return @db_migrate_tenants if defined?(@db_migrate_tenants)
+
+      @db_migrate_tenants = true
+    end
+
+    # Default to empty array
+    def excluded_models
+      @excluded_models || []
+    end
+
+    def default_tenant
+      @default_tenant || tenant_resolver.init_config
+    end
+
+    def parallel_migration_threads
+      @parallel_migration_threads || 0
+    end
+
+    def persistent_schemas
+      @persistent_schemas || []
+    end
+
+    def connection_class
+      @connection_class || ActiveRecord::Base
+    end
+
+    def database_schema_file
+      return @database_schema_file if defined?(@database_schema_file)
+
+      @database_schema_file = Rails.root.join('db', 'schema.rb')
+    end
+
+    def seed_data_file
+      return @seed_data_file if defined?(@seed_data_file)
+
+      @seed_data_file = Rails.root.join('db', 'seeds.rb')
+    end
+
+    def reset
+      (ACCESSOR_METHODS + WRITER_METHODS + OTHER_METHODS).each do |method|
+        remove_instance_variable(:"@#{method}") if instance_variable_defined?(:"@#{method}")
+      end
+
+      Thread.current[:_innkeeper_connection_specification_name] = nil
+    end
+  end
+
+  # Exceptions
+  InnkeeperError = Class.new(StandardError)
+
+  # Raised when innkeeper cannot find the adapter specified in <tt>config/database.yml</tt>
+  AdapterNotFound = Class.new(InnkeeperError)
+
+  # Tenant specified is unknown
+  TenantNotFound = Class.new(InnkeeperError)
+
+  # The Tenant attempting to be created already exists
+  TenantExists = Class.new(InnkeeperError)
+end

data/lib/innkeeper/adapters/abstract_adapter.rb

@@ -0,0 +1,172 @@
+module Innkeeper
+  module Adapters
+    class AbstractAdapter
+      include ActiveSupport::Callbacks
+      define_callbacks :create, :switch
+
+      attr_reader :current
+
+      def initialize
+        reset
+      rescue Innkeeper::TenantNotFound
+        puts "WARN: Unable to connect to default tenant"
+      end
+
+      def reset
+        switch!(Innkeeper.default_tenant)
+      end
+
+      def switch(tenant = nil)
+        previous_tenant = @current
+        switch!(tenant)
+
+        yield
+      ensure
+        switch!(previous_tenant) rescue reset
+      end
+
+      def create(tenant)
+        run_callbacks :create do
+          begin
+            previous_tenant = @current
+            config = config_for(tenant)
+            difference = current_difference_from(config)
+
+            if difference[:host]
+              connection_switch!(config, without_keys: [:database, :schema_search_path])
+            end
+
+            create_tenant!(config)
+            simple_switch(config)
+            @current = tenant
+
+            import_database_schema
+            seed_data if Innkeeper.seed_after_create
+
+            yield if block_given?
+          ensure
+            switch!(previous_tenant) rescue reset
+          end
+        end
+      end
+
+      def drop(tenant)
+        previous_tenant = @current
+
+        config = config_for(tenant)
+        difference = current_difference_from(config)
+
+        if difference[:host]
+          connection_switch!(config, without_keys: [:database])
+        end
+
+        unless database_exists?(config[:database])
+          raise TenantNotFound, "Error while dropping database #{config[:database]} for tenant #{tenant}"
+        end
+
+        Innkeeper.connection.drop_database(config[:database])
+
+        @current = tenant
+      ensure
+        switch!(previous_tenant) rescue reset
+      end
+
+      def switch!(tenant)
+        run_callbacks :switch do
+          return reset if tenant.nil?
+
+          config = config_for(tenant)
+
+          if Innkeeper.force_reconnect_on_switch
+            connection_switch!(config)
+          else
+            switch_tenant(config)
+          end
+
+          @current = tenant
+
+          Innkeeper.connection.clear_query_cache
+
+          tenant
+        end
+      end
+
+      def config_for(tenant)
+        return tenant if tenant.is_a?(Hash)
+
+        decorated_tenant = decorate(tenant)
+        Innkeeper.tenant_resolver.resolve(decorated_tenant)
+      end
+
+      def decorate(tenant)
+        decorator = Innkeeper.tenant_decorator
+        decorator ? decorator.call(tenant) : tenant
+      end
+
+      def process_excluded_models
+        excluded_config = config_for(Innkeeper.default_tenant).merge(name: :_innkeeper_excluded)
+        Innkeeper.connection_handler.establish_connection(excluded_config)
+
+        Innkeeper.excluded_models.each do |excluded_model|
+          # user mustn't have overridden `connection_specification_name`
+          # cattr_accessor in model
+          excluded_model.constantize.connection_specification_name = :_innkeeper_excluded
+        end
+      end
+
+      def setup_connection_specification_name
+        Innkeeper.connection_class.connection_specification_name = nil
+        Innkeeper.connection_class.instance_eval do
+          def connection_specification_name
+            if !defined?(@connection_specification_name) || @connection_specification_name.nil?
+              innkeeper_spec_name = Thread.current[:_innkeeper_connection_specification_name]
+              return innkeeper_spec_name ||
+                (self == ActiveRecord::Base ? "primary" : superclass.connection_specification_name)
+            end
+            @connection_specification_name
+          end
+        end
+      end
+
+      def current_difference_from(config)
+        current_config = config_for(@current)
+        config.select{ |k, v| current_config[k] != v }
+      end
+
+      def connection_switch!(config, without_keys: [])
+        config = config.reject{ |k, _| without_keys.include?(k) }
+
+        config.merge!(name: connection_specification_name(config))
+
+        unless Innkeeper.connection_handler.retrieve_connection_pool(config[:name])
+          Innkeeper.connection_handler.establish_connection(config)
+        end
+
+        Thread.current[:_innkeeper_connection_specification_name] = config[:name]
+        simple_switch(config) if config[:database] || config[:schema_search_path]
+      end
+
+      def import_database_schema
+        ActiveRecord::Schema.verbose = false
+
+        load_or_abort(Innkeeper.database_schema_file) if Innkeeper.database_schema_file
+      end
+
+      def seed_data
+        silence_warnings{ load_or_abort(Innkeeper.seed_data_file) } if Innkeeper.seed_data_file
+      end
+
+      def load_or_abort(file)
+        if File.exist?(file)
+          load(file)
+        else
+          abort %{#{file} doesn't exist yet}
+        end
+      end
+
+      def raise_connect_error!(tenant, exception)
+        raise TenantNotFound, "Error while connecting to tenant #{tenant}: #{exception.message}"
+      end
+    end
+  end
+end