Versioned Migrations¶

BaseMigrator ships three versioned migrations. They execute once and are never re-run.

V1_0_0 — Initial schema¶

Creates the wc_entity_types table and seeds the four core entity types:

// src/Migrations/Versions/V1_0_0.php
public function install(): void {
    WCEntityType::create_table();

    (new WCEntityType(['entity' => 'shop_subscription']))->save();
    (new WCEntityType(['entity' => 'shop_order']))->save();
    (new WCEntityType(['entity' => 'product']))->save();
    (new WCEntityType(['entity' => 'product_variation']))->save();
}

V1_18_1 — WC status table¶

Creates the wc_statuses table and populates it with all registered WooCommerce order statuses, subscription statuses, and native WordPress post statuses. The wc- prefix is stripped before storing.

V1_20_0 — Stalled subscription fix¶

Repairs subscriptions that were incorrectly left in on-hold when their most recent renewal order was pending or failed. Moves them to wc-stalled.

Handles both HPOS (wc_orders table) and legacy (wp_posts) storage modes.

Adding a new versioned migration¶

1. Create a class in src/Migrations/Versions/ implementing Migration.
2. Return a version string that is greater than the previous highest version.
3. Add an instance to the get_migrations() array in BaseMigrator (or your own migrator) in ascending version order.

// src/Migrations/Versions/V2_0_0.php
class V2_0_0 implements Migration {
    public function install(): void {
        global $wpdb;
        $wpdb->query("ALTER TABLE {$wpdb->prefix}my_table ADD COLUMN new_col VARCHAR(50)");
    }

    public function get_version(): string {
        return '2.0.0';
    }
}