SuperClaude/.claude/commands/migrate.md

/migrate - Execute database and code migrations

Legend

Symbol	Meaning		Abbrev	Meaning
→	leads to		cfg	configuration
&	and/with		impl	implementation
w/	with		perf	performance
@	at/located		ops	operations
>	greater than		val	validation
∀	for all/every		req	requirements
∃	exists/there is		deps	dependencies
∴	therefore		env	environment
∵	because		db	database
≡	equivalent		api	interface
≈	approximately		docs	documentation
📁	directory/path		std	standard
🔢	number/count		def	default
📝	text/string		ctx	context
⚙	setting/config		err	error
🎛	control/flags		exec	execution
🔧	configuration		qual	quality
📋	group/category		rec	recovery
🚨	critical/urgent		sev	severity
⚠	warning/caution		resp	response
🔄	retry/recovery		esc	escalation
✅	success/fixed		tok	token
❌	failure/error		opt	optimization
ℹ	information		UX	user experience
⚡	fast/quick		UI	user interface
🐌	slow/delayed		C	critical
✨	complete/done		H	high
📖	read operation		M	medium
✏	edit operation		L	low
🗑	delete operation

Purpose

Execute comprehensive database or code migrations based on specifications in $ARGUMENTS with safety checks and rollback capabilities.

Syntax

/migrate [flags] [migration-spec]

Universal Flags

--plan: "Show execution plan before running" --uc: "UltraCompressed mode (~70% token reduction)" --ultracompressed: "Alias for --uc" --think: "Multi-file analysis w/ context (4K tokens)" --think-hard: "Deep architectural analysis (10K tokens)" --ultrathink: "Critical system redesign (32K tokens)" --c7: "Enable Context7→library documentation lookup" --seq: "Enable Sequential→complex analysis & thinking" --magic: "Enable Magic→UI component generation" --pup: "Enable Puppeteer→browser automation & testing" --all-mcp: "Enable all MCP servers" --no-mcp: "Disable all MCP servers (native tools only)" --no-c7: "Disable Context7 specifically" --no-seq: "Disable Sequential thinking specifically" --no-magic: "Disable Magic UI builder specifically" --no-pup: "Disable Puppeteer specifically"

Command-Specific Flags

Migration Types:

• --schema: Database schema migrations (tables, indexes, constraints)
• --data: Data transformation and migration operations
• --code: Code refactoring and modernization migrations
• --framework: Framework or library version migrations
• --config: Configuration and environment migrations

Execution Control:

• --dry-run: Preview changes without execution
• --rollback: Revert to pre-migration state
• --checkpoint: Create checkpoint before migration
• --force: Override safety checks (use with caution)

Safety & Validation:

• --backup: Create full backup before migration
• --validate: Validate migration integrity and consistency
• --test-mode: Run in isolated test environment
• --zero-downtime: Implement zero-downtime migration strategy

Monitoring:

• --progress: Show detailed progress during migration
• --log-level [level]: Set logging verbosity (info|debug|trace)
• --timeout [seconds]: Set maximum migration duration

Examples

• /migrate --schema --dry-run --think → Schema migration preview with analysis
• /migrate --data --backup --validate --think-hard → Data migration with safety checks
• /migrate --framework --zero-downtime --ultrathink → Framework upgrade with zero downtime
• /migrate --rollback --checkpoint restore-20240115 → Rollback to specific checkpoint
• /migrate --code --test-mode --progress → Code migration in test environment

Migration Types

Schema Migrations:

• Create, alter, or drop database tables
• Add or modify indexes for performance
• Update constraints and relationships
• Manage database versioning and compatibility
• Handle foreign key dependencies

Data Migrations:

• Transform existing data to new formats
• Backfill missing or derived data fields
• Clean up obsolete or orphaned records
• Ensure referential integrity throughout process
• Handle large dataset migrations efficiently

Code Migrations:

• Refactor to new architectural patterns
• Update to new framework versions
• Migrate between different technologies
• Modernize legacy code and patterns
• Update API contracts and interfaces

Framework Migrations:

• Upgrade major framework versions
• Migrate between competing frameworks
• Update dependency chains
• Handle breaking changes systematically
• Maintain backward compatibility where possible

Safe Migration Workflow

1. Planning Phase:

• Analyze migration requirements and scope
• Design migration strategy and approach
• Create comprehensive rollback plan
• Identify dependencies and prerequisites
• Estimate duration and resource requirements

2. Preparation Phase:

• Create full backup of affected systems
• Set up isolated test environment
• Prepare migration scripts and procedures
• Validate rollback procedures
• Notify stakeholders and schedule downtime

3. Testing Phase:

• Run migration in test environment
• Validate data integrity and functionality
• Test rollback procedures
• Performance test with realistic data
• Document any issues and resolutions

4. Execution Phase:

• Apply migration with transaction support
• Monitor system performance and health
• Track progress and log all operations
• Handle errors gracefully with fallbacks
• Maintain communication with stakeholders

5. Verification Phase:

• Validate migration success and completeness
• Verify data integrity with checksums
• Run comprehensive test suite
• Monitor system stability post-migration
• Document lessons learned and improvements

Dry Run Operations (--dry-run)

Preview Capabilities:

• Show all changes without executing them
• Display affected records and files count
• Estimate migration duration and resource usage
• Identify potential issues and conflicts
• Generate detailed execution plan

Risk Assessment:

• Analyze impact on system performance
• Identify data integrity risks
• Assess rollback complexity
• Evaluate downtime requirements
• Calculate resource utilization

Rollback Operations (--rollback)

Rollback Strategies:

• Transaction-based rollback for database changes
• Backup restoration for complex changes
• Code version control reversion
• Configuration rollback procedures
• Progressive rollback for staged migrations

Rollback Verification:

• Verify system returns to pre-migration state
• Validate data integrity after rollback
• Test system functionality completely
• Monitor performance and stability
• Document rollback effectiveness

Zero-Downtime Migrations (--zero-downtime)

Strategies:

• Blue-green deployment patterns
• Rolling updates with health checks
• Shadow migration and cutover
• Feature flags for gradual rollout
• Database read replica promotion

Implementation:

• Maintain dual-write compatibility
• Implement backward-compatible schemas
• Use load balancers for traffic switching
• Monitor key metrics during transition
• Prepare instant rollback mechanisms

Safety Measures

Data Protection:

• Automatic backup creation before migration
• Transaction atomicity for database operations
• Checksum validation for data integrity
• Idempotent migration scripts
• Recovery point objectives (RPO) compliance

System Protection:

• Resource usage monitoring and limits
• Timeout protection for long operations
• Health checks and circuit breakers
• Progressive execution with validation
• Automated rollback triggers

Deliverables

• Migration Scripts: Complete, tested migration procedures
• Execution Report: Detailed migration statistics and outcomes
• Backup Confirmation: Verified backup creation and integrity
• Data Integrity Report: Validation of data consistency post-migration
• Rollback Procedures: Documented and tested rollback plans
• Performance Metrics: Before/after performance comparisons

Output Locations

• Migration Logs: .claudedocs/reports/migration-{timestamp}.md
• Data Validation: .claudedocs/metrics/data-validation-{timestamp}.md
• Rollback Plans: .claudedocs/summaries/rollback-plan-{timestamp}.md
• Performance Reports: .claudedocs/metrics/migration-performance-{timestamp}.md

Research Requirements

External_Library_Research:

• Identify library/framework mentioned
• Context7 lookup for official documentation
• Verify API patterns and examples
• Check version compatibility
• Document findings in implementation Pattern_Research:
• Search existing codebase for similar patterns
• Magic component search if UI-related
• WebSearch for official documentation
• Validate approach with Sequential thinking
• Document pattern choice rationale API_Integration_Research:
• Official documentation lookup
• Authentication requirements
• Rate limiting and error handling
• SDK availability and examples
• Integration testing approach

Report Notifications

📄 Analysis report saved to: {path} 📊 Metrics updated: {path} 📋 Summary saved to: {path} 💾 Checkpoint created: {path} 📚 Documentation created: {path} 📁 Created directory: {path} ✅ {operation} completed successfully ❌ {operation} failed: {reason} ⚠ {operation} completed w/ warnings

Best Practices

Planning:

• Always test migrations in staging environment
• Create detailed rollback plans before execution
• Communicate with stakeholders about timing
• Plan for peak and off-peak execution windows
• Document all migration decisions and rationale

Execution:

• Use transactions for atomicity where possible
• Monitor system health throughout migration
• Keep detailed logs of all operations
• Have rollback procedures ready and tested
• Validate data integrity at each step

Post-Migration:

• Verify system functionality completely
• Monitor performance for regression
• Clean up temporary migration artifacts
• Update documentation and procedures
• Conduct post-mortem for improvement

Troubleshooting

• Large Datasets: Use --progress --timeout for monitoring
• Complex Dependencies: Apply --think-hard for comprehensive planning
• Production Systems: Combine --zero-downtime --backup --validate
• Failed Migrations: Use --rollback with specific checkpoint

Success Messages

✅ {operation} completed successfully 📝 Created: {file_path} ✏ Updated: {file_path} ✨ Task completed: {task_title}