pg_multitenant_schemas 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e4486368a3eff30c0b78d763ea5240a9c53290124bc9c86db5a95d758097543
-  data.tar.gz: 652ec19727ac61cb61306c50cf7cff6bc2813b35c849419299f3c07f70239e49
+  metadata.gz: bb953481e57f8425d7a272414d51e9225d224f6975f7e519051566f8e6c58406
+  data.tar.gz: 3512040a1448b3a8cca8f829717ecc373510234bc53e2d84243272ea16903846
 SHA512:
-  metadata.gz: c1b96e168c0e3a6c9e80fea6d842aa8fd02e1d002681d6a075b7c90a2d2974dce0f2891a17f8b1081db10a48932b096db1152d1a7c55efe860f19ac80eea8068
-  data.tar.gz: bbfaa928d0bbbe90bc03eddf06ab1467e072db15f2ac43522bd932eb1a2ea9fdc489a03aeb549a25480686c0854106c2e5cb1ffe5f3c7806ca0c73b991b07679
+  metadata.gz: c4e77e04b02112a32d8ac953ab0c88a662cc599ec1fc498f6c3205c3a4596ba74e26c514add5de50df58414ff4dfd62a65241e2dbe26f1dbfcdd3093eab25426
+  data.tar.gz: 267b65ce20ab82f817c1ecd959dcd3781ad7f0b00434a381cf3a7968cf1e5363bf57519d26e07cf3bc9d75b90797f2b394c2a3bca8ef060b52e01768ce8c10e4

data/.ruby-version

@@ -0,0 +1 @@
+3.4.3

data/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 🚀 **Migration System Overhaul** 
+- **NEW: Automated Migration Management**: Complete migration system for multi-tenant schemas
+- **NEW: PgMultitenantSchemas::Migrator**: Comprehensive migration management class
+- **NEW: Simplified Rake Tasks**: Modern `tenants:*` namespace with intuitive commands
+- **NEW: Bulk Operations**: Single-command migration across all tenant schemas
+- **NEW: Enhanced Status Reporting**: Detailed migration status with progress indicators
+
+### ✨ **Enhanced Features**
+- **Automated Tenant Setup**: `setup_tenant()` creates schema + runs migrations
+- **Migration Status Tracking**: Real-time status across all tenant schemas  
+- **Error Resilience**: Graceful error handling per tenant during bulk operations
+- **Tenant Creation Workflow**: `create_tenant_with_schema()` for complete tenant setup
+- **Rollback Support**: Individual tenant rollback capabilities
+
+### 🔧 **Developer Experience**
+- **Intuitive Commands**: `rails tenants:migrate`, `rails tenants:status`, `rails tenants:create`
+- **Progress Feedback**: Visual progress indicators during migration operations
+- **Safety Features**: Confirmation prompts for destructive operations
+- **Legacy Compatibility**: Deprecated old commands with migration path
+- **Example Scripts**: Complete workflow documentation and examples
+
+## [0.2.0] - 2025-09-06
+
+### 🚀 **BREAKING CHANGES**
+- **Modernized for Rails 8+ and Ruby 3.4+**: Removed backward compatibility
+- **Simplified API**: Removed dual API support for cleaner codebase
+- **Rails 8+ Only**: Updated dependencies to require ActiveRecord >= 8.0
+- **Ruby 3.2+ Required**: Minimum Ruby version increased from 3.1.0 to 3.2.0
+
+### ✨ **Added**
+- Modern Ruby 3.3+ features and performance optimizations
+- Enhanced configuration defaults for Rails 8+ applications
+- Improved error messages and developer experience
+
+### 🔧 **Changed**
+- Simplified `SchemaSwitcher` API (removed connection parameter overloads)
+- Updated default connection class to `ApplicationRecord`
+- Enhanced excluded subdomains and TLD lists
+- Automatic Rails logger integration
+
+### 🗑️ **Removed**
+- Backward compatibility layers
+- Dual API support (old conn parameter methods)
+- Legacy Rails version compatibility code
+- Ruby < 3.3 support
+
 ## [0.1.3] - 2025-09-03
 
 ### Added

data/README.md

@@ -3,18 +3,27 @@
 [![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.
+A modern Ruby gem that provides PostgreSQL schema-based multitenancy with automatic tenant resolution and schema switching. Built for Rails 8+ and Ruby 3.3+, focusing on security, performance, and developer experience.
 
-## Features
+## ✨ Features
 
 - 🏢 **Schema-based multitenancy** - Complete tenant isolation using PostgreSQL schemas
-- 🔄 **Automatic schema switching** - Seamlessly switch between tenant 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
+- � **Rails 8+ optimized** - Built for modern Rails applications
+- �️ **Security-first design** - Database-level tenant isolation
 - 🧵 **Thread-safe** - Safe for concurrent operations
 - 📝 **Comprehensive logging** - Track schema operations
-- ⚡ **High performance** - Minimal overhead
+- ⚡ **High performance** - Minimal overhead with clean API
+
+## 📋 Requirements
+
+## Requirements
+
+- Ruby 3.4+
+- Rails 8.0+
+- PostgreSQL 12+
+- **pg gem**: 1.5 or higher
 
 ## Installation
 
@@ -53,20 +62,90 @@ end
 
 ## Usage
 
-### Basic Schema Operations
+### Migration Management
 
-```ruby
-# Switch to a tenant schema
-PgMultitenantSchemas::SchemaSwitcher.switch_schema('tenant_123')
+The gem provides automated migration management across all tenant schemas:
 
-# Create a new schema
-PgMultitenantSchemas::SchemaSwitcher.create_schema('tenant_456')
+#### Running Migrations
 
-# Check if schema exists
-PgMultitenantSchemas::SchemaSwitcher.schema_exists?('tenant_123')
+```bash
+# Migrate all tenant schemas at once (recommended)
+rails tenants:migrate
+
+# Migrate a specific tenant
+rails tenants:migrate_tenant[acme_corp]
 
-# Drop a schema
-PgMultitenantSchemas::SchemaSwitcher.drop_schema('tenant_456')
+# Check migration status across all tenants
+rails tenants:status
+```
+
+#### Setting Up New Tenants
+
+```bash
+# Create new tenant with full setup (schema + migrations)
+rails tenants:create[new_tenant]
+
+# Create tenant with attributes using JSON
+rails tenants:new['{"subdomain":"acme","name":"ACME Corp","domain":"acme.com"}']
+
+# Setup schemas for all existing tenants (migration from single-tenant)
+rails tenants:setup
+```
+
+#### Migration Workflow
+
+1. **Create your migration** as usual:
+   ```bash
+   rails generate migration AddEmailToUsers email:string
+   ```
+
+2. **Deploy to all tenants** with a single command:
+   ```bash
+   rails tenants:migrate
+   ```
+
+3. **Check status** to verify migrations across tenants:
+   ```bash
+   rails tenants:status
+   ```
+
+   This shows detailed migration status:
+   ```
+   📊 Migration Status Report
+   ▸ acme_corp: ✅ Up to date (5 migrations)
+   ▸ beta_corp: ⚠️  2 pending migrations
+   ▸ demo_corp: ✅ Up to date (5 migrations)
+   
+   📈 Overall: 2/3 tenants current, 2 migrations pending
+   ```
+
+The migrator automatically:
+- Runs migrations across all tenant schemas
+- Provides detailed progress feedback
+- Handles errors gracefully per tenant
+- Maintains migration version tracking per schema
+- Supports rollbacks for individual tenants
+
+#### Advanced Migration Operations
+
+```bash
+# List all tenant schemas
+rails tenants:list
+
+# Rollback specific tenant
+rails tenants:rollback[tenant_name,2]  # rollback 2 steps
+
+# Drop tenant schema (DANGEROUS - requires confirmation)
+rails tenants:drop[old_tenant]
+```
+
+#### Programmatic Access
+
+```ruby
+# Use the Migrator directly in your code
+PgMultitenantSchemas::Migrator.migrate_all
+PgMultitenantSchemas::Migrator.setup_tenant('new_client')
+PgMultitenantSchemas::Migrator.migration_status
 ```
 
 ### Tenant Resolution
@@ -130,6 +209,180 @@ class Tenant < ApplicationRecord
 end
 ```
 
+## 🏗️ Multi-Tenant Architecture Principles
+
+### Core Principle: Tenant Isolation
+
+**In well-designed multi-tenant applications, tenants should NOT communicate with each other directly.** Each tenant operates in complete isolation for security, compliance, and data integrity.
+
+```ruby
+# ✅ GOOD: Isolated tenant operations
+PgMultitenantSchemas.with_tenant(tenant) do
+  # All operations are isolated to this tenant's schema
+  User.create!(name: "John", email: "john@example.com")
+  Order.where(status: "pending").update_all(status: "processed")
+end
+
+# ❌ BAD: Cross-tenant data sharing (security risk!)
+# Never do: tenant_a.users.merge(tenant_b.users)
+```
+
+### When Cross-Schema Operations Are Appropriate
+
+There are only **3 legitimate use cases** for cross-schema operations:
+
+#### 1. **Platform Analytics & Reporting** (Admin-only)
+```ruby
+# Platform owner needs aggregate statistics across all tenants
+def platform_analytics
+  PgMultitenantSchemas::SchemaSwitcher.with_connection do |conn|
+    conn.execute(<<~SQL)
+      SELECT 
+        schemaname as tenant,
+        COUNT(*) as total_users,
+        SUM(revenue) as total_revenue
+      FROM (
+        SELECT 'tenant_a' as schemaname, COUNT(*) as users, 
+               (SELECT SUM(amount) FROM tenant_a.orders) as revenue
+        UNION ALL
+        SELECT 'tenant_b' as schemaname, COUNT(*) as users,
+               (SELECT SUM(amount) FROM tenant_b.orders) as revenue
+      ) stats
+      GROUP BY schemaname;
+    SQL
+  end
+end
+```
+
+#### 2. **Tenant Migration & Data Operations** (Admin-only)
+```ruby
+# Moving data between environments or consolidating tenants
+def migrate_tenant_data(from_tenant, to_tenant)
+  PgMultitenantSchemas.with_tenant(from_tenant) do
+    users = User.all.to_a
+  end
+  
+  PgMultitenantSchemas.with_tenant(to_tenant) do
+    users.each { |user| User.create!(user.attributes.except('id')) }
+  end
+end
+```
+
+#### 3. **Shared Reference Data** (Read-only)
+```ruby
+# Shared lookup tables that all tenants can read (e.g., countries, currencies)
+class Country < ApplicationRecord
+  self.table_name = 'public.countries'  # Shared across all schemas
+end
+
+# In tenant context, can still access shared data
+PgMultitenantSchemas.with_tenant(tenant) do
+  user = User.create!(name: "John", country: Country.find_by(code: 'US'))
+end
+```
+
+### 🚫 Anti-Patterns to Avoid
+
+```ruby
+# ❌ NEVER: Direct tenant-to-tenant communication
+def share_data_between_tenants(tenant_a, tenant_b)
+  # This violates tenant isolation!
+end
+
+# ❌ NEVER: Cross-tenant user authentication
+def authenticate_user_across_tenants(email)
+  # Users should only exist in their tenant's schema
+end
+
+# ❌ NEVER: Cross-tenant business logic
+def process_order_with_other_tenant_data(order_id, other_tenant)
+  # Business logic should be isolated per tenant
+end
+```
+
+### Why Tenant Isolation Matters
+
+1. **Security**: Prevents accidental data leaks between customers
+2. **Compliance**: GDPR, HIPAA, SOX require strict data separation  
+3. **Performance**: Each tenant's queries are optimized for their data size
+4. **Reliability**: One tenant's issues don't affect others
+5. **Scalability**: Easy to move tenants to different database servers
+
+### Architecture Recommendation
+
+```ruby
+# ✅ Proper multi-tenant architecture
+class ApplicationController < ActionController::Base
+  include PgMultitenantSchemas::Rails::ControllerConcern
+  
+  before_action :authenticate_user!
+  before_action :resolve_tenant
+  before_action :ensure_user_belongs_to_tenant
+  
+  private
+  
+  def resolve_tenant
+    @tenant = resolve_tenant_from_subdomain
+    switch_to_tenant(@tenant) if @tenant
+  end
+  
+  def ensure_user_belongs_to_tenant
+    # Ensure current user can only access their tenant's data
+    redirect_to_login unless current_user.tenant == @tenant
+  end
+end
+```
+
+**Bottom Line**: Cross-tenant operations should be **extremely rare**, **admin-only**, and **carefully audited**. The vast majority of your application should operate within a single tenant's schema.
+
+## 📚 Documentation
+
+### Complete Architecture Documentation
+
+Detailed documentation for each core component:
+
+- **[📁 Core Architecture Overview](docs/README.md)** - Complete system architecture
+- **[🔧 Schema Switcher](docs/schema_switcher.md)** - Low-level PostgreSQL schema operations
+- **[🧵 Context Management](docs/context.md)** - Thread-safe tenant context handling
+- **[🚀 Migration System](docs/migrator.md)** - Automated migration management
+- **[⚙️ Configuration](docs/configuration.md)** - Gem settings and customization
+- **[🔍 Tenant Resolver](docs/tenant_resolver.md)** - Tenant identification strategies
+- **[🛤️ Rails Integration](docs/rails_integration.md)** - Framework components and patterns
+- **[🚨 Error Handling](docs/errors.md)** - Exception classes and error management
+
+### Examples and Patterns
+
+- **[Schema Operations](examples/schema_operations.rb)** - Core schema management
+- **[Context Management](examples/context_management.rb)** - Thread-safe tenant switching
+- **[Migration Workflow](examples/migration_workflow.rb)** - Automated migration examples
+- **[Rails Controllers](examples/rails_integration/controller_examples.rb)** - Framework integration patterns
+
+## 🧪 Testing
+
+This gem includes a comprehensive test suite with both unit and integration tests.
+
+### Running Tests
+
+```bash
+# Run unit tests only (fast, no database required)
+bundle exec rspec
+
+# Run integration tests (requires PostgreSQL)
+bundle exec rspec --tag integration
+
+# Run all tests
+bundle exec rspec --no-tag
+```
+
+### Test Categories
+
+- **Unit Tests** (65 examples): Fast, isolated component testing
+- **Integration Tests** (21 examples): Real PostgreSQL multi-schema operations
+- **Performance Tests**: Memory usage and thread safety validation
+- **Edge Cases**: Error handling and boundary condition testing
+
+See [Testing Guide](docs/testing.md) for detailed information about the test suite and [Integration Testing Guide](docs/integration_testing.md) for PostgreSQL integration testing details.
+
 ## 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.

data/docs/README.md

@@ -0,0 +1,77 @@
+# PG Multitenant Schemas - Core Architecture Documentation
+
+This directory contains detailed documentation for each core component of the PG Multitenant Schemas gem.
+
+## 📁 Core Components Overview
+
+| Component | Purpose | Documentation |
+|-----------|---------|---------------|
+| **SchemaSwitcher** | Low-level PostgreSQL schema operations | [schema_switcher.md](schema_switcher.md) |
+| **Context** | Thread-safe tenant context management | [context.md](context.md) |
+| **Migrator** | Automated migration management system | [migrator.md](migrator.md) |
+| **Configuration** | Gem configuration and settings | [configuration.md](configuration.md) |
+| **TenantResolver** | Tenant identification and resolution | [tenant_resolver.md](tenant_resolver.md) |
+| **Rails Integration** | Rails framework integration components | [rails_integration.md](rails_integration.md) |
+| **Errors** | Custom exception classes | [errors.md](errors.md) |
+| **Testing** | RSpec test suite and testing guide | [testing.md](testing.md) |
+| **Integration Testing** | PostgreSQL integration testing guide | [integration_testing.md](integration_testing.md) |
+
+## 🏗️ Architecture Flow
+
+```
+HTTP Request
+    ↓
+TenantResolver (identifies tenant)
+    ↓
+Context (sets tenant context)
+    ↓
+SchemaSwitcher (switches PostgreSQL schema)
+    ↓
+Rails Application (executes in tenant schema)
+```
+
+## 🔧 Key Concepts
+
+### Schema-Based Multitenancy
+- Each tenant gets their own PostgreSQL schema
+- Complete data isolation between tenants
+- Shared application code, separate data
+
+### Thread-Safe Context
+- Tenant context is stored per thread
+- Safe for concurrent requests
+- Automatic context restoration
+
+### Automated Migrations
+- Single command migrates all tenant schemas
+- Error handling per tenant
+- Progress tracking and status reporting
+
+## 📖 Getting Started
+
+1. **Read the [Configuration Guide](configuration.md)** to understand setup options
+2. **Explore [Schema Switcher](schema_switcher.md)** for core PostgreSQL operations
+3. **Learn [Context Management](context.md)** for tenant switching
+4. **Master [Migration System](migrator.md)** for database management
+5. **Understand [Rails Integration](rails_integration.md)** for framework features
+6. **Review [Testing Guide](testing.md)** for development and testing practices
+
+## 🧪 Testing and Development
+
+- **[Testing Guide](testing.md)**: Comprehensive RSpec test suite documentation
+- **[Integration Testing](integration_testing.md)**: PostgreSQL integration testing guide
+- **Test Execution**: `bundle exec rspec` (unit tests) and `bundle exec rspec --tag integration` (integration tests)
+
+## 🔍 Debug and Troubleshooting
+
+- Check [Errors Documentation](errors.md) for exception handling
+- Review [TenantResolver](tenant_resolver.md) for tenant identification issues
+- Examine Context state for switching problems
+- Use [Testing Guide](testing.md) for debugging test failures
+
+## 📚 Additional Resources
+
+- [Main README](../README.md) - Getting started guide
+- [CHANGELOG](../CHANGELOG.md) - Version history
+- [Examples](../examples/) - Usage examples
+- [Specs](../spec/) - Test suite