pg_multitenant_schemas 0.1.3 → 0.2.0

data/examples/rails_integration/controller_examples.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+# Rails Controller Integration Examples
+# Demonstrates various controller patterns for multi-tenant applications
+
+# Example 1: Basic Application Controller Setup
+# Provides tenant resolution and access control for Rails applications
+class ApplicationController < ActionController::Base
+  include PgMultitenantSchemas::ControllerConcern
+
+  protect_from_forgery with: :exception
+  before_action :authenticate_user!
+  before_action :ensure_tenant_access
+
+  protected
+
+  # Custom tenant resolution from request
+  def resolve_tenant_from_request
+    resolve_by_subdomain || resolve_by_domain || resolve_by_user_preference
+  end
+
+  private
+
+  def resolve_by_subdomain
+    return nil unless request.subdomain.present?
+
+    Tenant.active.find_by(subdomain: request.subdomain)
+  end
+
+  def resolve_by_domain
+    return nil unless request.domain.present?
+
+    Tenant.active.find_by(domain: request.host)
+  end
+
+  def resolve_by_user_preference
+    return nil unless user_signed_in? && current_user.current_tenant_id.present?
+
+    current_user.tenants.find_by(id: current_user.current_tenant_id)
+  end
+
+  def tenant_access_valid?
+    @current_tenant && current_user&.has_access_to?(@current_tenant)
+  end
+
+  def ensure_tenant_access
+    return handle_missing_tenant unless @current_tenant
+    return handle_access_denied unless tenant_access_valid?
+
+    true
+  end
+
+  def handle_missing_tenant
+    respond_to do |format|
+      format.html { redirect_to tenant_selection_path, alert: "Please select a tenant" }
+      format.json { render json: { error: "Tenant required" }, status: :unauthorized }
+    end
+  end
+
+  def handle_access_denied
+    respond_to do |format|
+      format.html { redirect_to root_path, alert: "Access denied" }
+      format.json { render json: { error: "Access denied" }, status: :forbidden }
+    end
+  end
+
+  # Helper method to access current tenant in views
+  helper_method :current_tenant
+  attr_reader :current_tenant
+
+  # Custom error handling for tenant-related errors
+  rescue_from PgMultitenantSchemas::TenantNotFoundError do |error|
+    Rails.logger.warn "Tenant not found: #{error.message}"
+
+    respond_to do |format|
+      format.html { redirect_to tenant_selection_path, alert: "Tenant not found" }
+      format.json { render json: { error: "Tenant not found" }, status: :not_found }
+    end
+  end
+
+  rescue_from PgMultitenantSchemas::SchemaError do |error|
+    Rails.logger.error "Schema error: #{error.message}"
+
+    respond_to do |format|
+      format.html { redirect_to root_path, alert: "A database error occurred" }
+      format.json { render json: { error: "Database error" }, status: :internal_server_error }
+    end
+  end
+end
+
+# Example 2: Admin Controller with Multi-Tenant Management
+module Admin
+  # Controller for managing tenants in admin interface
+  # Allows administrators to view, manage, and switch between tenant contexts
+  class TenantsController < Admin::BaseController
+    # Admin controllers might need to switch between tenants
+
+    def index
+      # List all tenants (admin view, not tenant-scoped)
+      @tenants = Tenant.includes(:users, :subscriptions).order(:name)
+    end
+
+    def show
+      @tenant = Tenant.find(params[:id])
+
+      # Get tenant-specific statistics
+      @stats = PgMultitenantSchemas::Context.with_tenant(@tenant) do
+        {
+          users_count: User.count,
+          orders_count: Order.count,
+          revenue: Order.sum(:total),
+          last_activity: User.maximum(:last_sign_in_at)
+        }
+      end
+    end
+
+    def switch
+      @tenant = Tenant.find(params[:id])
+
+      # Allow admin to switch to tenant for support
+      if current_user.admin? && @tenant
+        session[:admin_impersonating_tenant] = @tenant.id
+        redirect_to root_path, notice: "Switched to tenant: #{@tenant.name}"
+      else
+        redirect_to admin_tenants_path, alert: "Access denied"
+      end
+    end
+
+    def stop_impersonation
+      session.delete(:admin_impersonating_tenant)
+      redirect_to admin_tenants_path, notice: "Stopped tenant impersonation"
+    end
+
+    private
+
+    def resolve_tenant_from_request
+      # Admin impersonation takes precedence
+      if session[:admin_impersonating_tenant] && current_user&.admin?
+        return Tenant.find_by(id: session[:admin_impersonating_tenant])
+      end
+
+      # Fall back to normal resolution
+      super
+    end
+  end
+end
+
+# Example 3: API Controller with JWT-based Tenant Resolution
+module Api
+  module V1
+    # Base controller for API endpoints with tenant resolution
+    # Supports JWT and API key authentication with tenant context
+    class BaseController < ActionController::API
+      include PgMultitenantSchemas::ControllerConcern
+
+      before_action :authenticate_api_request
+
+      protected
+
+      def resolve_tenant_from_request
+        # Extract tenant from JWT payload
+        return @jwt_payload["tenant"] if @jwt_payload&.key?("tenant")
+
+        # Extract from API key
+        return @api_key.tenant if @api_key&.tenant
+
+        # Extract from header
+        tenant_id = request.headers["X-Tenant-ID"]
+        return Tenant.find(tenant_id) if tenant_id.present?
+
+        nil
+      rescue ActiveRecord::RecordNotFound
+        nil
+      end
+
+      private
+
+      def authenticate_api_request
+        token = extract_token_from_header
+
+        if token.present?
+          @jwt_payload = decode_jwt_token(token)
+          @api_key = ApiKey.active.find_by(token: token) if @jwt_payload.nil?
+        end
+
+        return if @jwt_payload || @api_key
+
+        render json: { error: "Unauthorized" }, status: :unauthorized
+      end
+
+      def extract_token_from_header
+        auth_header = request.headers["Authorization"]
+        auth_header&.split&.last if auth_header&.start_with?("Bearer ")
+      end
+
+      def decode_jwt_token(token)
+        JWT.decode(token, Rails.application.secret_key_base, true, algorithm: "HS256").first
+      rescue JWT::DecodeError, JWT::ExpiredSignature
+        nil
+      end
+
+      # API-specific error handling
+      rescue_from PgMultitenantSchemas::TenantNotFoundError do |error|
+        render json: {
+          error: "tenant_not_found",
+          message: error.message,
+          code: "TENANT_NOT_FOUND"
+        }, status: :not_found
+      end
+
+      rescue_from PgMultitenantSchemas::SchemaError do |_error|
+        render json: {
+          error: "schema_error",
+          message: "Database schema error",
+          code: "SCHEMA_ERROR"
+        }, status: :internal_server_error
+      end
+    end
+  end
+end
+
+# Example 4: Background Job Controller Integration
+class JobsController < ApplicationController
+  def create
+    # Enqueue job with current tenant context
+    ProcessDataJob.perform_later(
+      current_tenant.id,
+      params[:data_type],
+      params[:options]
+    )
+
+    render json: {
+      message: "Job enqueued successfully",
+      tenant: current_tenant.subdomain
+    }
+  end
+
+  def status
+    # Check job status within tenant context
+    job_id = params[:job_id]
+
+    # Job status checking happens in tenant context
+    job_status = Rails.cache.read("job_status:#{current_tenant.id}:#{job_id}")
+
+    render json: {
+      job_id: job_id,
+      status: job_status || "not_found",
+      tenant: current_tenant.subdomain
+    }
+  end
+end
+
+# Example 5: Multi-Strategy Tenant Resolution Controller
+class FlexibleController < ApplicationController
+  protected
+
+  def resolve_tenant_from_request
+    # Try multiple resolution strategies in order
+    strategies = %i[
+      resolve_by_custom_header
+      resolve_by_subdomain
+      resolve_by_path_parameter
+      resolve_by_user_preference
+      resolve_by_session
+    ]
+
+    strategies.each do |strategy|
+      tenant = send(strategy)
+      return tenant if tenant
+    end
+
+    nil
+  end
+
+  private
+
+  def resolve_by_custom_header
+    tenant_identifier = request.headers["X-Tenant-Identifier"]
+    return nil unless tenant_identifier.present?
+
+    Tenant.find_by(subdomain: tenant_identifier) ||
+      Tenant.find_by(slug: tenant_identifier)
+  end
+
+  def resolve_by_subdomain
+    return nil unless request.subdomain.present?
+
+    Tenant.find_by(subdomain: request.subdomain)
+  end
+
+  def resolve_by_path_parameter
+    # For routes like /t/:tenant_slug/dashboard
+    tenant_slug = params[:tenant_slug]
+    return nil unless tenant_slug.present?
+
+    Tenant.find_by(slug: tenant_slug)
+  end
+
+  def resolve_by_user_preference
+    return nil unless user_signed_in?
+
+    tenant_id = current_user.preferred_tenant_id
+    current_user.tenants.find_by(id: tenant_id) if tenant_id.present?
+  end
+
+  def resolve_by_session
+    tenant_id = session[:selected_tenant_id]
+    Tenant.find_by(id: tenant_id) if tenant_id.present?
+  end
+end
+
+# Example 6: WebSocket Integration
+module ApplicationCable
+  # WebSocket connection with tenant context support
+  # Establishes tenant context for real-time communication
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user, :current_tenant
+
+    def connect
+      self.current_user = find_verified_user
+      self.current_tenant = find_tenant_for_user
+
+      # Set tenant context for the connection
+      PgMultitenantSchemas::Context.switch_to_tenant(current_tenant) if current_tenant
+    end
+
+    private
+
+    def find_verified_user
+      if (verified_user = User.find_by(id: cookies.signed[:user_id]))
+        verified_user
+      else
+        reject_unauthorized_connection
+      end
+    end
+
+    def find_tenant_for_user
+      # Extract tenant from connection params or user preferences
+      tenant_id = request.params[:tenant_id] || current_user.current_tenant_id
+      current_user.tenants.find_by(id: tenant_id)
+    end
+  end
+end
+
+# Example WebSocket Channel with Tenant Context
+class NotificationsChannel < ApplicationCable::Channel
+  def subscribed
+    # Subscribe to tenant-specific notifications
+    if current_tenant
+      stream_from "notifications_#{current_tenant.id}"
+    else
+      reject
+    end
+  end
+
+  def receive(data)
+    # All operations happen within tenant context
+    PgMultitenantSchemas::Context.with_tenant(current_tenant) do
+      case data["action"]
+      when "mark_as_read"
+        notification = Notification.find(data["notification_id"])
+        notification.mark_as_read!
+      when "create"
+        Notification.create!(data["notification"])
+      end
+    end
+  end
+end

data/examples/schema_operations.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Schema Operations Example
+# Demonstrates core schema switching and management operations
+
+require_relative "../lib/pg_multitenant_schemas"
+
+puts "🔧 PG Multitenant Schemas - Schema Operations Example"
+puts "====================================================="
+
+# Example 1: Basic Schema Switching
+puts "\n📋 Example 1: Basic Schema Switching"
+puts "------------------------------------"
+
+# Switch to a tenant schema
+schema_name = "demo_tenant"
+puts "Switching to schema: #{schema_name}"
+
+begin
+  PgMultitenantSchemas::SchemaSwitcher.switch_schema(schema_name)
+  current = PgMultitenantSchemas::SchemaSwitcher.current_schema
+  puts "✅ Current schema: #{current}"
+rescue PgMultitenantSchemas::SchemaError => e
+  puts "❌ Schema switch failed: #{e.message}"
+end
+
+# Example 2: Schema Creation and Management
+puts "\n🏗️  Example 2: Schema Creation and Management"
+puts "---------------------------------------------"
+
+new_schema = "example_tenant"
+puts "Creating schema: #{new_schema}"
+
+begin
+  # Create new schema
+  PgMultitenantSchemas::SchemaSwitcher.create_schema(new_schema)
+  puts "✅ Schema created: #{new_schema}"
+
+  # Verify schema exists
+  puts "✅ Schema exists: #{new_schema}" if PgMultitenantSchemas::SchemaSwitcher.schema_exists?(new_schema)
+
+  # List all schemas
+  schemas = PgMultitenantSchemas::SchemaSwitcher.list_schemas
+  puts "📋 Available schemas: #{schemas.join(", ")}"
+rescue PgMultitenantSchemas::SchemaError => e
+  puts "❌ Schema operation failed: #{e.message}"
+end
+
+# Example 3: Safe Schema Operations
+puts "\n🛡️  Example 3: Safe Schema Operations"
+puts "------------------------------------"
+
+begin
+  # Store current schema
+  original_schema = PgMultitenantSchemas::SchemaSwitcher.current_schema
+  puts "Original schema: #{original_schema}"
+
+  # Switch to tenant schema
+  PgMultitenantSchemas::SchemaSwitcher.switch_schema("demo_tenant")
+  puts "Switched to: #{PgMultitenantSchemas::SchemaSwitcher.current_schema}"
+
+  # Execute some operations here...
+  puts "Performing tenant-specific operations..."
+
+  # Always restore original schema
+  PgMultitenantSchemas::SchemaSwitcher.switch_schema(original_schema)
+  puts "✅ Restored to original schema: #{PgMultitenantSchemas::SchemaSwitcher.current_schema}"
+rescue PgMultitenantSchemas::SchemaError => e
+  puts "❌ Error: #{e.message}"
+  # Ensure we restore the original schema even on error
+  begin
+    PgMultitenantSchemas::SchemaSwitcher.switch_schema(original_schema)
+  rescue StandardError
+    nil
+  end
+end
+
+# Example 4: Schema Validation
+puts "\n✅ Example 4: Schema Validation"
+puts "-------------------------------"
+
+test_schemas = ["valid_schema", "invalid-schema!", "", "another_valid_123"]
+
+test_schemas.each do |schema|
+  puts "Testing schema name: '#{schema}'"
+
+  if schema.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/) && !schema.blank?
+    puts "  ✅ Valid schema name"
+
+    # Try to create (for demonstration)
+    # PgMultitenantSchemas::SchemaSwitcher.create_schema(schema)
+  else
+    puts "  ❌ Invalid schema name format"
+  end
+rescue PgMultitenantSchemas::SchemaError => e
+  puts "  ❌ Schema error: #{e.message}"
+end
+
+# Example 5: Schema Cleanup
+puts "\n🧹 Example 5: Schema Cleanup"
+puts "----------------------------"
+
+cleanup_schema = "example_tenant"
+puts "Cleaning up schema: #{cleanup_schema}"
+
+begin
+  if PgMultitenantSchemas::SchemaSwitcher.schema_exists?(cleanup_schema)
+    PgMultitenantSchemas::SchemaSwitcher.drop_schema(cleanup_schema)
+    puts "✅ Schema dropped: #{cleanup_schema}"
+  else
+    puts "ℹ️  Schema doesn't exist: #{cleanup_schema}"
+  end
+rescue PgMultitenantSchemas::SchemaError => e
+  puts "❌ Cleanup failed: #{e.message}"
+end
+
+puts "\n✨ Schema operations example completed!"
+puts "\n📖 Key Takeaways:"
+puts "  • Always validate schema names before operations"
+puts "  • Use proper error handling for schema operations"
+puts "  • Store and restore original schema in ensure blocks"
+puts "  • Check schema existence before creation or deletion"
+puts "  • Use meaningful schema naming conventions"

data/lib/pg_multitenant_schemas/configuration.rb

@@ -13,11 +13,11 @@ module PgMultitenantSchemas
       @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]
+      @excluded_subdomains = %w[www api admin mail ftp blog support help docs staging]
+      @common_tlds = %w[com org net edu gov mil int co uk ca au de fr jp cn dev test]
       @auto_create_schemas = true
-      @connection_class = "ActiveRecord::Base"
-      @logger = nil
+      @connection_class = "ApplicationRecord"
+      @logger = defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
     end
 
     def tenant_model

data/lib/pg_multitenant_schemas/migration_display_reporter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  # Module for migration display and reporting functionality
+  # Handles console output and summary reports for migration operations
+  module MigrationDisplayReporter
+    private
+
+    def display_migration_summary(results, verbose)
+      return unless verbose
+
+      summary = results.group_by { |r| r[:status] }.transform_values(&:count)
+
+      puts "\n📊 Migration Summary:"
+      puts "  ✅ Successful: #{summary[:success] || 0}"
+      puts "  ❌ Failed: #{summary[:error] || 0}"
+      puts "  ⏭️  Skipped: #{summary[:skipped] || 0}"
+    end
+
+    def display_setup_summary(results, verbose)
+      return unless verbose
+
+      summary = results.group_by { |r| r[:status] }.transform_values(&:count)
+
+      puts "\n📊 Setup Summary:"
+      puts "  ✅ Successful: #{summary[:success] || 0}"
+      puts "  ❌ Failed: #{summary[:error] || 0}"
+    end
+  end
+end

data/lib/pg_multitenant_schemas/migration_executor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  # Module for executing migration operations
+  # Handles the core migration execution and error handling logic
+  module MigrationExecutor
+    private
+
+    def process_schemas_migration(schemas, verbose, ignore_errors)
+      puts "🚀 Starting migrations for #{schemas.count} tenant schemas..." if verbose
+
+      schemas.map do |schema|
+        migrate_tenant(schema, verbose: verbose, raise_on_error: !ignore_errors)
+      end
+    end
+
+    def handle_missing_schema(schema_name, verbose, raise_on_error)
+      message = "Schema '#{schema_name}' does not exist"
+      puts "    ⚠️  #{message}" if verbose
+      raise StandardError, message if raise_on_error
+
+      { schema: schema_name, status: :skipped, message: message }
+    end
+
+    def execute_tenant_migration(schema_name, verbose, raise_on_error)
+      puts "  📦 Migrating schema: #{schema_name}" if verbose
+      original_schema = current_schema
+
+      begin
+        result = perform_migration_for_schema(schema_name, verbose)
+        puts "    ✅ Migration completed" if verbose && result[:status] == :success
+        result
+      rescue StandardError => e
+        handle_migration_error(schema_name, e, verbose, raise_on_error)
+      ensure
+        switch_to_schema(original_schema) if original_schema
+      end
+    end
+
+    def perform_migration_for_schema(schema_name, verbose)
+      switch_to_schema(schema_name)
+      pending_count = pending_migrations.count
+
+      if pending_count.zero?
+        puts "    ℹ️  No pending migrations" if verbose
+        return { schema: schema_name, status: :success, message: "No pending migrations" }
+      end
+
+      run_migrations
+      { schema: schema_name, status: :success, message: "#{pending_count} migrations applied" }
+    end
+
+    def handle_migration_error(schema_name, error, verbose, raise_on_error)
+      message = "Migration failed: #{error.message}"
+      puts "    ❌ #{message}" if verbose
+      raise error if raise_on_error
+
+      { schema: schema_name, status: :error, message: message }
+    end
+
+    def create_tenant_schema_if_needed(schema_name, verbose)
+      if schema_exists?(schema_name)
+        puts "  ℹ️  Schema already exists" if verbose
+      else
+        create_schema(schema_name)
+        puts "  ✅ Schema created" if verbose
+      end
+    end
+
+    def validate_tenant_model_exists
+      raise "Tenant model not found. Please define a Tenant model." unless defined?(Tenant)
+    end
+
+    def process_setup_for_tenants(tenants, verbose)
+      tenants.map do |tenant|
+        schema_name = extract_schema_name(tenant)
+        setup_tenant(schema_name, verbose: verbose)
+      end
+    end
+  end
+end

data/lib/pg_multitenant_schemas/migration_schema_operations.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PgMultitenantSchemas
+  # Schema operations for migration management
+  module MigrationSchemaOperations
+    private
+
+    # Delegate schema operations to SchemaSwitcher
+    def switch_to_schema(schema_name)
+      SchemaSwitcher.switch_schema(schema_name)
+    end
+
+    def create_schema(schema_name)
+      SchemaSwitcher.create_schema(schema_name)
+    end
+
+    def schema_exists?(schema_name)
+      SchemaSwitcher.schema_exists?(schema_name)
+    end
+
+    def current_schema
+      SchemaSwitcher.current_schema
+    end
+
+    def tenant_schemas
+      SchemaSwitcher.list_schemas.reject do |schema|
+        %w[information_schema pg_catalog public pg_temp_1 pg_toast_temp_1].include?(schema) ||
+          schema.start_with?("pg_toast")
+      end
+    end
+
+    def extract_schema_name(tenant)
+      tenant.respond_to?(:subdomain) ? tenant.subdomain : tenant.to_s
+    end
+
+    def run_migrations
+      ActiveRecord::Base.connection.migrate
+    end
+
+    def pending_migrations
+      ActiveRecord::Base.connection.migration_context.migrations.reject do |migration|
+        ActiveRecord::Base.connection.migration_context.get_all_versions.include?(migration.version)
+      end
+    end
+
+    def applied_migrations
+      ActiveRecord::Base.connection.migration_context.get_all_versions
+    end
+
+    def migration_paths
+      ActiveRecord::Base.connection.migration_context.migrations_paths
+    end
+  end
+end