Database Migration System
The HMIS Database Migration System provides administrators with a powerful, self-contained solution for managing database schema changes and version control. This system allows you to safely execute database migrations, track execution history, and maintain database consistency across different environments.
The Database Migration System is built directly into the HMIS application, eliminating the need for external migration tools. It provides:
- Version Control: Track database schema versions alongside application versions
- Safe Execution: Atomic migrations with rollback capabilities
- Progress Monitoring: Real-time tracking of migration execution
- Audit Trail: Complete history of all migration activities
- Admin Control: Secure, administrator-controlled execution
- Login as an administrator to the HMIS system
- Navigate to: Admin → Database Migration
-
URL:
http://your-domain/context/faces/admin/database_migration.xhtml
The migration dashboard provides a comprehensive overview of your database migration status:
- Current Version: Shows the current database schema version
- Application Version: Displays the latest application version available
- Pending Migrations: Number of migrations waiting to be executed
- Status: Current system status (Ready/In Progress)
When migrations are running, you'll see:
- Progress Bar: Visual indicator of completion percentage
- Current Migration: Which migration is currently executing
- Step Information: Current step and total steps remaining
When new application versions include database changes, they appear in the Pending Migrations section:
-
Review Migration Details:
- Version number and description
- Estimated execution time
- Whether downtime is required
- Affected database tables
-
Execute Migrations:
- Click "Execute All Pending Migrations"
- Confirm the action when prompted
- Monitor progress in real-time
The Available Migrations tab shows all migrations in the system:
- Version: Migration version number
- Description: Brief description of changes
- Author: Who created the migration
- Affects: Which modules are impacted
- Status: Executed or Pending
The Execution History tab provides a complete audit trail:
- Version: Which migration was executed
- Status: Success, Failed, or Rolled Back
- Executed At: When the migration ran
- Duration: How long it took to complete
- Executed By: Which administrator ran it
- Actions: Options to rollback successful migrations
The Execution Log tab shows detailed logs from migration runs:
- Complete SQL execution details
- Error messages (if any)
- Performance information
- Verification results
- Only one migration can run at a time
- System prevents concurrent executions
- Automatic cleanup if migrations are interrupted
- Each migration runs in a database transaction
- Automatic rollback on failure
- Data integrity protection
- Safe rollback of successfully executed migrations
- Rollback scripts provided for each migration
- Complete audit trail of rollback activities
The system uses semantic versioning for migrations:
- Format:
v2.1.0,v2.1.1,v2.2.0 - Automatic discovery from filesystem
- Chronological execution order
- Major: Significant database changes
- Minor: New features or schema additions
- Patch: Bug fixes or minor adjustments
Administrators can configure migration behavior:
- Navigate to: Admin → System Configuration
-
Find migration-related options:
- Auto Execute Database Migrations: Enable automatic execution
- Show Migration Management to Admins: Control UI visibility
- Require Migration Confirmation: Force confirmation dialogs
- Enable Migration Progress Tracking: Show real-time progress
- Log Migration Execution Details: Enable detailed logging
Symptoms: Migration shows as failed in execution history
Solutions:
- Check the Execution Log tab for error details
- Verify database permissions
- Ensure sufficient disk space
- Contact system administrator if needed
Symptoms: Cannot access migration management page
Solutions:
- Verify you have administrator privileges
- Check if "Show Migration Management to Admins" is enabled
- Clear browser cache and try again
- Contact system administrator
Symptoms: Migrations take longer than expected
Solutions:
- Check database server performance
- Verify network connectivity
- Review migration complexity in logs
- Consider scheduling during low-usage periods
- Backup Database: Always create a backup before running migrations
- Review Changes: Understand what each migration does
- Check Dependencies: Ensure all prerequisites are met
- Plan Downtime: Schedule during low-usage periods if required
- Monitor Progress: Watch the real-time progress indicators
- Don't Interrupt: Allow migrations to complete naturally
- Check Logs: Review execution logs for any warnings
- Verify Results: Confirm changes were applied correctly
- Test Functionality: Verify all system features work correctly
- Check Performance: Monitor system performance
- Review Logs: Examine execution logs for any issues
- Document Changes: Note any operational changes needed
- Only administrators can execute migrations
- User actions are logged and auditable
- Role-based access controls enforced
- All migrations run in transactions
- Automatic rollback on failure
- Complete audit trail maintained
- Migration locking prevents conflicts
- Progress monitoring prevents interruption
- Error handling protects data integrity
- Check migration status periodically
- Review execution logs for warnings
- Monitor system performance after migrations
- Schedule regular database backups
- Test backup restoration procedures
- Keep migration logs for audit purposes
- Check execution logs for error details
- Review this documentation for guidance
- Contact system administrator for assistance
- Report issues through the support system
Advanced users can create custom migration scripts following the established format structure.
The system can handle multiple migrations in sequence, executing them in the correct order automatically.
The migration system integrates with the overall HMIS monitoring infrastructure for comprehensive system oversight.
The Database Migration System provides a robust, secure, and user-friendly way to manage database schema changes in your HMIS installation. By following the guidelines in this documentation, administrators can safely maintain database consistency while deploying new application features.
For additional assistance or questions about the migration system, please contact your system administrator or refer to the technical documentation.