Enabling Tenant Sharding

Tenant sharding distributes tenant databases across multiple database hosts — useful once a single MySQL server can no longer handle the load, or when you need regional database hosts for data-residency compliance.

When to shard

You'll know it's time when one of these is true:

• You have hundreds of tenants and a single DB is slowing down — query latency rises, concurrent-connection counts hit limits, the DB host is CPU-bound.
• Some tenants are dramatically larger than others and you want to isolate them — premium customers on dedicated database hosts, free-tier customers on shared infrastructure.
• You want regional database hosts so EU tenants live on EU servers, US tenants on US servers, etc. — typically driven by GDPR-style data-residency requirements.
• You're approaching the storage limits of a single MySQL server (millions of rows × hundreds of tenants × many years of history adds up).

Enabling sharding

Three steps:

1. Add the additional Database Hosts

From the Architect Panel → Database Hosts, add an entry for each additional MySQL/MariaDB server you want to use. Each host has its own hostname, port, credentials, and SSL settings.

Typical patterns:

• Host 1: the original DB (typically remains the master tenant's host).
• Host 2: a US-region DB for US tenants.
• Host 3: an EU-region DB for EU tenants.
• Hosts 4+: additional shards for capacity overflow.

2. Toggle Enable Tenant Sharding in Site Settings

Under Site Settings → Tenant. Once enabled, the platform routes each tenant's database connection to its configured host.

3. Assign tenants to hosts

Each tenant has a databasehost_id column on the .tenants table. Set this to the ID of the host the tenant should live on. New tenants get the default host (typically Host 1) unless you explicitly assign them elsewhere.

Moving existing tenants to a new shard

If you're sharding an existing install, you'll need to move some tenants off the original host. The general procedure:

1. Take a backup of the tenant's database on the source host.
2. Restore the backup to the target host.
3. Update the tenant's databasehost_id in .tenants to point at the new host.
4. Verify the tenant works correctly on the new host (test user logins, sample queries, etc.).
5. After confirming, drop the database from the original host to free space.

Plan a maintenance window for this — there's no zero-downtime tenant migration built into the platform.

Operational considerations

Backups

Each host needs its own backup pipeline. The platform's own backup tools (if you use them) need to be configured per-host.

Migrations

Schema migrations now have to run on every host. Make sure your migration orchestration handles this — run on Host 1, verify, run on Host 2, etc.

Monitoring

Monitor each host independently. A capacity problem on Host 2 doesn't surface in Host 1's metrics.

Cross-host queries

The platform doesn't support cross-host JOINs. Any query that needs data from multiple tenants on different hosts has to fetch each side separately and join in PHP. Plan reports and dashboards accordingly.

Warning: Sharding is a one-way door for most installs. Once tenants are spread across multiple hosts, going back to a single-host setup means a big migration. Don't enable sharding speculatively; wait until you have a concrete reason and have done the capacity-planning work to confirm it's the right move.