pg_multitenant_schemas 0.1.3 → 0.2.2

data/TESTING_LOCALLY.md

@@ -0,0 +1,208 @@
+# 🚀 Quick Start: Testing GitHub Workflows Locally
+
+This guide gets you up and running quickly with local GitHub Actions testing.
+
+## 🎯 TL;DR - Quick Commands
+
+```bash
+# 1. Run pre-push checks (recommended before every push)
+./pre-push-check.sh
+
+# 2. Test GitHub Actions locally with act
+act -l                    # List all workflows
+act push                  # Test CI workflow
+act pull_request         # Test PR workflow
+
+# 3. Manual component testing
+bundle exec rubocop      # Code style check
+bundle exec rspec        # Run tests
+gem build *.gemspec     # Test gem building
+```
+
+## 🔧 One-Time Setup
+
+### 1. Install act (if not already installed)
+
+```bash
+# macOS
+brew install act
+
+# Linux
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows
+choco install act-cli
+```
+
+### 2. Create local environment file
+
+```bash
+# Copy the example and fill in your values
+cp .env.local.example .env.local
+
+# Edit with your actual tokens (optional, only needed for release testing)
+nano .env.local
+```
+
+## 🧪 Testing Strategies
+
+### Strategy 1: Pre-Push Script (Recommended)
+
+Run this before every push:
+
+```bash
+./pre-push-check.sh
+```
+
+This runs:
+- ✅ RuboCop (code style)
+- ✅ RSpec (unit tests)  
+- ✅ Security audit
+- ✅ Gem build test
+- ✅ Integration tests (if PostgreSQL available)
+
+### Strategy 2: act - GitHub Actions Locally
+
+```bash
+# Test the main CI workflow
+act push
+
+# Test pull request workflow
+act pull_request
+
+# Dry run (see what would execute)
+act -n
+
+# Test specific job
+act -j test
+
+# List all available workflows and jobs
+act -l
+```
+
+### Strategy 3: Manual Component Testing
+
+```bash
+# Test each component individually
+bundle install
+bundle exec rubocop
+bundle exec rspec
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'  # Unit tests only
+bundle exec rspec --tag integration  # Integration tests only
+bundle audit
+gem build pg_multitenant_schemas.gemspec
+```
+
+## 🎯 Workflow-Specific Testing
+
+### Testing CI Workflow (.github/workflows/main.yml)
+
+```bash
+# With act
+act push
+
+# Manual simulation
+bundle install
+bundle exec rubocop
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'
+bundle audit
+```
+
+### Testing Release Workflow (.github/workflows/release.yml)
+
+```bash
+# With act (simulates main branch push)
+act push --env GITHUB_REF=refs/heads/main
+
+# Manual simulation (WITHOUT publishing)
+# 1. Update version in lib/pg_multitenant_schemas/version.rb
+# 2. Build gem locally
+gem build pg_multitenant_schemas.gemspec
+# 3. Check gem contents
+gem contents pg_multitenant_schemas-*.gem
+```
+
+## 🐛 Troubleshooting
+
+### act Issues
+
+```bash
+# Docker not running
+# → Start Docker Desktop
+
+# Permission denied
+# → Fix Docker permissions or use sudo
+
+# Platform issues
+act --container-architecture linux/amd64
+
+# Secrets not found
+# → Check .env.local file exists and has correct values
+```
+
+### PostgreSQL Issues
+
+```bash
+# Check if PostgreSQL is running
+pg_isready
+
+# Start PostgreSQL (macOS)
+brew services start postgresql@15
+
+# Create test database
+createdb pg_multitenant_test
+```
+
+### Ruby/Bundle Issues
+
+```bash
+# Install correct Ruby version
+rbenv install 3.3.0
+rbenv local 3.3.0
+
+# Clean and reinstall gems
+bundle clean --force
+bundle install
+```
+
+## 🔄 Typical Workflow
+
+1. **Make changes** to your code
+2. **Run pre-push checks**: `./pre-push-check.sh`
+3. **Fix any issues** found
+4. **Test with act** (optional): `act push`
+5. **Commit and push** when everything passes
+
+## 📋 Integration with Git
+
+Add to `.git/hooks/pre-push` to run checks automatically:
+
+```bash
+#!/bin/bash
+./pre-push-check.sh
+```
+
+Make it executable:
+```bash
+chmod +x .git/hooks/pre-push
+```
+
+## 🎉 Success Indicators
+
+You're ready to push when you see:
+
+- ✅ Pre-push script passes all checks
+- ✅ `act push` completes without errors
+- ✅ All tests pass locally
+- ✅ RuboCop shows no violations
+- ✅ Gem builds successfully
+
+## 🔗 More Information
+
+- [Complete Guide](docs/local_workflow_testing.md) - Detailed documentation
+- [GitHub Actions Docs](https://docs.github.com/en/actions)
+- [act Documentation](https://github.com/nektos/act)
+
+---
+
+**💡 Pro Tip**: Run `./pre-push-check.sh` before every commit to catch issues early!

data/docs/README.md

@@ -0,0 +1,81 @@
+# 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) |
+| **CI/CD & Releases** | GitHub Actions automation setup | [github_actions_setup.md](github_actions_setup.md) |
+| **Local Workflow Testing** | Test GitHub Actions locally before push | [local_workflow_testing.md](local_workflow_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
+- **[Local Workflow Testing](local_workflow_testing.md)**: Test GitHub Actions locally before push
+- **Test Execution**: `bundle exec rspec` (unit tests) and `bundle exec rspec --tag integration` (integration tests)
+- **Pre-Push Testing**: `./pre-push-check.sh` (validates CI components locally)
+
+## 🔍 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

data/docs/configuration.md

@@ -0,0 +1,340 @@
+# Configuration - Gem Settings and Options
+
+**File**: `lib/pg_multitenant_schemas/configuration.rb`
+
+## 📋 Overview
+
+The `Configuration` class manages all configurable aspects of the PG Multitenant Schemas gem. It provides a centralized way to customize behavior, set defaults, and integrate with different Rails applications.
+
+## 🎯 Purpose
+
+- **Centralized Settings**: Single location for all gem configuration
+- **Framework Integration**: Seamless Rails integration options
+- **Customization**: Flexible options for different deployment scenarios
+- **Defaults Management**: Sensible defaults with override capabilities
+
+## 🔧 Configuration Options
+
+### Core Settings
+
+```ruby
+PgMultitenantSchemas.configure do |config|
+  # Default schema to use (usually 'public')
+  config.default_schema = 'public'
+  
+  # ActiveRecord connection class
+  config.connection_class = 'ApplicationRecord'
+  
+  # Tenant model class name
+  config.tenant_model = 'Tenant'
+  
+  # Schema naming strategy
+  config.schema_prefix = nil  # No prefix by default
+end
+```
+
+### Connection Management
+
+```ruby
+PgMultitenantSchemas.configure do |config|
+  # Connection class for database operations
+  config.connection_class = 'ApplicationRecord'  # Default
+  # config.connection_class = 'TenantRecord'     # Custom connection
+  # config.connection_class = 'ReadOnlyRecord'   # Read-only operations
+end
+```
+
+### Tenant Resolution
+
+```ruby
+PgMultitenantSchemas.configure do |config|
+  # Model used for tenant lookup
+  config.tenant_model = 'Tenant'  # Default
+  # config.tenant_model = 'Organization'
+  # config.tenant_model = 'Account'
+  
+  # Attribute used for schema naming
+  config.tenant_schema_attribute = :subdomain  # Default
+  # config.tenant_schema_attribute = :slug
+  # config.tenant_schema_attribute = :code
+end
+```
+
+### Schema Management
+
+```ruby
+PgMultitenantSchemas.configure do |config|
+  # Default schema for non-tenant operations
+  config.default_schema = 'public'
+  
+  # Schema naming prefix (optional)
+  config.schema_prefix = 'tenant_'  # Results in 'tenant_acme', 'tenant_beta'
+  # config.schema_prefix = nil       # Results in 'acme', 'beta'
+  
+  # Schema exclusion patterns
+  config.excluded_schemas = ['information_schema', 'pg_catalog', 'pg_toast']
+end
+```
+
+## 🏗️ Implementation Details
+
+### Configuration Class Structure
+
+```ruby
+module PgMultitenantSchemas
+  class Configuration
+    attr_accessor :default_schema,
+                  :connection_class,
+                  :tenant_model,
+                  :tenant_schema_attribute,
+                  :schema_prefix,
+                  :excluded_schemas
+
+    def initialize
+      @default_schema = 'public'
+      @connection_class = 'ApplicationRecord'
+      @tenant_model = 'Tenant'
+      @tenant_schema_attribute = :subdomain
+      @schema_prefix = nil
+      @excluded_schemas = default_excluded_schemas
+    end
+  end
+end
+```
+
+### Dynamic Configuration Loading
+
+The configuration supports dynamic loading and environment-specific settings:
+
+```ruby
+# Load from environment variables
+config.default_schema = ENV['PG_MULTITENANT_DEFAULT_SCHEMA'] || 'public'
+
+# Environment-specific configuration
+if Rails.env.development?
+  config.schema_prefix = 'dev_'
+elsif Rails.env.test?
+  config.schema_prefix = 'test_'
+end
+```
+
+## 🔄 Usage Patterns
+
+### Basic Configuration
+
+```ruby
+# config/initializers/pg_multitenant_schemas.rb
+PgMultitenantSchemas.configure do |config|
+  config.default_schema = 'public'
+  config.tenant_model = 'Organization'
+  config.connection_class = 'ApplicationRecord'
+end
+```
+
+### Advanced Configuration
+
+```ruby
+# config/initializers/pg_multitenant_schemas.rb
+PgMultitenantSchemas.configure do |config|
+  # Core settings
+  config.default_schema = 'shared'
+  config.tenant_model = 'Account'
+  config.tenant_schema_attribute = :slug
+  
+  # Schema naming
+  config.schema_prefix = Rails.env.production? ? nil : "#{Rails.env}_"
+  
+  # Connection management
+  config.connection_class = 'TenantRecord'
+  
+  # Exclusions
+  config.excluded_schemas += ['analytics', 'logs']
+end
+```
+
+### Environment-Specific Configuration
+
+```ruby
+# config/initializers/pg_multitenant_schemas.rb
+PgMultitenantSchemas.configure do |config|
+  case Rails.env
+  when 'development'
+    config.schema_prefix = 'dev_'
+    config.default_schema = 'dev_public'
+  when 'test'
+    config.schema_prefix = 'test_'
+    config.default_schema = 'test_public'
+  when 'staging'
+    config.schema_prefix = 'staging_'
+    config.default_schema = 'public'
+  when 'production'
+    config.schema_prefix = nil
+    config.default_schema = 'public'
+  end
+end
+```
+
+## 🎛️ Configuration Validation
+
+The gem includes configuration validation to catch common issues:
+
+```ruby
+def validate_configuration!
+  raise ConfigurationError, "tenant_model must be defined" if tenant_model.blank?
+  raise ConfigurationError, "default_schema cannot be blank" if default_schema.blank?
+  
+  # Validate tenant model exists
+  begin
+    tenant_model.constantize
+  rescue NameError
+    raise ConfigurationError, "Tenant model '#{tenant_model}' not found"
+  end
+  
+  # Validate connection class
+  begin
+    connection_class.constantize
+  rescue NameError
+    raise ConfigurationError, "Connection class '#{connection_class}' not found"
+  end
+end
+```
+
+## 🔧 Integration Examples
+
+### Custom Tenant Models
+
+```ruby
+# For custom tenant model structure
+class Organization < ApplicationRecord
+  has_many :users
+  
+  def schema_name
+    "org_#{slug}"
+  end
+end
+
+# Configuration
+PgMultitenantSchemas.configure do |config|
+  config.tenant_model = 'Organization'
+  config.tenant_schema_attribute = :schema_name
+end
+```
+
+### Multiple Database Setup
+
+```ruby
+# For applications with multiple databases
+class TenantRecord < ApplicationRecord
+  connects_to database: { writing: :tenant_primary, reading: :tenant_replica }
+end
+
+PgMultitenantSchemas.configure do |config|
+  config.connection_class = 'TenantRecord'
+end
+```
+
+### Custom Schema Naming
+
+```ruby
+# Custom schema naming logic
+module SchemaNameBuilder
+  def self.build_name(tenant)
+    case tenant.tier
+    when 'enterprise'
+      "ent_#{tenant.slug}"
+    when 'premium'
+      "prem_#{tenant.slug}"
+    else
+      "std_#{tenant.slug}"
+    end
+  end
+end
+
+PgMultitenantSchemas.configure do |config|
+  config.schema_name_builder = SchemaNameBuilder
+end
+```
+
+## 🚨 Important Considerations
+
+### Configuration Timing
+
+- Configure the gem **before** Rails application initialization
+- Place configuration in `config/initializers/`
+- Ensure configuration runs before model loading
+
+### Thread Safety
+
+- Configuration is **read-only** after initialization
+- Safe to access from multiple threads
+- No runtime configuration changes supported
+
+### Performance Impact
+
+- Configuration lookups are fast (cached)
+- No database queries for configuration access
+- Minimal memory overhead
+
+## 🔍 Configuration Debugging
+
+### Check Current Configuration
+
+```ruby
+# Display current configuration
+config = PgMultitenantSchemas.configuration
+puts "Default Schema: #{config.default_schema}"
+puts "Tenant Model: #{config.tenant_model}"
+puts "Connection Class: #{config.connection_class}"
+puts "Schema Prefix: #{config.schema_prefix}"
+```
+
+### Validate Configuration
+
+```ruby
+# Validate configuration is correct
+begin
+  PgMultitenantSchemas.configuration.validate_configuration!
+  puts "✅ Configuration is valid"
+rescue PgMultitenantSchemas::ConfigurationError => e
+  puts "❌ Configuration error: #{e.message}"
+end
+```
+
+## 🔗 Related Components
+
+- **[Context](context.md)**: Uses configuration for default schema
+- **[SchemaSwitcher](schema_switcher.md)**: Uses connection class configuration
+- **[TenantResolver](tenant_resolver.md)**: Uses tenant model configuration
+- **[Rails Integration](rails_integration.md)**: Framework-specific configuration
+
+## 📝 Configuration Templates
+
+### Standard Rails App
+```ruby
+PgMultitenantSchemas.configure do |config|
+  config.default_schema = 'public'
+  config.tenant_model = 'Tenant'
+  config.connection_class = 'ApplicationRecord'
+end
+```
+
+### SaaS Application
+```ruby
+PgMultitenantSchemas.configure do |config|
+  config.default_schema = 'shared'
+  config.tenant_model = 'Account'
+  config.tenant_schema_attribute = :subdomain
+  config.schema_prefix = Rails.env.production? ? nil : "#{Rails.env}_"
+end
+```
+
+### Enterprise Application
+```ruby
+PgMultitenantSchemas.configure do |config|
+  config.default_schema = 'master'
+  config.tenant_model = 'Organization'
+  config.tenant_schema_attribute = :schema_name
+  config.connection_class = 'TenantRecord'
+  config.excluded_schemas += ['audit', 'analytics', 'logs']
+end
+```