pg_multitenant_schemas 0.1.3 → 0.2.2

data/docs/local_workflow_testing.md

@@ -0,0 +1,314 @@
+# Testing GitHub Workflows Locally
+
+This guide shows you how to test GitHub Actions workflows locally before pushing to GitHub.
+
+## 🚀 Method 1: Using `act` (Recommended)
+
+`act` is the most popular tool for running GitHub Actions locally using Docker.
+
+### Installation
+
+```bash
+# macOS (using Homebrew)
+brew install act
+
+# Linux (using curl)
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows (using Chocolatey)
+choco install act-cli
+```
+
+### Basic Usage
+
+```bash
+# List all workflows
+act -l
+
+# Run all workflows
+act
+
+# Run specific workflow
+act push
+
+# Run specific job
+act -j test
+
+# Run with specific event
+act pull_request
+
+# Dry run (show what would be executed)
+act -n
+```
+
+### Testing Our Workflows
+
+```bash
+# Test the main CI workflow
+act push
+
+# Test the release workflow (simulates a push to main)
+act push --env GITHUB_REF=refs/heads/main
+
+# Test pull request workflow
+act pull_request
+```
+
+### Configuration
+
+Create `.actrc` file in project root for default settings:
+
+```bash
+# .actrc
+--container-architecture linux/amd64
+--artifact-server-path /tmp/act-artifacts
+--env-file .env.local
+```
+
+### Environment Variables
+
+Create `.env.local` for local testing:
+
+```bash
+# .env.local
+GITHUB_TOKEN=your_github_token_here
+RUBYGEMS_API_KEY=your_rubygems_key_here
+GITHUB_REPOSITORY=rubenpazch/pg_multitenant_schemas
+GITHUB_ACTOR=your_username
+```
+
+## 🔧 Method 2: Manual Testing Components
+
+### Test RuboCop Locally
+
+```bash
+# Run RuboCop (same as in CI)
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -A
+
+# Check specific files
+bundle exec rubocop lib/ spec/
+```
+
+### Test RSpec Locally
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage (if configured)
+COVERAGE=true bundle exec rspec
+
+# Run integration tests
+bundle exec rspec --tag integration
+
+# Run tests with different Ruby versions (using rbenv/rvm)
+rbenv shell 3.2.0 && bundle exec rspec
+rbenv shell 3.3.0 && bundle exec rspec
+```
+
+### Test Gem Building
+
+```bash
+# Build gem locally
+gem build pg_multitenant_schemas.gemspec
+
+# Install locally built gem
+gem install pg_multitenant_schemas-*.gem
+
+# Test gem installation
+gem list | grep pg_multitenant_schemas
+```
+
+### Test PostgreSQL Setup
+
+```bash
+# Start PostgreSQL (macOS with Homebrew)
+brew services start postgresql@15
+
+# Create test database
+createdb pg_multitenant_test
+
+# Run integration tests
+PGDATABASE=pg_multitenant_test bundle exec rspec --tag integration
+```
+
+## 🐳 Method 3: Docker-based Testing
+
+Create a local testing environment that mirrors CI:
+
+```bash
+# Create Dockerfile.test
+cat > Dockerfile.test << 'EOF'
+FROM ruby:3.3
+
+# Install PostgreSQL client
+RUN apt-get update && apt-get install -y postgresql-client
+
+# Set working directory
+WORKDIR /app
+
+# Copy Gemfile
+COPY Gemfile* ./
+RUN bundle install
+
+# Copy source code
+COPY . .
+
+# Run tests
+CMD ["bundle", "exec", "rspec"]
+EOF
+
+# Build and run
+docker build -f Dockerfile.test -t pg_multitenant_test .
+docker run --rm pg_multitenant_test
+```
+
+## 🔍 Method 4: GitHub CLI for Remote Testing
+
+Use GitHub CLI to trigger workflows manually:
+
+```bash
+# Install GitHub CLI
+brew install gh
+
+# Authenticate
+gh auth login
+
+# Trigger workflow manually
+gh workflow run main.yml
+
+# Check workflow status
+gh run list
+
+# View workflow logs
+gh run view --log
+```
+
+## 📋 Pre-Push Checklist
+
+Before pushing to GitHub, run these commands locally:
+
+```bash
+#!/bin/bash
+# pre-push-check.sh
+
+echo "🔍 Running pre-push checks..."
+
+# 1. RuboCop
+echo "Running RuboCop..."
+bundle exec rubocop || exit 1
+
+# 2. RSpec
+echo "Running RSpec..."
+bundle exec rspec || exit 1
+
+# 3. Security audit
+echo "Running security audit..."
+bundle audit || exit 1
+
+# 4. Gem build test
+echo "Testing gem build..."
+gem build pg_multitenant_schemas.gemspec || exit 1
+
+# 5. Integration tests (if PostgreSQL available)
+if command -v psql &> /dev/null; then
+    echo "Running integration tests..."
+    bundle exec rspec --tag integration || exit 1
+fi
+
+echo "✅ All checks passed! Ready to push."
+```
+
+Make it executable:
+
+```bash
+chmod +x pre-push-check.sh
+./pre-push-check.sh
+```
+
+## 🎯 Specific Workflow Testing
+
+### Testing CI Workflow (main.yml)
+
+```bash
+# Using act
+act push -W .github/workflows/main.yml
+
+```bash
+# Manual simulation
+bundle install
+bundle exec rubocop
+bundle exec rspec --exclude-pattern '**/integration/**/*_spec.rb'
+bundle audit
+```
+```
+
+### Testing Release Workflow (release.yml)
+
+```bash
+# Simulate version bump
+# 1. Update version in lib/pg_multitenant_schemas/version.rb
+# 2. Test locally
+act push -W .github/workflows/release.yml --env GITHUB_REF=refs/heads/main
+
+# Manual simulation (without actual publishing)
+gem build pg_multitenant_schemas.gemspec
+# Note: Don't run 'gem push' in testing
+```
+
+## 🛠️ Troubleshooting
+
+### Common Issues with `act`
+
+1. **Docker not running**: Start Docker Desktop
+2. **Permission issues**: Run with `sudo` or fix Docker permissions
+3. **Platform issues**: Use `--container-architecture linux/amd64`
+4. **Secret errors**: Provide secrets via `.env.local` file
+
+### PostgreSQL Issues
+
+```bash
+# Check if PostgreSQL is running
+pg_isready
+
+# Start PostgreSQL service
+brew services start postgresql@15
+
+# Create test database
+createdb pg_multitenant_test
+```
+
+### Ruby Version Issues
+
+```bash
+# Install required Ruby versions
+rbenv install 3.2.0
+rbenv install 3.3.0
+rbenv install 3.4.0
+
+# Test with specific version
+rbenv shell 3.3.0
+bundle install
+bundle exec rspec
+```
+
+## 📚 Additional Resources
+
+- [act Documentation](https://github.com/nektos/act)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Local Development Best Practices](https://docs.github.com/en/actions/using-workflows/about-workflows#best-practices)
+
+## 🔗 Integration with Git Hooks
+
+Add to `.git/hooks/pre-push`:
+
+```bash
+#!/bin/bash
+./pre-push-check.sh
+exit $?
+```
+
+This ensures checks run automatically before every push.

data/docs/migrator.md

@@ -0,0 +1,291 @@
+# Migrator - Automated Migration Management
+
+**File**: `lib/pg_multitenant_schemas/migrator.rb`
+
+## 📋 Overview
+
+The `Migrator` class provides comprehensive automated migration management for multi-tenant applications. It handles running migrations across all tenant schemas, setting up new tenants, and tracking migration status.
+
+## 🎯 Purpose
+
+- **Bulk Migration**: Run migrations across all tenant schemas with single command
+- **Tenant Setup**: Automated tenant creation with schema and migrations
+- **Status Tracking**: Monitor migration status across all tenants
+- **Error Resilience**: Handle migration failures gracefully per tenant
+- **Progress Reporting**: Detailed feedback during migration operations
+
+## 🔧 Key Methods
+
+### Core Migration Operations
+
+```ruby
+# Migrate all tenant schemas
+Migrator.migrate_all
+
+# Migrate specific tenant
+Migrator.migrate_tenant('acme_corp')
+
+# Check migration status across all tenants
+Migrator.migration_status
+
+# Setup new tenant (create schema + run migrations)
+Migrator.setup_tenant('new_tenant')
+```
+
+### Tenant Management
+
+```ruby
+# Setup all existing tenants
+Migrator.setup_all_tenants
+
+# Create tenant with attributes and schema
+Migrator.create_tenant_with_schema({
+  subdomain: 'acme',
+  name: 'ACME Corporation'
+})
+
+# Rollback specific tenant
+Migrator.rollback_tenant('tenant_name', steps: 2)
+```
+
+## 🏗️ Implementation Details
+
+### Migration Execution Flow
+
+```ruby
+def migrate_all
+  puts "🚀 Starting migration for all tenant schemas..."
+  
+  tenant_schemas.each do |schema|
+    puts "📦 Migrating schema: #{schema}"
+    
+    migrate_tenant(schema)
+  end
+  
+  puts "✅ Migration completed for all schemas"
+end
+```
+
+### Error Handling Strategy
+
+The Migrator implements robust error handling:
+
+- **Per-Tenant Isolation**: Failures in one tenant don't affect others
+- **Detailed Error Reporting**: Specific error messages per tenant
+- **Continue on Error**: Migration continues for remaining tenants
+- **Transaction Safety**: Each tenant migration is self-contained
+
+### Progress Tracking
+
+```ruby
+def migration_status
+  puts "📊 Migration Status Report"
+  
+  tenant_schemas.each do |schema|
+    pending = pending_migrations_for_schema(schema)
+    
+    if pending.empty?
+      puts "▸ #{schema}: ✅ Up to date"
+    else
+      puts "▸ #{schema}: ⚠️  #{pending.count} pending migrations"
+    end
+  end
+end
+```
+
+## 🔄 Usage Patterns
+
+### Daily Operations
+
+```ruby
+# Check what needs migration
+PgMultitenantSchemas::Migrator.migration_status
+
+# Run migrations across all tenants
+PgMultitenantSchemas::Migrator.migrate_all
+
+# Setup new tenant
+PgMultitenantSchemas::Migrator.setup_tenant('new_client')
+```
+
+### Deployment Workflow
+
+```ruby
+# In deployment script
+namespace :deploy do
+  task :migrate_tenants do
+    PgMultitenantSchemas::Migrator.migrate_all
+  end
+end
+```
+
+### New Tenant Onboarding
+
+```ruby
+# Complete tenant setup
+tenant_attributes = {
+  subdomain: 'newco',
+  name: 'New Company Ltd',
+  domain: 'newco.com'
+}
+
+tenant = PgMultitenantSchemas::Migrator.create_tenant_with_schema(tenant_attributes)
+puts "✅ Tenant #{tenant.subdomain} ready for use"
+```
+
+### Rollback Operations
+
+```ruby
+# Rollback specific tenant
+PgMultitenantSchemas::Migrator.rollback_tenant('acme_corp', steps: 1)
+
+# Check status after rollback
+PgMultitenantSchemas::Migrator.migration_status
+```
+
+## 🎛️ Configuration Integration
+
+The Migrator respects global configuration:
+
+```ruby
+PgMultitenantSchemas.configure do |config|
+  config.default_schema = 'public'
+  config.tenant_model = 'Tenant'
+  config.connection_class = 'ApplicationRecord'
+end
+```
+
+## 📊 Status Reporting
+
+### Migration Status Output
+
+```
+📊 Migration Status Report
+▸ acme_corp: ✅ Up to date (5 migrations)
+▸ beta_corp: ⚠️  2 pending migrations
+  - 20241201120000_add_feature_flags
+  - 20241202100000_update_user_fields
+▸ demo_corp: ✅ Up to date (5 migrations)
+
+📈 Overall: 2/3 tenants current, 2 migrations pending
+```
+
+### Migration Progress Output
+
+```
+🚀 Starting migration for all tenant schemas...
+
+📦 Migrating schema: acme_corp
+  ✓ Running migration 20241201120000_add_feature_flags
+  ✓ Running migration 20241202100000_update_user_fields
+  ✅ Completed migration for acme_corp
+
+📦 Migrating schema: beta_corp
+  ✓ Running migration 20241201120000_add_feature_flags
+  ✗ Error in migration 20241202100000_update_user_fields: column already exists
+  ⚠️  Continuing with next tenant...
+
+✅ Migration completed for all schemas
+📊 Summary: 1/2 tenants migrated successfully
+```
+
+## 🔍 Advanced Features
+
+### Custom Migration Paths
+
+```ruby
+# Override migration paths if needed
+class CustomMigrator < PgMultitenantSchemas::Migrator
+  private
+  
+  def migration_paths
+    [
+      Rails.root.join('db', 'migrate'),
+      Rails.root.join('db', 'tenant_migrations')
+    ]
+  end
+end
+```
+
+### Migration Callbacks
+
+```ruby
+# Add hooks for migration events
+module MigrationHooks
+  def self.before_tenant_migration(schema_name)
+    Rails.logger.info "Starting migration for #{schema_name}"
+  end
+  
+  def self.after_tenant_migration(schema_name, success)
+    status = success ? "SUCCESS" : "FAILED"
+    Rails.logger.info "Migration for #{schema_name}: #{status}"
+  end
+end
+```
+
+### Batch Processing
+
+```ruby
+# Process tenants in batches for large installations
+def migrate_all_batched(batch_size: 10)
+  tenant_schemas.each_slice(batch_size) do |batch|
+    batch.each { |schema| migrate_tenant(schema) }
+    sleep(1)  # Brief pause between batches
+  end
+end
+```
+
+## 🚨 Important Considerations
+
+### Performance
+
+- **Parallel Processing**: Consider parallelization for large tenant counts
+- **Resource Usage**: Monitor database connections during bulk operations
+- **Timing**: Run during low-traffic periods for production
+
+### Data Integrity
+
+- **Backup Strategy**: Ensure proper backups before major migrations
+- **Testing**: Test migrations on staging environment with production data
+- **Rollback Plan**: Have rollback procedures for failed migrations
+
+### Monitoring
+
+- **Log Analysis**: Monitor migration logs for patterns and issues
+- **Alert Setup**: Set up alerts for migration failures
+- **Performance Metrics**: Track migration duration and resource usage
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**Migration Stuck**
+```ruby
+# Check for long-running queries
+ActiveRecord::Base.connection.execute("SELECT * FROM pg_stat_activity WHERE state = 'active'")
+```
+
+**Schema Not Found**
+```ruby
+# Verify schema exists
+if !PgMultitenantSchemas::SchemaSwitcher.schema_exists?('tenant_name')
+  PgMultitenantSchemas::Migrator.setup_tenant('tenant_name')
+end
+```
+
+**Permission Errors**
+```ruby
+# Check database permissions
+ActiveRecord::Base.connection.execute("SELECT has_schema_privilege('tenant_schema', 'USAGE')")
+```
+
+## 🔗 Related Components
+
+- **[SchemaSwitcher](schema_switcher.md)**: Core schema operations used by Migrator
+- **[Context](context.md)**: Tenant context management during migrations
+- **[Configuration](configuration.md)**: Migrator configuration options
+- **[Rails Integration](rails_integration.md)**: Framework integration features
+
+## 📝 Examples
+
+See [examples/migration_workflow.rb](../examples/) for complete usage examples and [rake tasks documentation](../lib/pg_multitenant_schemas/tasks/) for command-line usage.