# Moving Tenants Between Shards — Multi-Tenant SaaS Architecture

Source: https://www.skillbyai.com/en/multi-tenant-saas/mt-tenant-rebalancing

> Plan a live tenant move between shards or into a silo using copy, catch-up, a short write freeze and a directory flip.

## A tenant move, step by step

Sooner or later you must move a tenant: a shard is too full, a tenant grew huge, or a customer upgraded to a dedicated database. Because placement lives in a directory, a move is a data operation. A typical online move goes: **copy** a snapshot of the tenant's rows to the target; **catch up** by replaying changes made since the snapshot, using change data capture or logical replication filtered to that tenant; **freeze writes** for that one tenant briefly (other tenants are unaffected) and let replication drain; **verify** with row counts or checksums; **flip** the directory entry so new requests go to the target; then, after a safety period, **delete** the old copy. Caches holding the old placement must be invalidated during the flip. Having `tenant_id` on every row is what makes this possible: you can select exactly one tenant's data from every table.

## Rehearse with a test tenant

Run the whole move against a synthetic tenant in production before touching a paying customer. Measure how long the write freeze really is, and have a rollback: flipping the directory back must be safe if verification fails.

## Shifting house

Moving a tenant is like shifting to a new flat. You pack and move most things over a few days, live in the old flat meanwhile, then on the final day pause, carry the last boxes, hand over the new address to the post office (the directory flip), and only then return the old keys.

**Quiz:** During an online tenant move, what is the purpose of the brief write freeze?

- [x] To let replication drain so the target has every change before the directory flips
- [ ] To delete the old copy before copying
- [ ] To stop all tenants on the shard from writing
- [ ] To rebuild every index on the source shard

*Answer:* To let replication drain so the target has every change before the directory flips. Freezing only that tenant's writes lets the last changes reach the target, so the flip loses nothing. Other tenants keep working, and deletion of the source comes last.