WooCommerce database schema version after an interrupted upgrade

Direct Answers

1. Yes, re-running is idempotent. WooCommerce uses dbDelta() for all schema changes, which emits CREATE TABLE IF NOT EXISTS and conditional ALTER TABLE statements. Already-applied steps are safely skipped; you will not get duplicate-column or duplicate-table errors on a partially migrated schema.
2. No manual correction of woocommerce_db_version is required. The option in wp_options is only written after the entire upgrade routine finishes successfully. An interruption leaves it at the pre-upgrade value, so WooCommerce automatically detects the mismatch and offers the database update again.
3. All major branches from 3.0 (2017) through current 9.x behave identically. The idempotent design and automatic re-offer are documented in the official Database Update Process guide and confirmed in the WC_Install source. No branch documents a different procedure.

Why This Works

The updater (WC_Install::run_upgrade_routine) runs a versioned sequence of dbDelta() calls. Because dbDelta() compares the current schema against the desired schema before issuing SQL, each step is effectively a no-op if the change already exists. The version option acts as a single commit marker — it flips only at the very end — so a crash mid-sequence leaves the database in a "partially migrated, version still old" state that the next run picks up cleanly.

Recovery Steps (Staging First)

1. Clone production to a staging environment.
2. Verify the mismatch: SELECT option_value FROM wp_options WHERE option_name = 'woocommerce_db_version'; and compare with the WC_VERSION constant shown in WooCommerce → Status.
3. Confirm the "Update database" button appears in WooCommerce → Status → Tools → Database.
4. Run the update (web UI or wp wc update --yes via WP-CLI to avoid web-server timeouts).
5. Watch for the "Database update completed" notice, then re-query the option to confirm it now matches WC_VERSION.
6. If staging succeeds, repeat on production during a maintenance window.

When the Standard Path Might Not Apply

The only scenario that breaks idempotency is a PHP fatal error inside a custom migration callback (code hooked to woocommerce_update_ actions). These are rare in core but possible in plugins or custom code. Check your PHP error log for traces from WC_Install::run_upgrade_routine before re-running.

One Diagnostic Detail

Do you have any custom plugins or mu-plugins that hook into WooCommerce update routines? If yes, inspect their callbacks for non-idempotent operations (raw ALTER TABLE without existence checks, data mutations without guards). That answer changes whether a simple re-run is safe or whether you need to audit the custom code first.

Important Reminders

• Downgrading the WooCommerce plugin files does not revert applied schema changes. The only rollback is a database backup restore.
• Very large tables (e.g., wp_wc_order_stats) can still hit max_execution_time or memory limits on ALTER TABLE. Prefer the CLI command wp wc update --yes on large stores.
• The woocommerce_db_version option is distinct from the plugin version constant (WC_VERSION). Only the option controls the updater trigger.