pg_multitenant_schemas 0.1.3 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e4486368a3eff30c0b78d763ea5240a9c53290124bc9c86db5a95d758097543
-  data.tar.gz: 652ec19727ac61cb61306c50cf7cff6bc2813b35c849419299f3c07f70239e49
+  metadata.gz: 4523327235e126955f182413b00ecab417f260daf3b0ed550ece95bc1da7a8bf
+  data.tar.gz: 4f277b6139588035c3d04befb30b475ad55fd7a199d582e7728aed15757dcc7c
 SHA512:
-  metadata.gz: c1b96e168c0e3a6c9e80fea6d842aa8fd02e1d002681d6a075b7c90a2d2974dce0f2891a17f8b1081db10a48932b096db1152d1a7c55efe860f19ac80eea8068
-  data.tar.gz: bbfaa928d0bbbe90bc03eddf06ab1467e072db15f2ac43522bd932eb1a2ea9fdc489a03aeb549a25480686c0854106c2e5cb1ffe5f3c7806ca0c73b991b07679
+  metadata.gz: a454ee397a247ea820b89590c0e9c8d10f63e83507f4b989b27780b8721c99b5191fe9048f7cf378d9388371650524b48adcf4a4ec58c2566aa2e0afdfb66929
+  data.tar.gz: 6adc8a9a67ff69b2e045982ff85a48f045a683614bb548343bc64e78062c01b191e5e70984c8ed3dd110696bd556f51def524dd2619f1a5d20cd43f3eeafcb9a

data/.actrc

@@ -0,0 +1,17 @@
+# act configuration file
+# This configures act to run GitHub Actions locally
+
+# Use Linux AMD64 architecture for compatibility
+--container-architecture linux/amd64
+
+# Set artifact server path
+--artifact-server-path /tmp/act-artifacts
+
+# Load environment variables from local file
+--env-file .env.local
+
+# Use medium size runner image
+--platform ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Show more verbose output
+--verbose

data/.env.local.example

@@ -0,0 +1,21 @@
+# Local environment variables for testing with act
+# Copy this to .env.local and fill in your actual values
+
+# GitHub token (create at https://github.com/settings/tokens)
+# Needs repo and workflow permissions
+GITHUB_TOKEN=your_github_token_here
+
+# RubyGems API key (get from https://rubygems.org/profile/edit)
+# Only needed for testing release workflow
+RUBYGEMS_API_KEY=your_rubygems_api_key_here
+
+# Repository information
+GITHUB_REPOSITORY=rubenpazch/pg_multitenant_schemas
+GITHUB_ACTOR=your_github_username
+
+# PostgreSQL configuration for local testing
+PGDATABASE=pg_multitenant_test
+PGUSER=postgres
+PGPASSWORD=
+PGHOST=localhost
+PGPORT=5432

data/.ruby-version

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

data/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2025-09-07
+
+### 🔧 **Developer Experience & Testing**
+- **NEW: Local Workflow Testing**: Complete solution for testing GitHub Actions locally before push
+- **NEW: Pre-Push Validation**: `pre-push-check.sh` script validates CI components locally  
+- **NEW: GitHub Actions Testing**: `act` tool integration with configuration files
+- **NEW: Validation Scripts**: `validate-github-commands.sh` and `test-github-setup.sh`
+
+### 🚀 **CI/CD Improvements**
+- **FIXED: GitHub Actions Permissions**: Resolved permission issues with release workflow
+- **FIXED: RSpec Command**: Corrected `--exclude-pattern` usage for unit test isolation
+- **IMPROVED: Release Automation**: Enhanced release workflow with proper bot identity
+- **IMPROVED: Documentation**: Comprehensive guides for CI/CD setup and troubleshooting
+
+### 📚 **Documentation Enhancements**
+- **NEW: Local Testing Guide**: `TESTING_LOCALLY.md` and `LOCAL_TESTING_SUMMARY.md`
+- **NEW: CI/CD Setup Guide**: `docs/github_actions_setup.md` with step-by-step instructions
+- **NEW: Permissions Fix Guide**: `docs/github_actions_permissions_fix.md`
+- **NEW: Workflow Testing Guide**: `docs/local_workflow_testing.md`
+- **IMPROVED: Core Documentation**: Updated `docs/README.md` with local testing references
+
+### 🧪 **Testing Infrastructure**
+- **ENHANCED: RuboCop Compliance**: Fixed all code style violations across test suite
+- **ENHANCED: Test Organization**: Improved test structure and mocking patterns
+- **ENHANCED: Integration Testing**: Better PostgreSQL integration test support
+- **ENHANCED: Security Auditing**: Bundle audit integration in CI pipeline
+
+### 🔧 **Configuration Files**
+- **NEW: `.actrc`**: Configuration for local GitHub Actions testing
+- **NEW: `.env.local.example`**: Template for local environment variables
+- **IMPROVED: `.gitignore`**: Added local testing files to ignore list
+
+## [0.2.1] - 2025-09-06
+
+### 🚀 **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
@@ -48,3 +128,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial release
 - Basic schema switching functionality
 - PostgreSQL multitenancy support
+
+[Unreleased]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/rubenpazch/pg_multitenant_schemas/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/rubenpazch/pg_multitenant_schemas/releases/tag/v0.1.0

data/LOCAL_TESTING_SUMMARY.md

@@ -0,0 +1,141 @@
+# 🧪 Summary: How to Test GitHub Workflows Locally
+
+## ✅ What You Can Do Right Now
+
+### 1. **Pre-Push Script (Recommended)**## 📁 **Files Created**
+
+- **`pre-push-check.sh`** - Main testing script
+- **`validate-github-commands.sh`** - Test exact GitHub Actions commands
+- **`TESTING_LOCALLY.md`** - Quick start guide
+- **`docs/local_workflow_testing.md`** - Complete documentation
+- **`.actrc`** - act configuration
+- **`.env.local.example`** - Environment templateh
+# Run this before every push
+./pre-push-check.sh
+```
+This validates everything that runs in CI:
+- ✅ RuboCop (code style)
+- ✅ RSpec (tests)
+- ✅ Bundle audit (security)
+- ✅ Gem building
+- ✅ Integration tests (if PostgreSQL available)
+
+### 2. **Manual Component Testing**
+```bash
+```bash
+# Test each CI component individually
+bundle install
+bundle exec rubocop              # Code style check
+bundle exec rspec               # Run all tests
+bundle exec rspec --tag integration  # Integration tests only
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'  # Unit tests only
+bundle audit                    # Security audit
+gem build pg_multitenant_schemas.gemspec  # Test gem build
+```
+```
+
+### 3. **act Tool (Partial Support)**
+```bash
+# List workflows
+act -l
+
+# Dry run (shows what would execute)
+act -n push
+
+# Note: Currently has issues with PostgreSQL services
+# Better for simple workflows without database dependencies
+```
+
+## 🎯 **Before Every Push Checklist**
+
+1. ✅ Run `./pre-push-check.sh`
+2. ✅ Fix any issues found
+3. ✅ Commit your changes
+4. ✅ Push to GitHub
+
+## 📋 **Component Status**
+
+| Component | Local Testing | Status |
+|-----------|---------------|---------|
+| RuboCop | ✅ `bundle exec rubocop` | Working |
+| Unit Tests | ✅ `bundle exec rspec` | Working |
+| Integration Tests | ✅ With local PostgreSQL | Working |
+| Security Audit | ✅ `bundle audit` | Working |
+| Gem Building | ✅ `gem build *.gemspec` | Working |
+| Release Workflow | ⚠️ Manual simulation only | Partial |
+| Full CI with act | ⚠️ PostgreSQL service issues | Limited |
+
+## 🔧 **Quick Setup**
+
+1. **Make pre-push script executable:**
+   ```bash
+   chmod +x pre-push-check.sh
+   ```
+
+2. **Install act (optional):**
+   ```bash
+   brew install act
+   ```
+
+3. **Create environment file (for act):**
+   ```bash
+   cp .env.local.example .env.local
+   # Edit .env.local with your tokens if needed
+   ```
+
+## 🚀 **Recommended Workflow**
+
+```bash
+# 1. Make your changes
+git add .
+
+# 2. Test locally
+./pre-push-check.sh
+
+# 3. If all passes, commit and push
+git commit -m "Your changes"
+git push
+```
+
+## 🛠️ **Troubleshooting**
+
+### 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 Issues
+```bash
+# Install correct Ruby version
+rbenv install 3.3.0
+rbenv local 3.3.0
+bundle install
+```
+
+### act Issues
+```bash
+# Try without services (simpler)
+act -j security  # Just run security audit job
+
+# Check Docker is running
+docker ps
+```
+
+## 📚 **Files Created**
+
+- **`pre-push-check.sh`** - Main testing script
+- **`TESTING_LOCALLY.md`** - Quick start guide
+- **`docs/local_workflow_testing.md`** - Complete documentation
+- **`.actrc`** - act configuration
+- **`.env.local.example`** - Environment template
+
+---
+
+**💡 Bottom Line**: Use `./pre-push-check.sh` for reliable local testing. It covers 95% of what CI does and catches issues early!

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.