Migration Guide

This guide helps you migrate from nself v0.1.x to v0.2.0, which includes significant new features and some breaking changes. The migration process is largely automated, but requires your review and approval.

Pre-Migration Checklist

• ✅ Backup your entire project directory
• ✅ Export current database schema and data
• ✅ Document any custom configurations
• ✅ Test the migration on a copy of your project first
• ✅ Update nself CLI to v0.2.0

Migration Overview

What Changes in v0.2.0

• Database Management: New DBML-based schema management system
• Directory Structure: Addition of database/ directory
• Environment Variables: Some variables renamed for consistency
• CLI Commands: New database commands and reorganized structure
• Configuration Format: Enhanced configuration options

Migration Timeline

Expected migration time: 15-30 minutes for most projects

1. Preparation (5 mins): Backup and update CLI
2. Automated Migration (5-10 mins): Run migration tool
3. Manual Review (10-15 mins): Review and adjust changes
4. Testing (5-10 mins): Verify everything works

Step-by-Step Migration

Step 1: Update nself CLI

# Update to latest version
nself update

# Verify version
nself --version
# Should show v0.2.0 or later

Step 2: Create Backup

# Create complete project backup
cp -r /path/to/your/project /path/to/backup/project-v0.1-backup

# Export database
nself db backup --name pre-migration-backup

# Backup configuration
cp .env.local .env.v0.1.backup

Step 3: Run Migration Tool

# Navigate to your project
cd /path/to/your/project

# Run migration (dry-run first to see what will change)
nself migrate --from v0.1 --to v0.2 --dry-run

# Review the proposed changes, then run actual migration
nself migrate --from v0.1 --to v0.2

# Alternative: Interactive migration with prompts
nself migrate --interactive

Step 4: Review Generated Files

The migration creates several new files and directories:

your-project/
├── database/                    # NEW: Database management
│   ├── schema.dbml             # Your database schema
│   ├── migrations/             # Generated migrations
│   └── seeds/                  # Seed data
│       ├── development/
│       ├── staging/
│       └── production/
├── .env.local                  # Updated with new variables
├── .env.v0.1.backup           # Your original config
└── MIGRATION.md               # Migration summary

Configuration Changes

Environment Variable Updates

Some environment variables have been renamed or reorganized:

New Configuration Options

v0.2.0 adds many new configuration options:

# Database management
DB_SEED_ON_INIT=true
DB_BACKUP_RETENTION=7
DB_CONFIRM_DESTRUCTIVE=true

# Service scaling
NESTJS_API_REPLICAS=2
BULLMQ_EMAIL_CONCURRENCY=5
PYTHON_ML_API_REPLICAS=1

# Performance tuning
POSTGRES_SHARED_BUFFERS=256MB
REDIS_MAXMEMORY=128MB
NGINX_WORKER_PROCESSES=auto

Database Migration

Schema Generation

The migration tool attempts to generate a DBML schema from your existing database:

# If automatic generation fails, create manually
nself db generate:from-database

# Or start with a template
nself db init --template basic

# Edit the generated schema
nano database/schema.dbml

Migration File Creation

# Generate initial migration from existing schema
nself db run --message "Initial migration from v0.1"

# This creates:
# database/migrations/001_initial_migration_from_v0.1.up.sql
# database/migrations/001_initial_migration_from_v0.1.down.sql

Service Configuration Updates

NestJS Services

If you had custom services in v0.1.x, update your configuration:

# Old format (v0.1.x)
SERVICES=api,webhooks

# New format (v0.2.0)
NESTJS_SERVICES=api,webhooks
NESTJS_VERSION=10.x
NESTJS_SWAGGER=true

Worker Configuration

# Old format (v0.1.x)
WORKERS=email,image

# New format (v0.2.0)
BULLMQ_WORKERS=email-worker,image-processor
BULLMQ_EMAIL_CONCURRENCY=5
BULLMQ_IMAGE_CONCURRENCY=3

Manual Steps After Migration

Review Generated Schema

Check the generated database/schema.dbml file:

# Validate the generated schema
nself db validate

# Make any necessary adjustments to schema.dbml
nano database/schema.dbml

# Regenerate migrations if needed
nself db run --message "Updated schema after migration"

Update Custom Code

If you have custom services or functions, update them for v0.2.0 compatibility:

• Environment Variables: Update variable names in your code
• Database Connections: Update connection strings if needed
• API Endpoints: Verify all endpoints still work
• Dependencies: Update package versions

Test Database Operations

# Test database connectivity
nself db ping

# Check migration status
nself db migrate:status

# Apply any pending migrations
nself db migrate:up

# Test seeding
nself db seed --fresh

Verification Steps

Functional Testing

# Rebuild with new configuration
nself build

# Start services
nself up

# Check service status
nself status

# Test API endpoints
curl http://localhost:8080/v1/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "query { __schema { queryType { name } } }"}'

# Test database connectivity
nself db ping

Performance Verification

• Check service startup times
• Verify database query performance
• Test API response times
• Monitor resource usage

Troubleshooting Migration Issues

Common Problems

Migration Tool Fails

# If automatic migration fails
nself migrate --force --from v0.1 --to v0.2

# Or manual migration
nself init --template minimal
# Then manually copy your settings

Schema Generation Issues

# If schema generation fails
nself db generate:from-database --force

# Or create schema manually based on your existing tables
nself db init --template custom

Configuration Errors

# Validate configuration
nself config validate

# Check for missing variables
nself config check --migration

# Compare with example
nself config generate --template .env.example

Rollback Procedure

If migration fails or causes issues, you can rollback:

# Stop current services
nself down

# Restore backup
rm -rf ./*
cp -r /path/to/backup/* ./

# Downgrade nself CLI if needed
nself update --version v0.1.x

# Restore database from backup
nself db restore --name pre-migration-backup

Post-Migration Optimization

New Feature Adoption

After successful migration, consider adopting new v0.2.0 features:

• Database Management: Use DBML for schema changes
• Visual Design: Connect to dbdiagram.io
• Enhanced Monitoring: Enable new health checks
• Performance Tuning: Use new optimization settings

Configuration Cleanup

# Remove backup files after successful migration
rm .env.v0.1.backup
rm -rf project-v0.1-backup/

# Clean up old configurations
nself config clean --remove-deprecated

# Optimize configuration for v0.2.0
nself config optimize

Migration Support

Getting Help

If you encounter issues during migration:

• Debug Mode: Run migration with --debug flag
• Migration Logs: Check migration.log file
• Community Support: Ask questions in GitHub Discussions
• Issue Reports: Create GitHub issues for bugs

Migration Report

After migration, nself generates a report:

# View migration summary
cat MIGRATION.md

# Generate detailed report
nself migrate --report

# Export migration metrics
nself migrate --export-metrics migration-metrics.json

Best Practices for Future Migrations

• Regular Backups: Maintain regular backups of your project
• Test Migrations: Test on non-production environments first
• Document Changes: Keep track of custom modifications
• Stay Updated: Regularly update to latest versions

Next Steps

After successful migration to v0.2.0:

• Database Management - Learn the new database features
• What's New - Explore all v0.2.0 features
• Breaking Changes - Review all changes
• Production Deployment - Deploy the updated version

The migration to v0.2.0 unlocks powerful new database management capabilities and enhanced developer experience. Take time to explore the new features and optimize your configuration.