Architecture decision record · Accepted
Tenant data isolation: database per tenant
Context
An integration platform connects many banks to their core systems. Each bank is a tenant, and its configuration, credentials, logs and audit trail must be separated from every other tenant. Banks' security teams will ask exactly how. The platform is early stage, so the cost of the safest option is small today and large to retrofit later.
Decision
One PostgreSQL database per tenant, plus a small control database that stores only tenant metadata. The API reads the tenant from the authenticated token, looks it up in the control database and routes to that tenant's data source in one place. Migrations run against every tenant database automatically, and onboarding a tenant is a single scripted action.
Options considered
| Option | Strength | Weakness |
|---|---|---|
| Shared tables + tenant ID | Cheapest, simplest | One missed filter leaks data; weakest answer to a bank questionnaire |
| Schema per tenant | Better separation, per-tenant backup | Shared failure domain; migrations slow as tenants grow |
| Database per tenant | Strongest isolation, separate credentials, easy restore and deletion | More to operate; connection pooling and automation needed |
Consequences
Easier: answering security questionnaires, per-tenant backup and deletion, limiting the blast radius of a leaked secret. Harder: operating many databases, connection limits (a pooler such as PgBouncer may be needed), cross-tenant analytics, and testing that proves isolation. To revisit: pooling strategy, a lower-cost shared tier for low-risk tenants, and a regulatory review before any production tenant.
An engineering decision, not a compliance opinion.