The Tenant Database Mode setting in Site Settings is one of the most consequential decisions you'll make in a multi-tenant install. Switching modes later is possible but painful, so think carefully up front.
Shared database mode
All tenants share the same physical database. Each datastore that supports multi-tenancy has a tenantid column; ownership of each row is determined by that column. The platform automatically filters every query by the current tenant's ID.
From the application's perspective, each tenant sees only their own rows. The filtering is transparent — your code doesn't need to add WHERE tenantid clauses; the platform injects them automatically on the read path and stamps tenantid on the write path.
Separate database mode
Each tenant gets their own physical database. The platform manages the connection per-tenant — when a user is in tenant 123, the platform connects to am_tenant_123; when they switch (in admin-tenant-switching scenarios) to tenant 456, it switches to am_tenant_456.
Tenant databases follow a naming convention (typically am_tenant_{id}). When a new tenant is created, the platform creates the new database and copies the schema from a template database.
Comparing the two modes
Cost and infrastructure
Shared: one database server, one backup pipeline, one migration to run. Cheaper to operate at any scale.
Separate: one database per tenant. More backups, more migrations, but each independent. Higher infrastructure cost.
Isolation
Shared: logical isolation only. A bug in your tenant filtering (rare but possible) could expose one tenant's data to another. The platform's automatic filtering is robust but custom code that bypasses it is a risk.
Separate: physical isolation. Even a serious bug can't cross databases. Easier to satisfy compliance regimes (HIPAA, GDPR data residency, financial-services data segregation).
Performance
Shared: one tenant with very heavy load can affect others ("noisy neighbour"). Mitigations: per-tenant rate limiting, query timeouts, monitoring.
Separate: each tenant's database is independent. Noisy neighbour isn't an issue at the database level. Larger tenants can be put on more powerful database hosts.
Backup and restore granularity
Shared: backups are per-database (one backup, many tenants). Restoring one tenant's data from backup is hard — you'd need to extract their rows from the backup and re-import.
Separate: per-tenant backups are trivial. "Restore tenant X's database" is one command.
Migration complexity
Shared: one migration runs for all tenants simultaneously. Fast to deploy.
Separate: migrations have to run on every tenant database. Slower; needs orchestration. More likely that one tenant's migration fails while others succeed, leaving the install in mixed state.
Picking
Pick shared when:
- You're early-stage and want simplicity.
- You have many small tenants (100+).
- No compliance regime requires physical isolation.
- You're confident in the platform's tenant-filtering.
Pick separate when:
- You're in a regulated industry where compliance audits will examine isolation.
- You have fewer, larger tenants (under 50, each with 500+ users).
- Some tenants need data residency in specific regions.
- You're a managed-service provider where customers expect dedicated databases.
Note: You can mix the modes — shared by default, with separate databases for premium tenants. The platform supports this via Tenant Sharding, where each tenant has a configured "database host" that can point at either the shared host or a dedicated host. Common pattern for SaaS that wants to offer enterprise-tier customers physical isolation as an upgrade.