pg_multitenant_schemas 0.2.0 → 0.2.3

data/docs/github_actions_setup.md

@@ -0,0 +1,181 @@
+# GitHub Actions Setup Guide
+
+This document explains how to set up GitHub Actions for automated testing and releases.
+
+## Overview
+
+The repository uses two main workflows:
+
+1. **CI Workflow** (`.github/workflows/main.yml`) - Runs tests on every push and PR
+2. **Release Workflow** (`.github/workflows/release.yml`) - Automatically releases to RubyGems when version changes
+
+## Setting Up RubyGems API Key
+
+To enable automatic releases to RubyGems, you need to set up a GitHub secret with your RubyGems API key.
+
+### Step 1: Get Your RubyGems API Key
+
+1. Go to [RubyGems.org](https://rubygems.org/)
+2. Sign in to your account
+3. Go to your profile settings
+4. Navigate to "API Keys" section
+5. Create a new API key or use an existing one
+6. Copy the API key (it should start with `rubygems_`)
+
+### Step 2: Add GitHub Secret
+
+1. Go to your GitHub repository
+2. Click on "Settings" tab
+3. In the left sidebar, click "Secrets and variables" → "Actions"
+4. Click "New repository secret"
+5. Name: `RUBYGEMS_API_KEY`
+6. Value: Paste your RubyGems API key
+7. Click "Add secret"
+
+### 3. Configure Repository Permissions
+
+**Important:** Configure GitHub Actions permissions to allow the release workflow to create tags and releases:
+
+1. Go to your repository Settings
+2. Navigate to **Actions > General**
+3. Under "Workflow permissions":
+   - Select **"Read and write permissions"**
+   - Check **"Allow GitHub Actions to create and approve pull requests"**
+4. Click **Save**
+
+Without these permissions, you'll get errors like:
+```
+remote: Permission to username/repo.git denied to github-actions[bot].
+fatal: unable to access 'https://github.com/username/repo/': The requested URL returned error: 403
+```
+
+## How the Workflows Work
+
+### CI Workflow
+
+**Triggers:**
+- Every push to `main` branch
+- Every pull request to `main` branch
+
+**What it does:**
+- Tests on Ruby 3.2, 3.3, and 3.4
+- Runs RuboCop for code quality
+- Runs unit tests (excluding integration tests)
+- Runs integration tests (with PostgreSQL database)
+- Runs security audit with bundle-audit
+
+### Release Workflow
+
+**Triggers:**
+- Push to `main` branch that changes `lib/pg_multitenant_schemas/version.rb`
+
+**What it does:**
+- Checks if the version in `version.rb` has changed
+- If version changed:
+  1. Builds the gem
+  2. Creates a Git tag (e.g., `v0.2.1`)
+  3. Creates a GitHub release with changelog notes
+  4. Publishes the gem to RubyGems
+
+## Release Process
+
+To release a new version:
+
+1. **Update the version** in `lib/pg_multitenant_schemas/version.rb`:
+   ```ruby
+   module PgMultitenantSchemas
+     VERSION = "0.2.1"  # Increment this
+   end
+   ```
+
+2. **Update the changelog** in `CHANGELOG.md`:
+   ```markdown
+   ## [0.2.1] - 2025-09-07
+   
+   ### Added
+   - New feature description
+   
+   ### Fixed
+   - Bug fix description
+   ```
+
+3. **Commit and push** to main branch:
+   ```bash
+   git add lib/pg_multitenant_schemas/version.rb CHANGELOG.md
+   git commit -m "Bump version to 0.2.1"
+   git push origin main
+   ```
+
+4. **Automatic release** will trigger:
+   - GitHub Actions will detect the version change
+   - Create a Git tag and GitHub release
+   - Publish to RubyGems automatically
+
+## Manual Release (Alternative)
+
+If you prefer manual releases or need to troubleshoot:
+
+```bash
+# Build the gem
+gem build pg_multitenant_schemas.gemspec
+
+# Push to RubyGems (requires authentication)
+gem push pg_multitenant_schemas-0.2.1.gem
+
+# Create Git tag
+git tag v0.2.1
+git push origin v0.2.1
+```
+
+## Workflow Status
+
+You can monitor workflow runs:
+
+1. Go to your GitHub repository
+2. Click the "Actions" tab
+3. View running and completed workflows
+4. Click on individual runs to see detailed logs
+
+## Security Considerations
+
+- **API Keys**: Never commit API keys to the repository
+- **Secrets**: Use GitHub Secrets for sensitive information
+- **Permissions**: The `GITHUB_TOKEN` has limited permissions for creating releases
+- **Audit**: The security workflow checks for vulnerable dependencies
+
+## Troubleshooting
+
+### Common Issues
+
+1. **RubyGems authentication failed**
+   - Check that `RUBYGEMS_API_KEY` secret is set correctly
+   - Ensure the API key has publishing permissions
+
+2. **Git tag already exists**
+   - The workflow checks for existing tags
+   - If tag exists, release is skipped
+
+3. **Tests failing**
+   - CI must pass before release workflow runs
+   - Check test logs in the Actions tab
+
+4. **PostgreSQL connection issues**
+   - Integration tests require PostgreSQL service
+   - Check service configuration in workflow
+
+### Debug Steps
+
+1. Check workflow logs in GitHub Actions
+2. Verify secrets are set correctly
+3. Test locally with same Ruby versions
+4. Check RubyGems.org for published gems
+
+## Best Practices
+
+1. **Version Bumping**: Use semantic versioning (MAJOR.MINOR.PATCH)
+2. **Changelog**: Always update changelog before releasing
+3. **Testing**: Ensure all tests pass locally before pushing
+4. **Security**: Regularly update dependencies and run security audits
+5. **Documentation**: Update documentation for breaking changes
+
+This automated setup ensures consistent, reliable releases while maintaining code quality through comprehensive testing.

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/testing_rails_tasks.md

@@ -0,0 +1,128 @@
+# 🧪 Testing Rails Tasks in PG Multitenant Schemas
+
+## 🚨 Important: Testing Context
+
+The `rails tenants:list` command only works **within a Rails application** that includes this gem, not in the gem directory itself.
+
+## 🔧 Fixed Issues
+
+✅ **Removed circular dependency** in rake task loading
+✅ **Eliminated duplicate task files** (`pg_multitenant_schemas.rake` was identical to `tenant_tasks.rake`)
+✅ **Updated railtie** to load all task files properly
+✅ **Added missing `list_schemas` method** to `SchemaSwitcher` class
+✅ **Fixed Rails 8 migration_context compatibility** - Updated migration handling for Rails 8
+
+## 🚀 How to Test the Rails Tasks
+
+### **Option 1: Create a Test Rails App**
+
+```bash
+# Create a new Rails app for testing
+rails new test_multitenancy --database=postgresql
+cd test_multitenancy
+
+# Add the gem to Gemfile
+echo 'gem "pg_multitenant_schemas", path: "/Users/rubenpaz/personal/pg_multitenant_schemas"' >> Gemfile
+
+# Install the gem
+bundle install
+
+# Now you can test the tasks
+rails tenants:list
+rails tenants:status
+rails tenants:migrate
+```
+
+### **Option 2: Use an Existing Rails App**
+
+```bash
+# Navigate to your existing Rails app
+cd /Users/rubenpaz/personal/lbyte-security  # or wherever your Rails app is
+
+# Add gem to Gemfile if not already added
+# gem "pg_multitenant_schemas", path: "/Users/rubenpaz/personal/pg_multitenant_schemas"
+
+# Install and test
+bundle install
+rails tenants:list
+```
+
+### **Option 3: Test in the Example Directory**
+
+```bash
+# If there's a Rails example in the gem
+cd /Users/rubenpaz/personal/pg_multitenant_schemas/examples
+# Follow instructions in that directory
+```
+
+## 📋 Available Tasks
+
+After including the gem in a Rails app, you'll have these tasks:
+
+### **Basic Tasks**
+- `rails tenants:list` - List all tenant schemas
+- `rails tenants:status` - Show migration status for all tenants  
+- `rails tenants:migrate` - Run migrations for all tenant schemas
+
+### **Advanced Tasks**  
+- `rails tenants:migrate_tenant[schema_name]` - Run migrations for specific tenant
+- `rails tenants:create[schema_name]` - Setup new tenant with schema and migrations
+- `rails tenants:setup` - Setup schemas and run migrations for all existing tenants
+
+### **Management Tasks**
+- `rails tenants:new[attributes]` - Create new tenant with attributes (JSON format)
+- `rails tenants:drop[schema_name]` - Drop tenant schema (DANGEROUS)
+- `rails tenants:rollback[schema_name,steps]` - Rollback migrations for a tenant
+
+### **Convenience Aliases**
+- `rails tenants:db:create[schema_name]` - Alias for `tenants:create`
+- `rails tenants:db:migrate` - Alias for `tenants:migrate`
+- `rails tenants:db:status` - Alias for `tenants:status`
+
+### **Legacy Tasks (Deprecated)**
+- `rails pg_multitenant_schemas:list_schemas` - Use `tenants:list` instead
+- `rails pg_multitenant_schemas:migrate_all` - Use `tenants:migrate` instead
+
+## 🛠️ Troubleshooting
+
+### "Command not found" or "stack level too deep"
+- ✅ **Fixed**: Circular dependency in task loading removed
+- Make sure you're in a Rails application directory
+- Run `bundle install` after adding the gem
+
+### "NoMethodError: undefined method 'list_schemas'"  
+- ✅ **Fixed**: Added missing `list_schemas` method to `SchemaSwitcher`
+- Update to the latest version of the gem
+
+### "NoMethodError: undefined method 'migration_context'"
+- ✅ **Fixed**: Updated migration handling for Rails 8 compatibility
+- The gem now properly handles migration context access across Rails versions
+- Update to the latest version of the gem
+
+### "No such task"
+- Ensure the gem is properly added to your Rails app's Gemfile
+- Run `bundle install`
+- Check that the gem is loading: `rails runner "puts PgMultitenantSchemas::VERSION"`
+
+### "Environment not loaded"
+- The tasks require `:environment`, so they need a proper Rails environment
+- Make sure your Rails app's database is configured and accessible
+
+## 🧪 Quick Test
+
+To verify everything works, create a minimal test:
+
+```bash
+# In your Rails app directory
+rails runner "puts 'Gem loaded: ' + PgMultitenantSchemas::VERSION"
+rails tenants:list
+```
+
+## 📁 Task File Structure
+
+The gem now has a clean task structure:
+- `basic_tasks.rake` - List, status, migrate tasks
+- `advanced_tasks.rake` - Advanced tenant management  
+- `tenant_tasks.rake` - Management tasks + aliases + legacy compatibility
+
+All are loaded automatically via the Rails railtie when you include the gem in your Rails application.