The migration manager includes three types of migrations, each designed for a different purpose.

Background Process Migrations are designed for large-scale data migrations that must be triggered manually by a user with the necessary permissions. These migrations typically operate on substantial data sets and are not executed automatically to avoid performance issues or unintended changes.

Schema Migrations handle structural changes to the database. They are executed during plugin update and ensure that the database schema remains compatible with the current plugin version. These migrations apply version-controlled changes such as adding or modifying tables, columns, or indexes.

Queue Migrations apply small, ordered database updates through a queue(FIFO) system. Each update step is identified by a unique job index and runs sequentially. The queue only runs when triggered by a user with the appropriate permission, ensuring that updates are controlled and predictable.

Step 1: Add a job index and method to the $migrationSteps array

protected $migrationSteps = [
    'v510_update_settings' => 'updateSettings510',
];

Step 2: Define the corresponding public method

public function updateSettings510() {
    update_option( 'sample_option', 'new-value' );
}

Full example

use WP_Statistics\Service\Database\Migrations\Queue\QueueMigration;

class QueueMigration extends BaseMigrationOperation {
    protected array $migrationSteps = [
        'v510_update_settings' => 'updateSettings510',
    ];

    public function updateSettings510() {
        update_option( 'sample_option', 'new-value' );
    }
}

1. The queue starts from the first incomplete job step.
2. Each step runs inside a try/catch block to handle errors gracefully.
3. Completed steps are recorded in the wp_options table to prevent re-execution.
4. Once all steps are complete, the queue remains idle unless new steps are added in future updates.

• completed_steps – Array of completed job index keys.
• completed – Boolean flag indicating whether all steps have finished.
• On fresh installations, all steps are marked as complete to prevent unnecessary execution.