column_anonymizer 0.1.0

data/RAKE_TASKS_GUIDE.md

@@ -0,0 +1,469 @@
+# Rake Tasks Guide
+
+## Overview
+
+Column Anonymizer provides powerful Rake tasks to anonymize your encrypted data in bulk. These tasks read your `config/encrypted_columns.yml` configuration and process records accordingly.
+
+---
+
+## Available Tasks
+
+### 1. `rake column_anonymizer:anonymize_all`
+
+Anonymize **all records** for **all models** defined in `config/encrypted_columns.yml`.
+
+**Usage:**
+```bash
+rake column_anonymizer:anonymize_all
+```
+
+**Example Output:**
+```
+🔍 Found 3 model(s) in configuration
+======================================================================
+
+📋 Processing User...
+   Columns: email, phone, ssn
+   Records: 1,523
+   ✅ Anonymized 1,523 record(s)
+
+📋 Processing Employee...
+   Columns: employee_number, ssn
+   Records: 847
+   ✅ Anonymized 847 record(s)
+
+📋 Processing Patient...
+   Columns: medical_record_number
+   Records: 2,104
+   ✅ Anonymized 2,104 record(s)
+
+======================================================================
+🎉 Anonymization complete!
+   Total records anonymized: 4,474
+======================================================================
+```
+
+**Features:**
+- ✅ Processes all models in configuration
+- ✅ Shows progress every 100 records
+- ✅ Handles errors gracefully
+- ✅ Shows summary statistics
+
+---
+
+### 2. `rake column_anonymizer:anonymize_model[ModelName]`
+
+Anonymize **all records** for a **specific model**.
+
+**Usage:**
+```bash
+rake column_anonymizer:anonymize_model[User]
+rake column_anonymizer:anonymize_model[Employee]
+```
+
+**Example Output:**
+```
+📋 Anonymizing User
+   Columns: email, phone, ssn
+   Records: 1,523
+   Progress: 1523/1523
+   ✅ Anonymized 1,523 record(s)
+```
+
+**Features:**
+- ✅ Focus on one model
+- ✅ Faster than anonymize_all for single model
+- ✅ Shows progress
+
+---
+
+### 3. `rake column_anonymizer:anonymize_where[ModelName,'condition']`
+
+Anonymize records **matching a condition**.
+
+**Usage:**
+```bash
+# Anonymize old users
+rake column_anonymizer:anonymize_where[User,'created_at < "2023-01-01"']
+
+# Anonymize inactive employees
+rake column_anonymizer:anonymize_where[Employee,'status = "inactive"']
+
+# Anonymize by ID range
+rake column_anonymizer:anonymize_where[Patient,'id < 1000']
+```
+
+**Example Output:**
+```
+📋 Anonymizing User where created_at < "2023-01-01"
+   Columns: email, phone, ssn
+   Matching records: 342
+   ⚠️  This will anonymize 342 record(s). Continue? (y/N): y
+   ✅ Anonymized 342 record(s)
+```
+
+**Features:**
+- ✅ Target specific records
+- ✅ Requires confirmation before processing
+- ✅ Supports any WHERE clause
+
+---
+
+### 4. `rake column_anonymizer:preview`
+
+Preview what **would be anonymized** without making changes.
+
+**Usage:**
+```bash
+rake column_anonymizer:preview
+```
+
+**Example Output:**
+```
+🔍 Anonymization Preview
+======================================================================
+
+User:
+   Columns to anonymize: email, phone, ssn
+   Records to process: 1,523
+   Types: email, phone, ssn
+
+   Example (first record):
+     email: john.doe@example.com
+     phone: +1-555-123-4567
+     ssn: 123-45-6789
+
+Employee:
+   Columns to anonymize: employee_number, ssn
+   Records to process: 847
+   Types: employee_id, ssn
+
+   Example (first record):
+     employee_number: EMP-2023-12345
+     ssn: 987-65-4321
+
+======================================================================
+💡 Run 'rake column_anonymizer:anonymize_all' to perform anonymization
+======================================================================
+```
+
+**Features:**
+- ✅ Safe dry-run
+- ✅ Shows what will be processed
+- ✅ Shows example values
+- ✅ No data changes
+
+---
+
+### 5. `rake column_anonymizer:stats`
+
+Show **statistics** about your encrypted columns.
+
+**Usage:**
+```bash
+rake column_anonymizer:stats
+```
+
+**Example Output:**
+```
+📊 Column Anonymizer Statistics
+======================================================================
+
+Models configured: 3
+Total encrypted columns: 6
+
+Detailed breakdown:
+
+User:
+  Columns: 3 (email, phone, ssn)
+  Records: 1,523
+  Types: email, phone, ssn
+
+Employee:
+  Columns: 2 (employee_number, ssn)
+  Records: 847
+  Types: employee_id, ssn
+
+Patient:
+  Columns: 1 (medical_record_number)
+  Records: 2,104
+  Types: mrn
+
+======================================================================
+Total records across all models: 4,474
+======================================================================
+```
+
+**Features:**
+- ✅ Overview of all models
+- ✅ Column counts
+- ✅ Record counts
+- ✅ Type information
+
+---
+
+## Common Workflows
+
+### Initial Setup and Testing
+
+```bash
+# 1. Preview what will be anonymized
+rake column_anonymizer:preview
+
+# 2. Check statistics
+rake column_anonymizer:stats
+
+# 3. Test on one model first
+rake column_anonymizer:anonymize_model[User]
+
+# 4. If successful, anonymize everything
+rake column_anonymizer:anonymize_all
+```
+
+### Anonymizing Old Data
+
+```bash
+# Anonymize users older than 2 years
+rake column_anonymizer:anonymize_where[User,'created_at < "2024-01-01"']
+
+# Anonymize deleted accounts
+rake column_anonymizer:anonymize_where[User,'deleted_at IS NOT NULL']
+```
+
+### Production Deployment
+
+```bash
+# 1. Preview on staging
+RAILS_ENV=staging rake column_anonymizer:preview
+
+# 2. Check stats
+RAILS_ENV=staging rake column_anonymizer:stats
+
+# 3. Anonymize in production (with backup!)
+RAILS_ENV=production rake column_anonymizer:anonymize_all
+```
+
+### Regular Maintenance
+
+```bash
+# Weekly: Anonymize accounts older than 1 year
+rake column_anonymizer:anonymize_where[User,'last_login_at < "2025-02-01"']
+```
+
+---
+
+## Advanced Usage
+
+### With Custom Generators
+
+If you've registered custom generators:
+
+```ruby
+# config/initializers/column_anonymizer.rb
+ColumnAnonymizer::Anonymizer.register(:credit_card) do
+  "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
+end
+```
+
+The Rake tasks will automatically use your custom generators:
+
+```bash
+rake column_anonymizer:anonymize_all
+# Uses your custom credit_card generator
+```
+
+### Batch Processing Large Datasets
+
+For very large tables, consider processing in batches:
+
+```bash
+# Process by ID ranges
+rake column_anonymizer:anonymize_where[User,'id BETWEEN 1 AND 10000']
+rake column_anonymizer:anonymize_where[User,'id BETWEEN 10001 AND 20000']
+# etc.
+```
+
+### Scheduling with Cron
+
+```bash
+# Add to crontab
+# Anonymize old records weekly on Sunday at 2 AM
+0 2 * * 0 cd /app && RAILS_ENV=production rake column_anonymizer:anonymize_where[User,'created_at < NOW() - INTERVAL 1 YEAR']
+```
+
+### Using in Deployment Scripts
+
+```ruby
+# config/deploy.rb (Capistrano)
+after 'deploy:migrate', 'column_anonymizer:anonymize_old_data'
+
+namespace :column_anonymizer do
+  task :anonymize_old_data do
+    on roles(:db) do
+      within release_path do
+        with rails_env: fetch(:rails_env) do
+          execute :rake, 'column_anonymizer:anonymize_where[User,\'created_at < "2023-01-01"\']'
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## Error Handling
+
+The tasks handle errors gracefully:
+
+```
+📋 Processing User...
+   Columns: email, phone, ssn
+   Records: 1,523
+   ❌ Error anonymizing User ID 42: Validation failed
+   ❌ Error anonymizing User ID 105: undefined method 'email='
+   ✅ Anonymized 1,521 record(s)
+   ⚠️  2 error(s)
+```
+
+**Common errors:**
+- Model class not found → Check model name spelling
+- Validation errors → Check model validations
+- Missing column → Check YAML config matches model
+
+---
+
+## Performance Tips
+
+### For Large Tables
+
+1. **Use batching** - `find_each` processes in batches of 1000
+2. **Process during low traffic** - Run during off-peak hours
+3. **Use conditions** - Process subsets with `anonymize_where`
+4. **Monitor progress** - Watch the progress indicators
+5. **Check database locks** - Ensure no long-running queries
+
+### Optimization
+
+```bash
+# Process specific date ranges
+rake column_anonymizer:anonymize_where[User,'created_at BETWEEN "2020-01-01" AND "2020-12-31"']
+
+# Use indexes
+# Add indexes on commonly queried columns (created_at, status, etc.)
+```
+
+---
+
+## Safety Checklist
+
+Before running in production:
+
+- ✅ **Backup your database** - Always have a recent backup
+- ✅ **Test on staging** - Run tasks on staging first
+- ✅ **Preview first** - Use `preview` task to see what will change
+- ✅ **Check stats** - Use `stats` task to understand scope
+- ✅ **Test one model** - Use `anonymize_model` on one model first
+- ✅ **Verify custom generators** - Ensure custom generators work correctly
+- ✅ **Check validations** - Ensure anonymized data passes validations
+- ✅ **Monitor performance** - Watch database and app performance
+- ✅ **Have rollback plan** - Know how to restore from backup
+
+---
+
+## Integration Examples
+
+### With Heroku Scheduler
+
+```bash
+# Add to Heroku Scheduler (daily at midnight)
+rake column_anonymizer:anonymize_where[User,'deleted_at < NOW() - INTERVAL 30 DAY']
+```
+
+### With Sidekiq/Background Jobs
+
+```ruby
+# app/jobs/anonymize_old_users_job.rb
+class AnonymizeOldUsersJob < ApplicationJob
+  queue_as :default
+
+  def perform
+    system("rake column_anonymizer:anonymize_where[User,'created_at < \"#{1.year.ago.to_date}\"']")
+  end
+end
+```
+
+### With Rails Runner
+
+```bash
+# One-off command
+rails runner "
+  schema = ColumnAnonymizer::SchemaLoader.load_schema
+  User.where('created_at < ?', 2.years.ago).find_each do |user|
+    ColumnAnonymizer::Anonymizer.anonymize_model!(user)
+  end
+"
+```
+
+---
+
+## Troubleshooting
+
+### Task Not Found
+
+```bash
+# Error: Don't know how to build task 'column_anonymizer:anonymize_all'
+
+# Solution: Ensure rake file is loaded
+# For gems, add to gemspec:
+spec.files = Dir['lib/**/*.{rb,rake}']
+
+# Or manually load:
+rake -T column_anonymizer
+```
+
+### Model Not Found
+
+```bash
+# Error: Model class 'User' not found
+
+# Solution: Check model name in encrypted_columns.yml
+# Must match exact class name (case-sensitive)
+```
+
+### No Records Anonymized
+
+```bash
+# Check:
+1. Models have encrypted columns defined
+2. YAML config matches model structure
+3. Records actually exist
+4. Models respond to encrypted_columns_metadata
+```
+
+---
+
+## Quick Reference
+
+| Task | Purpose | Example |
+|------|---------|---------|
+| `anonymize_all` | Anonymize all models | `rake column_anonymizer:anonymize_all` |
+| `anonymize_model[Model]` | Anonymize one model | `rake column_anonymizer:anonymize_model[User]` |
+| `anonymize_where[Model,'condition']` | Conditional anonymization | `rake column_anonymizer:anonymize_where[User,'id < 1000']` |
+| `preview` | Dry run | `rake column_anonymizer:preview` |
+| `stats` | Show statistics | `rake column_anonymizer:stats` |
+
+---
+
+## Summary
+
+The Rake tasks provide:
+
+✅ **Bulk anonymization** - Process all models at once  
+✅ **Selective anonymization** - Target specific models or records  
+✅ **Safe preview** - Check before making changes  
+✅ **Progress tracking** - Monitor long-running operations  
+✅ **Error handling** - Graceful error recovery  
+✅ **Statistics** - Understand your data  
+
+Start with `preview` and `stats`, then use `anonymize_all` or `anonymize_model` as needed! 🚀