pg_multitenant_schemas 0.1.3 → 0.2.2

data/docs/testing.md

@@ -0,0 +1,358 @@
+# RSpec Testing Guide - PgMultitenantSchemas
+
+## 📋 **Overview**
+
+This document provides comprehensive information about the RSpec test suite for the PgMultitenantSchemas gem, including unit tests, integration tests, and testing best practices.
+
+## 🏗️ **Test Architecture**
+
+### **Test Categories**
+
+The test suite is organized into two main categories:
+
+#### **1. Unit Tests** (Fast, Isolated)
+- **Location**: `spec/*_spec.rb`
+- **Execution**: Default `bundle exec rspec` 
+- **Purpose**: Test individual components in isolation
+- **Database**: Uses mocked connections where possible
+- **Speed**: Very fast (~0.03-0.16 seconds)
+
+#### **2. Integration Tests** (Comprehensive, Database)
+- **Location**: Tagged with `:integration`
+- **Execution**: `bundle exec rspec --tag integration`
+- **Purpose**: Test real PostgreSQL interactions and multi-schema operations
+- **Database**: Requires running PostgreSQL instance
+- **Speed**: Moderate (~0.67-1.17 seconds)
+
+## ⚙️ **Configuration**
+
+### **RSpec Configuration Files**
+
+#### **`.rspec`**
+```plaintext
+--format documentation
+--color
+--require spec_helper
+--tag ~integration          # Exclude integration tests by default
+```
+
+#### **`spec/spec_helper.rb`**
+```ruby
+require "rspec"
+require "pg_multitenant_schemas"
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+  config.disable_monkey_patching!
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end
+```
+
+### **Environment Variables**
+
+Integration tests use these environment variables for PostgreSQL connection:
+
+```bash
+PG_HOST=localhost              # PostgreSQL host
+PG_PORT=5432                  # PostgreSQL port  
+PG_TEST_DATABASE=pg_multitenant_test  # Test database name
+PG_USER=postgres              # Database user
+PG_PASSWORD=                  # Database password (empty by default)
+```
+
+## 🧪 **Test Suite Structure**
+
+### **Unit Tests (65 examples)**
+
+| **Test File** | **Component** | **Purpose** |
+|---------------|---------------|-------------|
+| `configuration_spec.rb` | Configuration | Test configuration options and validation |
+| `context_spec.rb` | Context | Test tenant/schema context management |
+| `schema_switcher_spec.rb` | SchemaSwitcher | Test schema operations (mocked) |
+| `tenant_resolver_spec.rb` | TenantResolver | Test subdomain extraction and tenant resolution |
+| `pg_multitenant_schemas_spec.rb` | Main Module | Test gem version and basic functionality |
+| `edge_cases_spec.rb` | Edge Cases | Test error handling and edge cases |
+| `performance_spec.rb` | Performance | Test memory usage and thread safety |
+| `integration_spec.rb` | Integration | Test component interactions (mocked) |
+| `errors_spec.rb` | Error Classes | Test custom error definitions |
+| `rails_integration/tenant_spec.rb` | Rails Integration | Test Rails model and validation integration |
+
+### **Integration Tests (21 examples)**
+
+| **Test File** | **Component** | **Purpose** |
+|---------------|---------------|-------------|
+| `postgresql_integration_spec.rb` | PostgreSQL | Real database schema operations |
+| `multiple_schemas_integration_spec.rb` | Multi-Schema | Complex schema interactions and isolation |
+| `multiple_schemas_database_spec.rb` | Database Ops | Bulk operations and schema management |
+| `multiple_tenants_context_spec.rb` | Context | Multi-tenant context switching |
+
+## 🚀 **Running Tests**
+
+### **Unit Tests Only** (Default, Fast)
+```bash
+# Run all unit tests (excludes integration)
+bundle exec rspec
+
+# Run specific unit test file
+bundle exec rspec spec/configuration_spec.rb
+
+# Run with verbose output
+bundle exec rspec --format documentation
+```
+
+### **Integration Tests Only** (Requires PostgreSQL)
+```bash
+# Run all integration tests
+bundle exec rspec --tag integration
+
+# Run with documentation format
+bundle exec rspec --tag integration --format documentation
+
+# Run specific integration test
+bundle exec rspec spec/postgresql_integration_spec.rb
+```
+
+### **All Tests** (Complete Test Suite)
+```bash
+# Run both unit and integration tests
+bundle exec rspec --tag integration spec/ && bundle exec rspec
+
+# Alternative: Run all tests including integration
+bundle exec rspec --no-tag
+```
+
+## 🔍 **Test Categories Deep Dive**
+
+### **Unit Tests Details**
+
+#### **Configuration Tests**
+```ruby
+# Tests configuration object behavior
+RSpec.describe PgMultitenantSchemas::Configuration do
+  describe "#initialize" do
+    it "sets default values"
+  end
+  
+  describe "#connection_class=" do
+    it "allows setting connection class"
+  end
+end
+```
+
+#### **Context Management Tests**
+```ruby
+# Tests tenant/schema context switching
+RSpec.describe PgMultitenantSchemas::Context do
+  describe ".current_schema" do
+    it "defaults to public schema"
+  end
+  
+  describe ".current_tenant=" do
+    it "sets the current tenant"
+  end
+end
+```
+
+#### **Edge Cases and Error Handling**
+```ruby
+# Tests robust error handling
+RSpec.describe "Edge Cases and Error Handling" do
+  describe "schema name validation" do
+    it "handles whitespace-only schema names"
+    it "handles special characters in schema names"
+    it "handles unicode characters"
+  end
+end
+```
+
+### **Integration Tests Details**
+
+#### **PostgreSQL Integration Tests**
+```ruby
+# Real database operations
+RSpec.describe "PostgreSQL Integration Tests", :integration do
+  describe "schema creation" do
+    it "actually creates a schema in PostgreSQL"
+  end
+  
+  describe "schema switching" do
+    it "actually switches the search_path"
+  end
+end
+```
+
+#### **Multiple Schemas Integration**
+```ruby
+# Complex multi-tenant scenarios
+RSpec.describe "Multiple Schemas Integration Tests", :integration do
+  describe "multiple tenant schemas" do
+    it "creates multiple schemas successfully"
+    it "maintains data isolation between schemas"
+    it "handles concurrent schema access safely"
+  end
+end
+```
+
+## 🛠️ **Database Setup for Integration Tests**
+
+### **Prerequisites**
+
+1. **PostgreSQL Running**: Ensure PostgreSQL is running locally or accessible
+2. **Test Database**: Create a test database (usually `pg_multitenant_test`)
+3. **Permissions**: Ensure test user has schema creation/deletion permissions
+
+### **Setup Commands**
+
+```bash
+# Create test database (PostgreSQL)
+createdb pg_multitenant_test
+
+# Or using psql
+psql -c "CREATE DATABASE pg_multitenant_test;"
+
+# Grant necessary permissions
+psql -d pg_multitenant_test -c "GRANT ALL PRIVILEGES ON DATABASE pg_multitenant_test TO postgres;"
+```
+
+### **Connection Configuration**
+
+Integration tests automatically handle connection setup:
+
+```ruby
+let(:db_config) do
+  {
+    host: ENV["PG_HOST"] || "localhost",
+    port: ENV["PG_PORT"] || 5432,
+    dbname: ENV["PG_TEST_DATABASE"] || "pg_multitenant_test",
+    user: ENV["PG_USER"] || "postgres",
+    password: ENV["PG_PASSWORD"] || ""
+  }
+end
+```
+
+## 🧹 **Test Cleanup and Isolation**
+
+### **Automatic Cleanup**
+
+Integration tests include comprehensive cleanup:
+
+```ruby
+after do
+  # Clean up test schemas
+  ["tenant_a", "tenant_b", "tenant_c", "public_test"].each do |schema|
+    PgMultitenantSchemas::SchemaSwitcher.drop_schema(schema, cascade: true)
+  rescue => e
+    # Log cleanup errors but don't fail tests
+  end
+  
+  # Reset to public schema
+  PgMultitenantSchemas::SchemaSwitcher.reset_to_public_schema
+end
+```
+
+### **Schema Isolation**
+
+Each test creates and destroys its own schemas:
+
+```ruby
+let(:tenants) { ["tenant_a", "tenant_b", "tenant_c"] }
+
+before do
+  # Ensure clean state
+  tenants.each { |t| PgMultitenantSchemas::SchemaSwitcher.create_schema(t) }
+end
+```
+
+## 📊 **Test Coverage and Quality**
+
+### **Current Test Metrics**
+
+- **Total Examples**: 86 (65 unit + 21 integration)
+- **Failures**: 0
+- **Coverage Areas**:
+  - ✅ Configuration management
+  - ✅ Schema operations  
+  - ✅ Tenant resolution
+  - ✅ Context switching
+  - ✅ Error handling
+  - ✅ Performance characteristics
+  - ✅ Thread safety
+  - ✅ Rails integration
+  - ✅ Multi-schema scenarios
+  - ✅ Concurrent access patterns
+
+### **Test Quality Features**
+
+- **Fast Unit Tests**: Complete in ~0.03 seconds
+- **Comprehensive Integration**: Real PostgreSQL testing
+- **Thread Safety**: Multi-threaded scenario testing
+- **Memory Leak Detection**: Performance monitoring
+- **Edge Case Coverage**: Unicode, special characters, malformed data
+- **Error Scenario Testing**: Connection failures, invalid schemas
+
+## 🔧 **Debugging Tests**
+
+### **Common Issues and Solutions**
+
+#### **PostgreSQL Connection Issues**
+```bash
+# Check if PostgreSQL is running
+pg_isready
+
+# Check connection with custom settings
+PG_HOST=localhost PG_USER=myuser bundle exec rspec --tag integration
+```
+
+#### **Schema Cleanup Issues**
+```ruby
+# Manual cleanup if tests leave artifacts
+psql -d pg_multitenant_test -c "DROP SCHEMA IF EXISTS tenant_a CASCADE;"
+```
+
+#### **Verbose Test Output**
+```bash
+# Run with detailed output for debugging
+bundle exec rspec --format documentation --color
+
+# Run specific failing test
+bundle exec rspec spec/multiple_schemas_integration_spec.rb:90 --format documentation
+```
+
+### **Test Development Tips**
+
+1. **Unit Test First**: Write fast unit tests before integration tests
+2. **Mock External Dependencies**: Use mocks for database connections in unit tests
+3. **Clean Isolation**: Ensure each test cleans up after itself
+4. **Descriptive Names**: Use clear, descriptive test names
+5. **Edge Cases**: Test boundary conditions and error scenarios
+
+## 📚 **Related Documentation**
+
+- **[Architecture Overview](README.md)**: Understanding the overall gem structure
+- **[Configuration Guide](configuration.md)**: Test configuration options
+- **[Rails Integration](rails_integration.md)**: Framework-specific testing patterns
+- **[Error Handling](errors.md)**: Error testing strategies
+
+## 🎯 **Test Development Workflow**
+
+### **Adding New Tests**
+
+1. **Identify Test Type**: Unit vs Integration
+2. **Create Test File**: Follow naming convention `*_spec.rb`
+3. **Add Appropriate Tags**: Use `:integration` for database tests
+4. **Include Setup/Teardown**: Proper before/after hooks
+5. **Test Edge Cases**: Include error scenarios
+6. **Run Test Suite**: Verify no regressions
+
+### **Best Practices**
+
+- **Keep Unit Tests Fast**: Avoid database calls in unit tests
+- **Use Descriptive Contexts**: Group related tests logically  
+- **Test Public APIs**: Focus on public interface testing
+- **Mock External Services**: Isolate component under test
+- **Include Performance Tests**: Monitor resource usage
+- **Document Complex Scenarios**: Comment non-obvious test logic
+
+This comprehensive test suite ensures the PgMultitenantSchemas gem is robust, reliable, and ready for production use across various scenarios and environments.

data/examples/context_management.rb

@@ -0,0 +1,198 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Context Management Example
+# Demonstrates thread-safe tenant context management
+
+require_relative "../lib/pg_multitenant_schemas"
+
+puts "🧵 PG Multitenant Schemas - Context Management Example"
+puts "======================================================"
+
+# Mock tenant class for demonstration
+class MockTenant
+  attr_reader :id, :subdomain, :name
+
+  def initialize(id, subdomain, name)
+    @id = id
+    @subdomain = subdomain
+    @name = name
+  end
+
+  def to_s
+    subdomain
+  end
+end
+
+# Create mock tenants
+tenant_a = MockTenant.new(1, "acme_corp", "ACME Corporation")
+tenant_b = MockTenant.new(2, "beta_inc", "Beta Inc")
+
+# Example 1: Basic Context Management
+puts "\n📋 Example 1: Basic Context Management"
+puts "--------------------------------------"
+
+# Check initial state
+puts "Initial context:"
+puts "  Current tenant: #{PgMultitenantSchemas::Context.current_tenant || "none"}"
+puts "  Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+
+# Switch to tenant A
+puts "\nSwitching to tenant A (#{tenant_a.subdomain}):"
+PgMultitenantSchemas::Context.switch_to_tenant(tenant_a)
+puts "  Current tenant: #{PgMultitenantSchemas::Context.current_tenant}"
+puts "  Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+
+# Switch to tenant B
+puts "\nSwitching to tenant B (#{tenant_b.subdomain}):"
+PgMultitenantSchemas::Context.switch_to_tenant(tenant_b)
+puts "  Current tenant: #{PgMultitenantSchemas::Context.current_tenant}"
+puts "  Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+
+# Reset context
+puts "\nResetting context:"
+PgMultitenantSchemas::Context.reset!
+puts "  Current tenant: #{PgMultitenantSchemas::Context.current_tenant || "none"}"
+puts "  Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+
+# Example 2: Block-Based Context Management
+puts "\n🔄 Example 2: Block-Based Context Management"
+puts "--------------------------------------------"
+
+puts "Before block - Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+
+PgMultitenantSchemas::Context.with_tenant(tenant_a) do
+  puts "Inside block - Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+  puts "Inside block - Current tenant: #{PgMultitenantSchemas::Context.current_tenant}"
+
+  # Simulate some work in tenant context
+  puts "  🔧 Performing operations for #{tenant_a.name}..."
+  sleep(0.1) # Simulate work
+end
+
+puts "After block - Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+puts "After block - Current tenant: #{PgMultitenantSchemas::Context.current_tenant || "none"}"
+
+# Example 3: Nested Context Management
+puts "\n🪆 Example 3: Nested Context Management"
+puts "---------------------------------------"
+
+puts "Starting nested context example..."
+
+PgMultitenantSchemas::Context.with_tenant(tenant_a) do
+  puts "Level 1 - In tenant A (#{PgMultitenantSchemas::Context.current_schema})"
+
+  PgMultitenantSchemas::Context.with_tenant(tenant_b) do
+    puts "  Level 2 - In tenant B (#{PgMultitenantSchemas::Context.current_schema})"
+
+    # Even deeper nesting
+    PgMultitenantSchemas::Context.with_tenant("custom_schema") do
+      puts "    Level 3 - In custom schema (#{PgMultitenantSchemas::Context.current_schema})"
+    end
+
+    puts "  Level 2 - Back in tenant B (#{PgMultitenantSchemas::Context.current_schema})"
+  end
+
+  puts "Level 1 - Back in tenant A (#{PgMultitenantSchemas::Context.current_schema})"
+end
+
+puts "Nested context complete - Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+
+# Example 4: Error Handling in Context
+puts "\n🚨 Example 4: Error Handling in Context"
+puts "---------------------------------------"
+
+puts "Testing error handling with context restoration..."
+
+begin
+  PgMultitenantSchemas::Context.with_tenant(tenant_a) do
+    puts "In tenant A context: #{PgMultitenantSchemas::Context.current_schema}"
+
+    # Simulate an error
+    raise StandardError, "Simulated error!"
+  end
+rescue StandardError => e
+  puts "Caught error: #{e.message}"
+end
+
+puts "After error - Current schema: #{PgMultitenantSchemas::Context.current_schema}"
+puts "✅ Context properly restored after error!"
+
+# Example 5: Thread Safety Demonstration
+puts "\n🧵 Example 5: Thread Safety Demonstration"
+puts "-----------------------------------------"
+
+threads = []
+results = {}
+
+# Create multiple threads with different tenant contexts
+[tenant_a, tenant_b].each_with_index do |tenant, index|
+  threads << Thread.new do
+    thread_id = "Thread-#{index + 1}"
+    results[thread_id] = []
+
+    PgMultitenantSchemas::Context.with_tenant(tenant) do
+      5.times do |i|
+        current_schema = PgMultitenantSchemas::Context.current_schema
+        current_tenant = PgMultitenantSchemas::Context.current_tenant
+
+        results[thread_id] << {
+          iteration: i + 1,
+          schema: current_schema,
+          tenant: current_tenant&.subdomain,
+          thread: Thread.current.object_id
+        }
+
+        sleep(0.01) # Small delay to allow thread interleaving
+      end
+    end
+  end
+end
+
+# Wait for all threads to complete
+threads.each(&:join)
+
+# Display results
+puts "Thread safety results:"
+results.each do |thread_id, iterations|
+  puts "#{thread_id}:"
+  iterations.each do |result|
+    puts "  Iteration #{result[:iteration]}: #{result[:schema]} (tenant: #{result[:tenant]})"
+  end
+end
+
+puts "✅ Each thread maintained its own tenant context!"
+
+# Example 6: Schema Management Through Context
+puts "\n🔧 Example 6: Schema Management Through Context"
+puts "----------------------------------------------"
+
+test_tenant = MockTenant.new(99, "test_tenant", "Test Tenant")
+
+begin
+  # Create tenant schema
+  puts "Creating schema for tenant: #{test_tenant.subdomain}"
+  PgMultitenantSchemas::Context.create_tenant_schema(test_tenant)
+  puts "✅ Schema created successfully"
+
+  # Use the tenant context
+  PgMultitenantSchemas::Context.with_tenant(test_tenant) do
+    puts "Operating in tenant schema: #{PgMultitenantSchemas::Context.current_schema}"
+    # Simulate tenant operations
+  end
+
+  # Clean up
+  puts "Cleaning up test schema..."
+  PgMultitenantSchemas::Context.drop_tenant_schema(test_tenant)
+  puts "✅ Schema cleaned up successfully"
+rescue PgMultitenantSchemas::SchemaError => e
+  puts "❌ Schema operation failed: #{e.message}"
+end
+
+puts "\n✨ Context management example completed!"
+puts "\n📖 Key Takeaways:"
+puts "  • Context is automatically restored after blocks"
+puts "  • Each thread maintains independent tenant context"
+puts "  • Nested contexts work correctly with proper restoration"
+puts "  • Error handling doesn't break context restoration"
+puts "  • Context can handle both tenant objects and schema strings"

data/examples/migration_workflow.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example script demonstrating the new migration workflow
+# This shows how the simplified migration system works
+
+require_relative "../lib/pg_multitenant_schemas"
+
+puts "🚀 PG Multitenant Schemas - Migration Workflow Example"
+puts "======================================================"
+
+# Example 1: Setup new tenant with full migration
+puts "\n📋 Example 1: Setting up a new tenant"
+puts "Command: PgMultitenantSchemas::Migrator.setup_tenant('example_corp')"
+puts "Result: Creates schema + runs all migrations automatically"
+
+# Example 2: Migration status check
+puts "\n📊 Example 2: Checking migration status"
+puts "Command: PgMultitenantSchemas::Migrator.migration_status"
+puts "Result: Shows status across all tenant schemas"
+
+# Example 3: Bulk migration
+puts "\n🔄 Example 3: Migrate all tenants"
+puts "Command: PgMultitenantSchemas::Migrator.migrate_all"
+puts "Result: Runs pending migrations across all tenant schemas"
+
+# Example 4: Individual tenant migration
+puts "\n🎯 Example 4: Migrate specific tenant"
+puts "Command: PgMultitenantSchemas::Migrator.migrate_tenant('acme_corp')"
+puts "Result: Runs migrations only for acme_corp schema"
+
+# Example 5: Create tenant with attributes
+puts "\n🏢 Example 5: Create tenant with attributes"
+puts "Command: PgMultitenantSchemas::Migrator.create_tenant_with_schema({subdomain: 'newco', name: 'New Company'})"
+puts "Result: Creates Tenant record + schema + runs migrations"
+
+puts "\n✨ Key Benefits:"
+puts "  • Single command migration across all tenants"
+puts "  • Automatic error handling per tenant"
+puts "  • Progress tracking and status reporting"
+puts "  • Simplified rake task interface"
+puts "  • Programmatic API for custom workflows"
+
+puts "\n🔧 Rake Task Examples:"
+puts "  rails tenants:migrate          # Migrate all tenants"
+puts "  rails tenants:create[newco]    # Setup new tenant"
+puts "  rails tenants:status           # Check migration status"
+puts "  rails tenants:list             # List all tenant schemas"
+
+puts "\n📖 See README.md for complete documentation"