Cloud: Migrating a Store from a Single Server

A blog survives a lost comment. A store cannot lose or duplicate three kinds of event, and each has a different owner:

The WordPress page treats the data as one pile moved by a dump or by DMS. For a store the rule that keeps all three safe is short: at any moment exactly one side takes orders and exactly one side runs the queue. The rest of the page is how to make that true across the freeze, the data copy, the DNS switch and a rollback.

The two methods are the ones of the WordPress page, and the choice is the same except that the cost of downtime is now measured in orders. A shop that takes ten orders an hour can accept a one-hour maintenance window at night; a shop with a steady flow, or a promotion in the calendar, cannot.

Source: AWS DMS User Guide: Using a MySQL-compatible database as a source for AWS DMS

Whichever you choose, both ends need the same thing at the moment of the final copy: no write on the old side. DMS replays what the old database writes until you stop the task, so a single order that sneaks in after the freeze is copied too, and an order that is created on the new side before the task is stopped can be overwritten by a replayed row. The freeze is not optional with DMS; it is what makes lag zero mean something. The task in the WordPress page is the template. The settings below are the ones that matter for a store, and the table mapping leaves out the sessions table:

Source: AWS DMS User Guide: Specifying task settings for AWS DMS tasks

Source: AWS DMS User Guide: Using table mapping to specify task settings

The reasons for each choice:

Every DMS task also needs a primary key in each table for CDC. All WooCommerce core tables have one; tables created by extensions may not, so list the tables without a primary key in the inventory and fix or exclude them.

High-performance order storage is two options in wp_options, and the cutover must not change either of them: woocommerce_custom_orders_table_enabled (which store is authoritative) and woocommerce_custom_orders_table_data_sync_enabled (whether the other store is kept in step, the "compatibility mode" of the settings screen). Both are checked in the 11.2.1 source and described on HPOS: High-Performance Order Storage.

The rules for a migration are:

wp wc hpos verify_data compares the two stores with each other; it does not compare the new site with the old one. For that the freeze report below records the order count, the highest order ID and the counts per status, and the check script prints the same numbers on the new side. A difference there is a missing or an extra order, and it is a no-go.

The freeze has four parts and their order is the point. Removing the crontab first stops the system cron from starting new queue runs; maintenance mode stops customers and, as a consequence, the web runners; draining waits for a run that began before the freeze to finish; the report records the final state. A queue run that is still in progress during the dump leaves rows with status in-progress in the copy, and on the new side such a row is reset or marked failed only after the timeout (300 seconds by default, filters action_scheduler_timeout_period and action_scheduler_failure_period, checked in the source), so an action that was half way through is retried late or reported as failed.

Source: Action Scheduler: WP CLI

Source: WP-CLI Commands: wp maintenance-mode

Three details of the script are worth stating:

A word on cancelling instead of draining. It is tempting to run wp action-scheduler action cancel --all for the hooks of the store and recreate them later. Do not: cancelling loses the recurring schedules of Subscriptions, of your extensions and of WooCommerce itself (woocommerce_cleanup_sessions, woocommerce_scheduled_sales, the unpaid-order cancellation), and not every extension re-creates its own on activation. The safe model is that pending actions are data and they move.

This is the one failure that no checksum catches, because both databases are consistent: a renewal due at 10:00 runs on the old server from its copy of the queue and on the new site from the copy it received, and the customer is charged twice, or receives two e-mails, or the ERP receives two orders. WooCommerce delivers its own webhooks through the action woocommerce_deliver_webhook_async in the group woocommerce-webhooks (checked in the source), so even an outgoing webhook is an Action Scheduler action. The new database holds the old pending actions from the moment the first DMS row is applied, so the rule applies before the cutover as well as after:

On the rehearsal copy, an even stronger safeguard is to change the outbound side: use the gateway’s test keys, a mail sink instead of SES, and webhooks that point at a sink. Never import a production dump into a cluster with production keys and a running worker.

Source: Action Scheduler: WP CLI

Source: Kubernetes Docs: CronJob

The chart of the store is built the way lumenpress-wordpress is on Deploying on EKS with Helm, with the helper prefix pc.*, so the suspended CronJob and the zero-replica worker are values (for example a cutover flag) rather than manual patches in a real pipeline; the commands above are the manual equivalent for a first migration. Once the worker runs, the backlog of actions that fell due during the freeze starts: a few hundred emails and renewals within a minute is normal, but a gateway can rate-limit, so watch the failed count of wp action-scheduler status for the first hour and keep the batch size modest (see the worker page).

WooCommerce Subscriptions is a paid extension and was not available to this page, so what follows is the generic mechanism from its public documentation and the Action Scheduler behaviour checked in the source. Verify each point with your version of the extension and the documentation of your gateway before the move.

Who triggers a renewal. According to the documentation, an automatic renewal is charged by Subscriptions through the gateway used for the original purchase, without customer action; a manual renewal puts the subscription on hold and creates an order that the customer has to pay. The trigger is a scheduled action: the documentation names the event woocommerce_scheduled_subscription_payment in Action Scheduler, and the existing page Subscriptions, Memberships and Bookings lists the hooks. So for the store-side model (the store holds a payment token and asks the gateway to charge it when the action runs) the queue is the clock: whichever side runs the action charges the customer. A gateway-side model, where the gateway itself bills on its own schedule and notifies the store by webhook, moves the clock to the gateway, and then the webhook URL is the point that matters. Which model your gateway extension uses is in its own documentation; this page does not know your gateway.

What happens to renewals due during the freeze. They stay pending, past due, on the old server and in the copy. After the worker starts they run in order and the customer is charged late by at most the length of the window. That is the right behaviour for an automatic renewal; for a gateway-side model the gateway may have charged on time and the webhook is retried (next section), so the late arrival is a notification, not a charge.

The "staging mode" safeguard, and why it does not protect a cutover. The documentation "How Subscriptions Handles Staging Sites and Migrations" explains that Subscriptions stores an obscured copy of the site URL in the option wc_subscriptions_siteurl and, when the current URL differs, runs the site in staging mode, which turns off automatic payments and subscription e-mails (the renewal and expiry events still fire). Two consequences are specific to a migration:

After the switch, check on the new side: the Subscriptions mode is live, the next payment dates of a handful of subscriptions are unchanged, and the first renewals after the freeze produce one renewal order each (a duplicate renewal order for the same subscription and date means two queues ran).

A payment gateway notifies the store of a payment or a refund by calling a URL on the store. WooCommerce builds the classic form with WC()->api_request_url( 'ClassName' ): https://www.pocketcoffee.example/wc-api/classname/ with pretty permalinks and https://www.pocketcoffee.example/?wc-api=classname with plain ones (checked in class-woocommerce.php). The request is answered by an action named woocommerce_api_ followed by the lowercase class name, and WooCommerce answers 400 when nothing is hooked to it (checked in LegacyRestApiStub.php). Other gateways register a REST route under /wp-json/ instead, or let the gateway extension create the webhook in the gateway dashboard itself. The inventory shows what your store has:

Source: WooCommerce docs: Working with webhooks in WooCommerce

What to do depends on one question:

During the freeze the old store answers with the maintenance status, 503. Gateways treat a non-success answer as a failed delivery and retry; the retry schedule and its end are specific to each gateway and are in its documentation, so check that the window is shorter than the retry period of every gateway you use. This is the reason to keep the window short and to announce it, not to point DNS at a server that answers 200 and drops the call.

Outbound webhooks of WooCommerce itself are rows in wp_wc_webhooks and travel with the database. A WooCommerce webhook is disabled after repeated failures (the limit is five by default, filter woocommerce_max_webhook_delivery_failures, checked in the source), so a receiver that was unreachable from the new cluster during the first minutes (a security group, an allow-list that lists the old server’s public IP) can silently disable the webhook. List them with wp wc webhook list after the switch and re-activate. Allow the NAT gateway addresses of the cluster on the receiving systems before the cutover; the fixed egress addresses are also what gateways with IP allow-lists will see.

Orders in pending status at the freeze. A customer who paid in the last minutes before the freeze may see a maintenance page instead of the thank-you page, and the order is still pending payment until the webhook arrives. Two pieces of core behaviour matter: the stock reservation of a pending order lasts woocommerce_hold_stock_minutes (60 minutes by default) and the action woocommerce_cancel_unpaid_orders, scheduled in the group woocommerce with the same interval, cancels unpaid orders when it next runs (both checked in the source). A window longer than the hold time, combined with a late webhook, can let the new site cancel an order that was in fact paid. After go-live reconcile in the gateway dashboard: every captured payment of the last day has a paid order, and every paid order has exactly one payment. This reconciliation is reasoning from the source, not something that was tested against a gateway.

The sequence below is the WordPress runbook with the store additions; the times are Pocket Coffee’s rehearsed ones and mean only that they were written down.

Source: Amazon Route 53 API Reference: ChangeResourceRecordSets

A test order in production data has a cost: it is an order for the accounting system and it triggers the outgoing webhooks. Mark it clearly, use a coupon you can exclude from reports, and cancel it. The alternative, a smoke test that only reads, is safer and covers less.

The WordPress page gives the generic table. The store makes the decision depend on one fact, whether the new site took an order.

Source: Kubernetes Docs: CronJob

Source: WP-CLI Commands: wp db query

Silence first, reopen second, in that order: the moment both sides are live they run both queues. A rollback after real orders is a data operation, not a switch, and the safest decision criteria are written before the window: for example a login or checkout failure rate above a threshold, or no healthy order within thirty minutes of the switch. Fixing forward is almost always faster than a reverse copy.