Multi-Tenant Architecture

Silo, bridge and pool isolation models, tenant context propagation, noisy-neighbour controls and tenant-aware operations for SaaS.

Intent

Serve many customers (tenants) from shared infrastructure and code while keeping their data, performance and configuration isolated. See the full case study: Multi-Tenant B2B SaaS Platform.

Isolation models

Model Compute Data Isolation Cost per tenant
Silo Dedicated stack Dedicated DB Strongest Highest
Bridge Shared compute Schema or DB per tenant Medium Medium
Pool Shared Shared tables with tenant_id Weakest (logical) Lowest
flowchart LR
  subgraph Pool
    A1[Shared services] --> DB1[(Shared DB<br/>tenant_id + RLS)]
  end
  subgraph Bridge
    A2[Shared services] --> S1[(Schema T1)]
    A2 --> S2[(Schema T2)]
  end
  subgraph Silo
    A3[Stack T3] --> D3[(DB T3)]
  end

Java example: tenant context propagation

public final class TenantContext {
    private static final ScopedValue<String> TENANT = ScopedValue.newInstance();   // Java 25: final
    public static String current() { return TENANT.orElseThrow(() -> new IllegalStateException("no tenant")); }
    public static void run(String tenantId, Runnable r) { ScopedValue.where(TENANT, tenantId).run(r); }
}

@Component
class TenantFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain) {
        var jwt = (Jwt) SecurityContextHolder.getContext().getAuthentication().getPrincipal();
        String tenant = jwt.getClaimAsString("tenant_id");          // from verified token only
        TenantContext.run(tenant, () -> {
            try { chain.doFilter(req, res); } catch (Exception e) { throw new RuntimeException(e); }
        });
    }
}

[!VERSION] ScopedValue became final in Java 25 (JEP 506). On Java 21 use ThreadLocal (with care for virtual threads) or the preview API.

Pros and cons

Pros Cons
Economies of scale; one codebase Isolation bugs can leak data across tenants
Fast onboarding Noisy neighbours
Single upgrade for all tenants Tenant-specific requirements pressure the shared design

Interview questions

How do you choose between pool and silo?

By tenant size, compliance/residency needs, customization, price tier and operational cost. Many SaaS products offer pooled tiers by default and silo as a premium enterprise option.

How do you handle per-tenant backups and restore in a pooled database?

Snapshot the shared database, restore to a side instance, extract the tenant's rows by tenant_id, and merge back carefully; or design data export/import per tenant from the start. Silo tenants get native per-database PITR.