> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Use cases

> Practical examples of when to choose DATABASE versus SCHEMA isolation in Lerian multi-tenancy, plus a step-by-step migration path between the two modes.

Choosing an isolation mode is a trade-off between **isolation strength** and **operational cost**. This page walks through two realistic scenarios — one for each mode — and shows how a deployment can start in one mode and migrate to the other as it grows.

For the full mode comparison, see [Isolation modes in Multi-tenancy](/en/multi-tenancy#isolation-modes).

## When to choose each mode

***

<CardGroup cols={2}>
  <Card title="DATABASE mode" icon="database">
    Maximum isolation — a separate database per tenant. Best when tenants are large, regulated, or sensitive to noisy neighbors and you can absorb higher per-tenant cost.
  </Card>

  <Card title="SCHEMA mode" icon="layer-group">
    Efficient isolation — a separate schema per tenant inside a shared database. Best for many smaller tenants where density and cost efficiency matter most.
  </Card>
</CardGroup>

## Example 1 — Regulated, high-volume fintech

***

**"Banco ACME"** is a licensed financial institution processing a high volume of transactions under strict regulatory oversight.

**Requirements:**

* Strong physical isolation to satisfy auditors and regulators.
* The smallest possible blast radius — an incident affecting one tenant must not touch others.
* The ability to back up and restore a single tenant independently, including point-in-time recovery.
* Predictable performance under heavy, sustained load.

**Recommended mode: `DATABASE`**

Banco ACME runs in `DATABASE` mode. Each tenant gets a dedicated PostgreSQL database, so:

* Physical isolation is complete — there is no shared schema surface between tenants.
* The blast radius of any failure, migration, or restore is confined to a single tenant.
* A selective restore touches only the affected tenant's database, with no impact on others.
* Performance isolation is strong, since tenants do not share table space or contend within the same database.

<Note>
  The higher per-tenant infrastructure cost of `DATABASE` mode is justified here by the regulatory and isolation requirements — and by transaction volumes that would make performance isolation valuable on its own.
</Note>

## Example 2 — Early-stage startup

***

**"FinX"** is an early-stage startup onboarding many small customers quickly, with tight cost constraints and modest per-tenant volume.

**Requirements:**

* Low cost per tenant to support a large number of small accounts.
* Fast onboarding of new tenants.
* Good-enough isolation for the current stage, with room to harden later.

**Recommended mode: `SCHEMA`**

FinX runs in `SCHEMA` mode. Each tenant gets a dedicated schema inside a shared PostgreSQL database, so:

* Infrastructure cost stays low because tenants share a database instance.
* Tenant data is still logically isolated — one tenant's schema is never reachable from another's.
* Onboarding is lightweight, which suits a high rate of small-tenant signups.

<Warning>
  `SCHEMA` mode shares a database instance across tenants, so the blast radius of a database-level incident is wider and performance isolation is weaker than in `DATABASE` mode. Plan to migrate high-value or high-volume tenants as they grow.
</Warning>

### A migration path as FinX grows

When one of FinX's tenants becomes large, regulated, or performance-sensitive, FinX can migrate that tenant from `SCHEMA` to `DATABASE` mode — without re-issuing tokens or changing the tenant's identity, because isolation is a property of the *service*, not the tenant.

<Steps>
  <Step title="Identify the tenant to promote">
    Pick the tenant whose volume, risk profile, or compliance needs now justify a dedicated database.
  </Step>

  <Step title="Provision a dedicated database">
    The platform provisions a new isolated PostgreSQL database for the tenant and runs migrations, exactly as in [automatic provisioning](/en/multi-tenancy/auto-provisioning).
  </Step>

  <Step title="Migrate the tenant's data">
    The tenant's data is moved from its shared-database schema into the new dedicated database.
  </Step>

  <Step title="Repoint the service">
    The tenant's service registration is updated to the `DATABASE`-mode configuration. The `tenantId` claim is unchanged, so integrations continue working without modification.
  </Step>
</Steps>

<Tip>
  Starting in `SCHEMA` mode and promoting individual tenants to `DATABASE` mode lets you keep costs low early and reserve dedicated databases for the tenants that actually need them.
</Tip>

## Related pages

***

<CardGroup cols={2}>
  <Card title="Multi-tenancy" icon="layer-group" href="/en/multi-tenancy" cta="Compare modes">
    The full DATABASE vs. SCHEMA comparison and migration flow.
  </Card>

  <Card title="Automatic provisioning" icon="wand-magic-sparkles" href="/en/multi-tenancy/auto-provisioning" cta="See provisioning">
    How a tenant's infrastructure is provisioned and migrated.
  </Card>

  <Card title="Automatic provisioning" icon="wand-magic-sparkles" href="/en/multi-tenancy/auto-provisioning" cta="See provisioning">
    Why isolation is a property of the service, not the tenant.
  </Card>

  <Card title="Security" icon="shield-halved" href="/en/midaz/security" cta="Read guarantees">
    Isolation and credential guarantees for both modes.
  </Card>
</CardGroup>