Multi-tenant migrations must be repeatable, observable, and safe to resume. A shared database needs one coordinated migration; database-per-tenant and sharded systems need the same migration applied across a fleet without losing track of versions.
Last updated: September 8, 2026.
CREATE TABLE schema_migrations (
version VARCHAR(50) PRIMARY KEY,
applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
checksum CHAR(64) NOT NULL
);Record each migration version and checksum in every database. A central tenant catalog can also record the current version, last attempt, and error for operational visibility.
Use expand-and-contract changes
First add the new table or nullable column while old code still works. Deploy application code that can handle both schemas, backfill data in bounded batches, switch reads to the new structure, and remove the obsolete structure in a later release. This avoids requiring every database and application instance to change simultaneously.
Run a controlled rollout
- Validate the migration against a representative copy and estimate locking and storage impact.
- Apply it to internal or canary tenants.
- Continue in small groups while monitoring latency, errors, locks, and replication.
- Pause automatically when thresholds are exceeded.
- Retry only migrations designed to resume safely.
Do not hand-edit one customer’s schema. If a tenant needs additional fields, model extensible data deliberately or move the customer to a supported service tier. The database tenancy model determines how large the migration fleet can become. Back up affected data and rehearse the restore path before destructive work. Test rollback timing too.
Prepare for support
Log the migration version, database or shard, affected tenant group, start and finish times, application release, and error. This information belongs with the operational history described in SaaS audit logging. Pause background workers that depend on an incompatible schema.
Microsoft’s multitenant data guidance recommends automated schema deployment, per-tenant version tracking, and application compatibility with at least one previous schema version.
