---
title: "Choose the isolation model before the · Agent Wranglers"
url: https://agentwranglers.se/playbook/data/multi-tenancy/tenant-isolation-model
id: DAT-67
level: Recommended
updated: 2026-10-22
tokens: 987
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Choose the isolation model before the first customer

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Multi-tenancy](https://agentwranglers.se/playbook/data/multi-tenancy.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: DAT-67
- Level: Recommended
- Chapter: [Multi-tenancy](https://agentwranglers.se/playbook/data/multi-tenancy.md)
- Rule: Write down where each customer's data lives, in shared tables, a schema per tenant or a database per tenant. Record the reason and the tenant count it must reach.
- Check: The repository holds a decision record that names the model, the reason and the target tenant count. The `tenants` table has a non-null column for the model and the database or schema of each tenant. A test creates a tenant in each model the code supports and reads a row back through the normal app code.
- How: Shared tables with a tenant column and row-level security, as [Keep each customer's data apart](https://agentwranglers.se/playbook/data/schema-design/tenant-isolation.md) shows, suit most apps. They need one migration, one connection pool and one backup. A schema per tenant gives cleaner restores and exports, but every migration runs once per schema. Past a few thousand schemas, catalog size slows tools and backups. A database per tenant gives the strongest separation, its own keys, region and restore. It also costs one connection pool, one backup and one upgrade per customer, so automate all three first. Many apps mix models, keeping small tenants in shared tables and moving a large or regulated customer to its own database. Store the model per tenant in a `tenants` table, so code reads where a tenant lives instead of assuming it. Keep the organisation as the owner of the data, as [Let organisations own the shared data](https://agentwranglers.se/playbook/accounts/organisations-and-teams/organisation-owns-data.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### SQL example

```sql
CREATE TABLE tenants (
  id            bigint PRIMARY KEY,
  slug          text NOT NULL UNIQUE,
  isolation     text NOT NULL CHECK (isolation IN ('shared', 'schema', 'database')),
  location      text NOT NULL,          -- schema name or connection name
  region        text NOT NULL,
  created_at    timestamptz NOT NULL DEFAULT now()
);
```

## Sources

- [AWS SaaS Tenant Isolation Strategies](https://docs.aws.amazon.com/whitepapers/latest/saas-tenant-isolation-strategies/saas-tenant-isolation-strategies.html)
- [OWASP Multi-Tenant Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Multi_Tenant_Security_Cheat_Sheet.html)

## Related rules

- DAT-7 [Keep each customer's data apart](https://agentwranglers.se/playbook/data/schema-design/tenant-isolation.md) in Data and databases
- ACC-41 [Let organisations own the shared data](https://agentwranglers.se/playbook/accounts/organisations-and-teams/organisation-owns-data.md) in Accounts and identity
- DAT-73 [Find and contain noisy neighbours](https://agentwranglers.se/playbook/data/multi-tenancy/noisy-neighbours.md) in Data and databases

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/data/multi-tenancy/tenant-isolation-model">Agent Wranglers data and databases playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Run every background job inside its tenant](https://agentwranglers.se/playbook/data/multi-tenancy/tenant-context-in-jobs.md)
- [Multi-tenancy](https://agentwranglers.se/playbook/data/multi-tenancy.md)