Data migration¶

Moving the marketplace data plane between Shopware's MySQL and the cluster's MySQL — the only correct way to change dataLocation. Requires Remote.

Never flip dataLocation by hand

Editing the dataLocation dropdown (or the cluster's db.connection.active) without moving the data points Base at an empty or stale database. Always use the migration commands — they move the data and flip the selector atomically, behind a maintenance gate.

The commands¶

Command	Direction
`marketplace:data:migrate:to-cluster`	Shopware MySQL → cluster MySQL, then `dataLocation=cluster`.
`marketplace:data:migrate:to-shopware`	Cluster MySQL → Shopware MySQL, then `dataLocation=shopware`.

Options (both): --drop-source truncates the source tables after a verified move; -y skips the confirmation prompt.

php bin/console marketplace:data:migrate:to-cluster          # interactive
php bin/console marketplace:data:migrate:to-cluster -y       # unattended
php bin/console marketplace:data:migrate:to-cluster --drop-source

How it runs — 10 resumable steps¶

Each command runs ten steps in order, persisting progress to var/marketplace/migration.state. If a step fails, rerun the same command — it resumes from the failing step rather than starting over.

1  schema_check        compare data-plane table shapes source vs target;
                       abort on drift (collation diffs only warn)
2  set_maintenance     set the maintenance flag — mutating Requests are
                       rejected, reads continue
3  dump_tables         mysqldump --single-transaction --no-create-info
                       the data-plane tables → var/marketplace/migration.sql
4  import_tables       TRUNCATE target tables, stream the dump in with
                       FOREIGN_KEY_CHECKS=0 bracketing
5  integrity_check     per-table row counts + a PK spot-check
                       (≤8 random PKs/table, full-row byte compare)
6  flip_data_location  rewrite cluster db.connection.active AND Shopware
                       dataLocation in lockstep
7  restart_cluster     run clusterRestartCommand, poll the channel port
                       until reachable (30s deadline)
8  smoke_test          shell out to marketplace:ping in a fresh process
                       (clean new TCP socket)
9  drop_source_tables  only if --drop-source was passed
10 clear_maintenance   lift the gate

The maintenance gate¶

While the migration runs (steps 2–10), the maintenance flag is set. With it set, RemoteMarketplaceBackend rejects mutating Requests but still serves reads — sellers can browse, but writes pause until the move completes. The final step clears it. This is why a migration causes a brief write freeze, not a full outage.

Before you migrate¶

Match the schemas. Step 1 aborts on any column/type/nullability drift. Run marketplace:local:schema:apply (Shopware side) and the cluster's setup so both ends declare the same flyokai_* tables first.
Confirm the restart command works. Step 7 polls the channel port for 30s; if your clusterRestartCommand doesn't actually bring the cluster back (or needs sudo you don't have), the migration stalls here.
Have headroom on the target MySQL. The dump is imported wholesale.

If it stalls¶

Because state is persisted, recovery is just rerun the same command:

Symptom	Likely step	Fix
"schema drift" abort	1	Apply the schema on both ends, rerun.
Import errors	4	Check target MySQL space / grants; rerun.
Integrity mismatch	5	Investigate source churn; rerun (it re-dumps).
Ping fails after restart	7–8	Stale workers on 1339/1439 (`ss -lntp`); fix, rerun.

The gate stays set until step 10, so a half-finished migration fails safe (writes blocked) rather than splitting data across two databases.

Verifying afterwards¶

php bin/console marketplace:ping     # backend + seller count

A green ping after to-cluster means Base is now reading/writing the cluster's MySQL. To go back, run marketplace:data:migrate:to-shopware — same machinery, opposite direction.