Loading

Changing Modes

Changing database mode is a migration of every tenant’s data. It is a project, not a setting.

Where to find it

Architect Panel → Configuration:

  • Multitenancy — the tenants themselves
  • Custom Tenant Information Fields — your own fields on a tenant
  • Instance Configuration Fields — settings held per tenant

Architect Panel → Integration & Connections:

  • Database Hosts — where tenant databases live

Architect Panel → Integration & Connections:

  • Deployments — the application versions involved

Why it is hard

The mode determines where every row lives. Moving from shared to separate means extracting each tenant’s rows into a new database and confirming nothing was missed or duplicated. Moving the other way means merging, with the additional problem of colliding identifiers.

Shared to separate is the easier direction

Because you are splitting rather than merging, and each tenant can be verified independently. It is still substantial, and it still needs every tenant checked.

Separate to shared is the harder one

Identifiers that were unique within a database are no longer unique once merged, and every reference between rows has to survive the remapping. This is where a migration goes quietly wrong — a foreign key pointing at the right number in the wrong tenant.

The approach

  1. Take a full backup and confirm you can restore it.
  2. Rehearse the whole thing on a copy, end to end.
  3. Count everything before — rows per table per tenant.
  4. Migrate one tenant, verify it thoroughly, and use what you learn.
  5. Migrate the rest in batches, verifying each.
  6. Count again and compare.
  7. Have every tenant confirmed before switching the application over.

Count rows, then check meaning

Counts catch missing data. They do not catch data attributed to the wrong tenant, which is the failure that matters most. Check a sample of records in each tenant against what that customer should actually have.

Plan the outage honestly

Data cannot be written while it is being moved. Tell customers the real window rather than an optimistic one, and pick a time that suits them rather than you.

Know when to stop

Define in advance what would make you roll back, and who decides. A migration in trouble at three in the morning is the worst possible moment to be forming that judgement.

Consider whether you need to

Mode changes are usually prompted by a requirement that might have another answer — a customer wanting isolation might be served by moving to a dedicated host under sharding, without changing the mode for everybody.

Worked example

A platform moving from shared to separate rehearsed the whole migration on a restored copy, migrated one willing customer first, then proceeded in batches of five with row counts compared before and after and a sampled records check per tenant. The rehearsal found a table that had been missed entirely.

Recommendations

  • Rehearse on a restored copy, completely.
  • One tenant first, verified thoroughly.
  • Count rows and check meaning — counts alone are not enough.
  • Define the rollback trigger and who decides.