Lesson 87 Implementation: Introducing a Database Migration Framework
Series: Building the Flipnzee Auctions Plugin
Lesson: 87
Topic: Creating a Dedicated Database Migration Framework
Introduction
In the previous lessons, we significantly improved the stability of the Flipnzee Auctions plugin by introducing database versioning and resolving the activation issues caused by dbDelta(). Those improvements laid the foundation for a more reliable database upgrade process.
In this lesson, we take the next architectural step by introducing a dedicated database migration framework. Instead of placing all upgrade logic inside the activation routine, we create a separate migration class that will eventually manage all database schema upgrades in a structured and maintainable way.
Although the framework currently contains only the basic migration runner, it establishes the architecture that future migrations will build upon.
Objectives
By the end of this lesson we achieved the following:
- Created a dedicated database migration class.
- Introduced a migration runner.
- Connected the migration framework to plugin activation.
- Separated fresh installations from upgrade logic.
- Successfully tested plugin activation on multiple WordPress environments.
- Prepared the plugin for version-based database migrations.
Why We Needed a Migration Framework
During Lessons 85 and 86 we discovered that repeatedly calling dbDelta() on existing installations could produce unpredictable behaviour on some hosting environments.
Rather than relying solely on dbDelta() for future upgrades, we decided to move toward a proper migration architecture.
The long-term goals are:
- predictable upgrades
- easier maintenance
- version-controlled database changes
- safer production deployments
Architecture Before Lesson 87
Previously, plugin activation simply created the database tables.
Plugin Activation
│
▼
create_tables()
│
▼
Update Database Version
While this worked for new installations, it wasn’t designed for long-term schema evolution.
New Architecture
After Lesson 87 the activation process is smarter.
Plugin Activation
│
▼
Database Version Exists?
│
┌────┴─────┐
│ │
▼ ▼
Fresh Existing
Install Install
│ │
▼ ▼
create_ Migration
tables() Runner
│ │
└────┬─────┘
▼
Update Database Version
This separation allows future upgrades to be handled independently from initial installations.
Files Modified
Main Plugin File
flipnzee-auctions.php
Updated the activation routine to distinguish between fresh installations and existing installations.
New File
includes/class-database-migration.php
Added the new migration framework that will host all future database migrations.
Implementation Highlights
The migration framework now contains a dedicated class responsible for future schema upgrades.
Responsibilities include:
- central migration runner
- version-based upgrade handling
- future migration methods
- database upgrade coordination
Although the class is intentionally lightweight at this stage, it provides a clean foundation for incremental development.
Activation Flow
The activation process now follows this logic:
- Check whether the plugin has been installed before.
- If this is a new installation:
- Create all required database tables.
- If this is an existing installation:
- Execute the migration runner.
- Update the stored database version.
This approach reduces unnecessary database operations on existing sites.
Testing Performed
The migration framework was tested extensively.
Local Development
- Plugin activated successfully.
- No PHP syntax errors.
- Activation logic executed correctly.
- Database version updated successfully.
Hostinger Test Site
The plugin was activated successfully after correcting a syntax issue discovered during testing.
Verified:
- plugin activation
- database version update
- migration runner execution
WP Engine Test Site
The plugin was also activated successfully on WP Engine.
This confirmed that the new activation flow behaves consistently across different hosting environments.
Debugging Process
This lesson involved careful debugging before reaching the final implementation.
Challenges included:
- PHP parse errors caused by unmatched braces.
- Syntax errors while introducing the migration class.
- Activation failures during early integration.
- Ensuring the migration framework loaded before activation.
Each issue was isolated and resolved systematically, resulting in a stable implementation.
Git Milestone
A stable checkpoint was created after successful testing.
Commit
Lesson 87: Add database migration framework
Git Tag
lesson-87-stable
This tag represents the new stable baseline for future database migration work.
Lessons Learned
Several important software engineering principles became evident during this lesson:
- Separate installation logic from upgrade logic.
- Build the migration architecture before implementing migrations.
- Test across multiple hosting environments.
- Resolve one issue at a time rather than making multiple unrelated changes.
- Small architectural improvements reduce future complexity.
Roadmap
The migration framework introduced in this lesson serves as the foundation for the next phase of development.
Upcoming work includes:
- reusable migration helper methods
- version-specific migration functions
- production database migrations
- removal of remaining upgrade dependencies on
dbDelta() - safer long-term database evolution
Download Source Code
Download the starting version of the plugin before the lesson:
Download the completed version after this lesson:
Conclusion
Lesson 87 marks an important architectural milestone in the Flipnzee Auctions project. Rather than simply adding new features, we invested in strengthening the plugin’s internal design.
By introducing a dedicated migration framework, we have separated installation and upgrade responsibilities, making the plugin easier to maintain, safer to upgrade, and better prepared for future releases.
This foundation will support all upcoming database enhancements as Flipnzee Auctions continues evolving into a professional WordPress auction marketplace plugin.