Skip to main content

Migration Guides

DEVELOPER Intermediate

Upgrade from previous versions of EZ-Console.

Overview​

This guide helps you migrate your EZ-Console application when upgrading to newer versions of the framework. Follow these guides to ensure a smooth transition and avoid breaking changes.

Before You Start​

Backup Your Data​

Always backup your database and configuration files before upgrading:

# Backup database
mysqldump -u user -p database_name > backup_$(date +%Y%m%d).sql

# Backup SQLite
cp ez-console.db ez-console.db.backup

# Backup configuration
cp config.yml config.yml.backup

Check Current Version​

# Check framework version in go.mod
grep ez-console go.mod

# Check application version
./server --version

Version Migration Guides​

Upgrading to Latest Version​

Step 1: Update Dependencies​

# Update Go module
go get -u github.com/sven-victor/ez-console@latest
go mod tidy

# Update frontend dependencies
cd web
pnpm update ez-console

Step 2: Review Breaking Changes​

Check the Changelog for breaking changes in your target version.

Step 3: Update Configuration​

Review and update your config.yml file:

# Check for deprecated options
# Old format (if any)
# New format

Step 4: Update Code​

Review your code for deprecated APIs:

// Old API (if deprecated)
// New API

Step 5: Run Migrations​

# Database migrations run automatically on startup
# Ensure database backup is complete before starting
./server --global.encrypt-key=your-key

Step 6: Test Thoroughly​

  • Test all API endpoints
  • Verify authentication and authorization
  • Check frontend functionality
  • Review audit logs

Common Migration Scenarios​

Database Schema Changes​

If the framework introduces database schema changes:

# 1. Backup database
mysqldump database > backup.sql

# 2. Update framework
go get -u github.com/sven-victor/ez-console@latest

# 3. Start server (migrations run automatically)
./server --global.encrypt-key=your-key

# 4. Verify migrations
# Check logs for migration status

Configuration Format Changes​

If configuration format changes:

# Old format
old_config:
  key: value

# New format
new_config:
  key: value

Update your config.yml accordingly.

API Changes​

If APIs change:

// Old API
oldFunction(param1, param2)

// New API
newFunction(param1, param2, param3)

Update all usages in your codebase.

Frontend Component Changes​

If frontend components change:

// Old component usage
import { OldComponent } from 'ez-console';

// New component usage
import { NewComponent } from 'ez-console';

Update all component imports and usages.

Migration Checklist​

  • Backup database
  • Backup configuration files
  • Review changelog for breaking changes
  • Update dependencies
  • Update configuration file
  • Update code for API changes
  • Update frontend components
  • Run database migrations
  • Test all functionality
  • Update documentation
  • Deploy to staging first
  • Monitor logs after deployment

Rollback Procedure​

If you need to rollback:

# 1. Stop the application
systemctl stop myapp

# 2. Restore database backup
mysql -u user -p database < backup.sql

# 3. Restore configuration
cp config.yml.backup config.yml

# 4. Revert code changes
git checkout previous-version

# 5. Restart application
systemctl start myapp

Getting Help​

If you encounter issues during migration:

  1. Check Logs: Review application logs for errors
  2. Review Documentation: Check the changelog and release notes
  3. GitHub Issues: Search for similar issues on GitHub
  4. Community: Ask in GitHub Discussions

Need help? Ask in GitHub Discussions.