Migration Guide

This guide helps you migrate between nself versions, covering new features, breaking changes, and step-by-step upgrade procedures. The current stable version is v0.4.8.

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 latest version

Version History

What is New in v0.4.8

• Plugin System: Extensible architecture with official plugins (Stripe, GitHub, Shopify)
• Enhanced Environment Workflow: Three-environment structure (dev, staging, prod)
• Improved Deployment: Better SSH deployment with health checks
• CLI Enhancements: New commands for frontend, config, and history management
• Monitoring Profiles: Minimal, standard, full monitoring configurations

Migration Timeline

Expected migration time: 10-20 minutes for most projects

1. Preparation (5 mins): Backup and update CLI
2. Update (2-5 mins): Run nself update
3. Rebuild (5-10 mins): Rebuild configuration
4. Testing (5 mins): Verify everything works

Migrating to v0.4.8

Step 1: Update nself CLI

# Update to latest version
nself update

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

Step 2: Create Backup

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

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

# Backup configuration
cp .env .env.backup

Step 3: Update Environment Structure

v0.4.7+ uses a new environment structure with .environments/ directory:

your-project/
├── .environments/               # NEW: Environment configurations
│   ├── dev/
│   │   └── .env                # Development settings
│   ├── staging/
│   │   ├── .env                # Staging settings
│   │   ├── .env.secrets        # Staging secrets (git-ignored)
│   │   └── server.json         # SSH connection details
│   └── prod/
│       ├── .env                # Production settings
│       ├── .env.secrets        # Production secrets (git-ignored)
│       └── server.json         # SSH connection details
├── .env                        # Active configuration (git-ignored)
└── .env.example                # Template

Step 4: Switch to New Environment Workflow

# Initialize environments
nself env init

# Switch environments
nself env switch dev
nself env switch staging
nself env switch prod

# Generate secrets for staging/prod
nself staging secrets generate
nself prod secrets generate

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.