pg_multitenant_schemas 0.1.3

data/README.md

@@ -0,0 +1,149 @@
+# PgMultitenantSchemas
+
+[![Gem Version](https://badge.fury.io/rb/pg_multitenant_schemas.svg)](https://badge.fury.io/rb/pg_multitenant_schemas)
+[![Ruby](https://github.com/yourusername/pg_multitenant_schemas/actions/workflows/main.yml/badge.svg)](https://github.com/yourusername/pg_multitenant_schemas/actions/workflows/main.yml)
+
+A Ruby gem that provides PostgreSQL schema-based multitenancy with automatic tenant resolution, schema switching, and Rails integration. Perfect for SaaS applications that need secure tenant isolation.
+
+## Features
+
+- 🏢 **Schema-based multitenancy** - Complete tenant isolation using PostgreSQL schemas
+- 🔄 **Automatic schema switching** - Seamlessly switch between tenant schemas
+- 🌐 **Subdomain resolution** - Extract tenant from request subdomains
+- 🛡️ **Rails 8 compatible** - Works with Rails 7.x and 8.x
+- 🚀 **Dual API support** - Backward compatible API design
+- 🧵 **Thread-safe** - Safe for concurrent operations
+- 📝 **Comprehensive logging** - Track schema operations
+- ⚡ **High performance** - Minimal overhead
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pg_multitenant_schemas'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install pg_multitenant_schemas
+```
+
+## Configuration
+
+Configure the gem in your Rails initializer (`config/initializers/pg_multitenant_schemas.rb`):
+
+```ruby
+PgMultitenantSchemas.configure do |config|
+  config.connection_class = 'ApplicationRecord'  # or 'ActiveRecord::Base'
+  config.tenant_model_class = 'Tenant'           # your tenant model
+  config.default_schema = 'public'
+  config.excluded_subdomains = ['www', 'api', 'admin']
+  config.development_fallback = true            # for development
+  config.auto_create_schemas = true             # automatically create missing schemas
+end
+```
+
+## Usage
+
+### Basic Schema Operations
+
+```ruby
+# Switch to a tenant schema
+PgMultitenantSchemas::SchemaSwitcher.switch_schema('tenant_123')
+
+# Create a new schema
+PgMultitenantSchemas::SchemaSwitcher.create_schema('tenant_456')
+
+# Check if schema exists
+PgMultitenantSchemas::SchemaSwitcher.schema_exists?('tenant_123')
+
+# Drop a schema
+PgMultitenantSchemas::SchemaSwitcher.drop_schema('tenant_456')
+```
+
+### Tenant Resolution
+
+```ruby
+# Extract tenant from subdomain
+subdomain = PgMultitenantSchemas.extract_subdomain('acme.myapp.com')
+# => 'acme'
+
+# Find tenant by subdomain
+tenant = PgMultitenantSchemas.find_tenant_by_subdomain('acme')
+
+# Resolve tenant from Rails request
+tenant = PgMultitenantSchemas.resolve_tenant_from_request(request)
+```
+
+### Context Management
+
+```ruby
+# Switch to tenant context
+PgMultitenantSchemas.switch_to_tenant(tenant)
+
+# Use block-based context switching
+PgMultitenantSchemas.with_tenant(tenant) do
+  # All queries here use tenant's schema
+  User.all  # Queries tenant_123.users
+end
+
+# Check current context
+PgMultitenantSchemas.current_tenant
+PgMultitenantSchemas.current_schema
+```
+
+### Rails Integration
+
+In your ApplicationController:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include PgMultitenantSchemas::Rails::ControllerConcern
+  
+  before_action :resolve_tenant
+  
+  private
+  
+  def resolve_tenant
+    tenant = resolve_tenant_from_subdomain
+    switch_to_tenant(tenant) if tenant
+  end
+end
+```
+
+In your models:
+
+```ruby
+class Tenant < ApplicationRecord
+  include PgMultitenantSchemas::Rails::ModelConcern
+  
+  after_create :create_tenant_schema
+  after_destroy :drop_tenant_schema
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/pg_multitenant_schemas. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/pg_multitenant_schemas/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PgMultitenantSchemas project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/pg_multitenant_schemas/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/pg_multitenant_schemas/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# PgMultitenantSchemas provides PostgreSQL schema-based multitenancy functionality.
+module PgMultitenantSchemas
+  # Configuration class for PgMultitenantSchemas gem settings.
+  # Manages tenant resolution, schema switching behavior, and Rails integration options.
+  class Configuration
+    attr_accessor :tenant_model_class, :default_schema, :development_fallback,
+                  :excluded_subdomains, :common_tlds, :auto_create_schemas,
+                  :connection_class, :logger
+
+    def initialize
+      @tenant_model_class = "Tenant"
+      @default_schema = "public"
+      @development_fallback = false
+      @excluded_subdomains = %w[www api admin mail ftp blog support help docs]
+      @common_tlds = %w[com org net edu gov mil int co uk ca au de fr jp cn]
+      @auto_create_schemas = true
+      @connection_class = "ActiveRecord::Base"
+      @logger = nil
+    end
+
+    def tenant_model
+      @tenant_model ||= tenant_model_class.constantize
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+    end
+  end
+end

data/lib/pg_multitenant_schemas/context.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  # Thread-safe tenant context management
+  class Context
+    class << self
+      def current_tenant
+        Thread.current[:pg_multitenant_current_tenant]
+      end
+
+      def current_tenant=(tenant)
+        Thread.current[:pg_multitenant_current_tenant] = tenant
+      end
+
+      def current_schema
+        Thread.current[:pg_multitenant_current_schema] || PgMultitenantSchemas.configuration.default_schema
+      end
+
+      def current_schema=(schema_name)
+        Thread.current[:pg_multitenant_current_schema] = schema_name
+      end
+
+      def reset!
+        Thread.current[:pg_multitenant_current_tenant] = nil
+        Thread.current[:pg_multitenant_current_schema] = nil
+        switch_to_schema(PgMultitenantSchemas.configuration.default_schema)
+      end
+
+      def switch_to_schema(schema_name)
+        schema_name = PgMultitenantSchemas.configuration.default_schema if schema_name.blank?
+        SchemaSwitcher.switch_schema(schema_name)
+        self.current_schema = schema_name
+      end
+
+      def switch_to_tenant(tenant)
+        if tenant
+          schema_name = tenant.respond_to?(:subdomain) ? tenant.subdomain : tenant.to_s
+          switch_to_schema(schema_name)
+          self.current_tenant = tenant
+        else
+          switch_to_schema(PgMultitenantSchemas.configuration.default_schema)
+          self.current_tenant = nil
+        end
+      end
+
+      # Execute block within tenant context
+      def with_tenant(tenant_or_schema)
+        schema_name, tenant = extract_schema_and_tenant(tenant_or_schema)
+        previous_tenant = current_tenant
+        previous_schema = current_schema
+
+        begin
+          switch_to_schema(schema_name)
+          self.current_tenant = tenant
+          yield if block_given?
+        ensure
+          restore_previous_context(previous_tenant, previous_schema)
+        end
+      end
+
+      private
+
+      # Extract schema name and tenant object from input
+      def extract_schema_and_tenant(tenant_or_schema)
+        if tenant_or_schema.respond_to?(:subdomain)
+          [tenant_or_schema.subdomain, tenant_or_schema]
+        else
+          [tenant_or_schema.to_s, nil]
+        end
+      end
+
+      # Restore the previous tenant context
+      def restore_previous_context(previous_tenant, previous_schema)
+        restore_schema = if previous_tenant.respond_to?(:subdomain)
+                           previous_tenant.subdomain
+                         else
+                           previous_schema
+                         end
+        switch_to_schema(restore_schema)
+        self.current_tenant = previous_tenant
+      end
+
+      public
+
+      # Create new tenant schema
+      def create_tenant_schema(tenant_or_schema)
+        schema_name = if tenant_or_schema.respond_to?(:subdomain)
+                        tenant_or_schema.subdomain
+                      else
+                        tenant_or_schema.to_s
+                      end
+        SchemaSwitcher.create_schema(schema_name)
+      end
+
+      # Drop tenant schema
+      def drop_tenant_schema(tenant_or_schema, cascade: true)
+        schema_name = if tenant_or_schema.respond_to?(:subdomain)
+                        tenant_or_schema.subdomain
+                      else
+                        tenant_or_schema.to_s
+                      end
+        SchemaSwitcher.drop_schema(schema_name, cascade: cascade)
+      end
+    end
+  end
+end

data/lib/pg_multitenant_schemas/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  # Exception classes
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class SchemaExists < Error; end
+  class SchemaNotFound < Error; end
+  class ConfigurationError < Error; end
+  class TenantNotFound < Error; end
+end

data/lib/pg_multitenant_schemas/rails/controller_concern.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  module Rails
+    # Controller concern for Rails integration
+    module ControllerConcern
+      extend ActiveSupport::Concern
+
+      included do
+        # Add callback hooks that can be overridden
+        before_action :resolve_tenant_context, unless: :skip_tenant_resolution?
+        after_action :reset_tenant_context, unless: :skip_tenant_resolution?
+
+        # Make current tenant available to views
+        helper_method :current_tenant, :current_schema if respond_to?(:helper_method)
+      end
+
+      # Instance methods
+      def current_tenant
+        @current_tenant || PgMultitenantSchemas::Context.current_tenant
+      end
+
+      def current_schema
+        PgMultitenantSchemas::Context.current_schema
+      end
+
+      def switch_to_tenant(tenant)
+        @current_tenant = tenant
+        PgMultitenantSchemas::Context.switch_to_tenant(tenant)
+      end
+
+      def resolve_tenant_context
+        tenant = PgMultitenantSchemas::TenantResolver.resolve_tenant_with_fallback(request)
+        switch_to_tenant(tenant)
+      rescue StandardError => e
+        handle_tenant_resolution_error(e)
+      end
+
+      def reset_tenant_context
+        @current_tenant = nil
+        PgMultitenantSchemas::Context.reset!
+      rescue StandardError => e
+        Rails.logger.error "PgMultitenantSchemas: Failed to reset tenant context: #{e.message}"
+        # Don't raise - this is cleanup code
+      end
+
+      protected
+
+      # Override this method in controllers that shouldn't use tenant resolution
+      def skip_tenant_resolution?
+        false
+      end
+
+      # Override this method to customize error handling
+      def handle_tenant_resolution_error(error)
+        Rails.logger.error "PgMultitenantSchemas: Tenant resolution failed: #{error.message}"
+
+        raise error unless PgMultitenantSchemas.configuration.development_fallback && Rails.env.development?
+
+        switch_to_tenant(nil) # Fall back to default schema in development
+      end
+
+      # Class methods
+      class_methods do
+        # DSL to skip tenant resolution for specific actions
+        def skip_tenant_resolution(options = {})
+          skip_before_action :resolve_tenant_context, options
+          skip_after_action :reset_tenant_context, options
+        end
+      end
+    end
+  end
+end

data/lib/pg_multitenant_schemas/rails/model_concern.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  module Rails
+    # Model concern for tenant callbacks
+    module ModelConcern
+      extend ActiveSupport::Concern
+
+      included do
+        # Add callbacks for schema management
+        after_create :create_tenant_schema_callback, if: :should_manage_schema?
+        before_destroy :drop_tenant_schema_callback, if: :should_manage_schema?
+      end
+
+      def create_tenant_schema_callback
+        return unless valid_tenant_for_schema?
+
+        handle_schema_creation
+      end
+
+      def drop_tenant_schema_callback
+        return unless valid_tenant_for_schema?
+
+        handle_schema_deletion
+      end
+
+      protected
+
+      # Override this method to control when schema management should happen
+      def should_manage_schema?
+        PgMultitenantSchemas.configuration.auto_create_schemas &&
+          respond_to?(:subdomain) &&
+          subdomain.present?
+      end
+
+      private
+
+      # Check if tenant is valid for schema operations
+      def valid_tenant_for_schema?
+        respond_to?(:subdomain) && subdomain.present?
+      end
+
+      # Handle schema creation with error handling
+      def handle_schema_creation
+        PgMultitenantSchemas::Context.create_tenant_schema(self)
+        log_schema_operation("Created schema for tenant '#{subdomain}'")
+      rescue PgMultitenantSchemas::SchemaExists
+        log_schema_operation("Schema '#{subdomain}' already exists")
+      rescue StandardError => e
+        handle_schema_error(e, "create")
+      end
+
+      # Handle schema deletion with error handling
+      def handle_schema_deletion
+        PgMultitenantSchemas::Context.drop_tenant_schema(self)
+        log_schema_operation("Dropped schema for tenant '#{subdomain}'")
+      rescue PgMultitenantSchemas::SchemaNotFound
+        log_schema_operation("Schema '#{subdomain}' not found for deletion")
+      rescue StandardError => e
+        handle_schema_error(e, "drop")
+      end
+
+      # Log schema operations
+      def log_schema_operation(message)
+        Rails.logger.info "PgMultitenantSchemas: #{message}"
+      end
+
+      # Handle schema operation errors
+      def handle_schema_error(error, operation)
+        Rails.logger.error "PgMultitenantSchemas: Failed to #{operation} schema '#{subdomain}': #{error.message}"
+        raise error unless development_fallback_enabled?
+      end
+
+      # Check if development fallback is enabled
+      def development_fallback_enabled?
+        PgMultitenantSchemas.configuration.development_fallback && Rails.env.development?
+      end
+
+      class_methods do
+        # DSL to disable automatic schema management
+        def skip_schema_management
+          skip_callback :after_create, :create_tenant_schema_callback
+          skip_callback :before_destroy, :drop_tenant_schema_callback
+        end
+      end
+    end
+  end
+end

data/lib/pg_multitenant_schemas/rails/railtie.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  module Rails
+    # Railtie for automatic initialization and integration with Rails applications.
+    # Handles schema switcher initialization when ActiveRecord loads.
+    class Railtie < ::Rails::Railtie
+      initializer "pg_multitenant_schemas.initialize" do |_app|
+        # Initialize connection when Rails starts
+        ActiveSupport.on_load(:active_record) do
+          PgMultitenantSchemas::SchemaSwitcher.initialize_connection
+        end
+      end
+
+      # Add rake tasks
+      rake_tasks do
+        load File.expand_path("../tasks/pg_multitenant_schemas.rake", __dir__)
+      end
+
+      # Add generators
+      generators do
+        require_relative "generators/install_generator"
+        require_relative "generators/tenant_migration_generator"
+      end
+    end
+  end
+end

data/lib/pg_multitenant_schemas/schema_switcher.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  # Core schema switching functionality
+  class SchemaSwitcher
+    class << self
+      # Initialize connection management
+      def initialize_connection
+        # This is called by the Railtie when Rails starts
+        # No special initialization needed as we use the configured connection class
+      end
+
+      # Get the database connection from the configured connection class
+      def connection
+        connection_class = PgMultitenantSchemas.configuration.connection_class
+        if connection_class.is_a?(String)
+          Object.const_get(connection_class).connection
+        else
+          connection_class.connection
+        end
+      rescue StandardError => e
+        raise ConnectionError, "Failed to get database connection: #{e.message}"
+      end
+
+      # Switches the search_path - supports both APIs for backward compatibility
+      def switch_schema(conn_or_schema, schema = nil)
+        if conn_or_schema.is_a?(String)
+          # New API: switch_schema('schema_name')
+          schema = conn_or_schema
+          conn = connection
+        else
+          # Old API: switch_schema(conn, 'schema_name')
+          conn = conn_or_schema
+        end
+
+        raise ArgumentError, "Schema name cannot be empty" if schema.nil? || schema.strip.empty?
+
+        # Use simple quoting for PostgreSQL identifiers
+        quoted_schema = "\"#{schema.gsub('"', '""')}\""
+        execute_sql(conn, "SET search_path TO #{quoted_schema};")
+      end
+
+      # Reset to default schema - supports both APIs
+      def reset_schema(conn = nil)
+        conn ||= connection
+        execute_sql(conn, "SET search_path TO public;")
+      end
+
+      # Create a new schema - supports both APIs
+      def create_schema(conn_or_schema, schema_name = nil)
+        if conn_or_schema.is_a?(String)
+          # New API: create_schema('schema_name')
+          schema_name = conn_or_schema
+          conn = connection
+        else
+          # Old API: create_schema(conn, 'schema_name')
+          conn = conn_or_schema
+        end
+
+        raise ArgumentError, "Schema name cannot be empty" if schema_name.nil? || schema_name.strip.empty?
+
+        quoted_schema = "\"#{schema_name.gsub('"', '""')}\""
+        execute_sql(conn, "CREATE SCHEMA IF NOT EXISTS #{quoted_schema};")
+      end
+
+      # Drop a schema - supports both APIs
+      def drop_schema(conn_or_schema, schema_name_or_options = nil, cascade: true)
+        if conn_or_schema.is_a?(String)
+          # New API: drop_schema('schema_name', cascade: true)
+          schema_name = conn_or_schema
+          options = schema_name_or_options || {}
+          cascade = options.fetch(:cascade, cascade)
+          conn = connection
+        else
+          # Old API: drop_schema(conn, 'schema_name', cascade: true)
+          conn = conn_or_schema
+          schema_name = schema_name_or_options
+        end
+
+        raise ArgumentError, "Schema name cannot be empty" if schema_name.nil? || schema_name.strip.empty?
+
+        cascade_option = cascade ? "CASCADE" : "RESTRICT"
+        quoted_schema = "\"#{schema_name.gsub('"', '""')}\""
+        execute_sql(conn, "DROP SCHEMA IF EXISTS #{quoted_schema} #{cascade_option};")
+      end
+
+      # Check if schema exists - supports both APIs
+      def schema_exists?(conn_or_schema, schema_name = nil)
+        if conn_or_schema.is_a?(String)
+          # New API: schema_exists?('schema_name')
+          schema_name = conn_or_schema
+          conn = connection
+        else
+          # Old API: schema_exists?(conn, 'schema_name')
+          conn = conn_or_schema
+        end
+
+        return false if schema_name.nil? || schema_name.strip.empty?
+
+        result = execute_sql(conn, <<~SQL)
+          SELECT EXISTS(
+            SELECT 1 FROM information_schema.schemata#{" "}
+            WHERE schema_name = '#{schema_name}'
+          ) AS schema_exists
+        SQL
+        get_result_value(result, 0, 0) == "t"
+      end
+
+      # Get current schema - supports both APIs
+      def current_schema(conn = nil)
+        conn ||= connection
+        result = execute_sql(conn, "SELECT current_schema()")
+        get_result_value(result, 0, 0)
+      end
+
+      private
+
+      # Execute SQL with Rails 8 compatibility
+      def execute_sql(conn, sql)
+        if conn.respond_to?(:execute)
+          # Rails connection - use execute
+          conn.execute(sql)
+        else
+          # Raw PG connection - use exec
+          conn.exec(sql)
+        end
+      end
+
+      # Get value from result with compatibility for different result types
+      def get_result_value(result, row, col)
+        if result.respond_to?(:getvalue)
+          # PG::Result
+          result.getvalue(row, col)
+        else
+          # ActiveRecord::Result
+          result.rows[row][col]
+        end
+      end
+    end
+  end
+end