---
id: backend-multi-tenant-architecture
title: Multi-tenant — Pool / Silo / Bridge 모델
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [backend, multi-tenant, saas, vibe-coding]
tech_stack: { language: "TS / SQL", applicable_to: ["Backend"] }
applied_in: []
aliases: [multi-tenant, SaaS, tenant isolation, pool model, silo model, RLS]
---

# Multi-tenant Architecture

> 한 시스템 + 여러 고객 (조직). **Pool (공유 DB) / Silo (고객별 DB) / Bridge (혼합)**. 격리 강도 vs 운영 비용.

## 📖 핵심 개념
- Tenant: 사용자가 속한 조직.
- Pool: 모든 tenant 한 DB, tenant_id 컬럼.
- Silo: tenant 별 DB / namespace.
- Bridge: 큰 tenant 만 silo, 나머지 pool.

## 💻 코드 패턴

### Pool model (가장 단순)
```sql
CREATE TABLE orders (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  ...
);

-- 모든 query 에 tenant_id 필수
CREATE INDEX orders_tenant ON orders(tenant_id, created_at DESC);
```

```ts
// 강제 — request context 에서
async function ordersForTenant(req: Request) {
  return db.orders.findMany({ where: { tenantId: req.tenantId, ...rest } });
}
```

### RLS (Row Level Security)
```sql
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON orders
USING (tenant_id = current_setting('app.tenant_id')::UUID);
```

```ts
// 매 트랜잭션 시작 시
await db.execute(`SET LOCAL app.tenant_id = '${ctx.tenantId}'`);
// 이제 모든 query 가 자동 필터
```

→ 코드 실수해도 다른 tenant 못 봄.

### Schema-per-tenant (Postgres)
```sql
CREATE SCHEMA tenant_acme;
CREATE TABLE tenant_acme.orders (...);
-- 모든 테이블 동일 schema, tenant 별 분리
```

```ts
const schema = `tenant_${tenantId}`;
await db.execute(`SET search_path TO ${schema}, public`);
// 이후 query 가 자동 그 schema
```

### Database-per-tenant (Silo)
```ts
const tenantPools = new Map<string, Pool>();

async function getPool(tenantId: string): Promise<Pool> {
  if (!tenantPools.has(tenantId)) {
    const cfg = await getTenantDbConfig(tenantId);
    tenantPools.set(tenantId, new Pool(cfg));
  }
  return tenantPools.get(tenantId)!;
}

const db = await getPool(req.tenantId);
const orders = await db.query('SELECT * FROM orders');
```

### Tenant 식별
```ts
// 1. Subdomain
const tenant = req.hostname.split('.')[0]; // acme.example.com

// 2. Header (API)
const tenant = req.headers['x-tenant-id'];

// 3. JWT claim
const { tenantId } = verifyJwt(token);

// 4. Path
// /tenants/:slug/api/...
```

### Migration (모든 tenant)
```ts
// Pool: 한 번만 (모든 tenant 영향)
await runMigrations();

// Schema-per-tenant: 각 schema 마다
const tenants = await db.query('SELECT id FROM tenants');
for (const t of tenants) {
  await db.execute(`SET search_path TO tenant_${t.id}`);
  await runMigrations();
}

// DB-per-tenant: 각 DB
for (const t of tenants) {
  const pool = await getPool(t.id);
  await runMigrationsOn(pool);
}
```

### Backup / restore (silo 강점)
```bash
# Per-tenant backup
pg_dump -d tenant_acme > acme.sql

# 한 tenant 만 restore — 다른 영향 X
psql -d tenant_acme < acme.sql
```

→ Pool 모델은 row 단위 backup 어려움.

### Quota / limit (per-tenant)
```ts
const QUOTAS: Record<Plan, { storageGB: number; usersMax: number }> = {
  free: { storageGB: 1, usersMax: 5 },
  pro: { storageGB: 100, usersMax: 50 },
  enterprise: { storageGB: 1000, usersMax: -1 },
};

async function checkQuota(tenantId: string, type: 'storage' | 'users') {
  const t = await db.tenants.find(tenantId);
  const q = QUOTAS[t.plan];
  // ...
}
```

### Noisy neighbor 방지
- Rate limit per tenant.
- Connection pool per tenant (silo) 또는 limit per tenant (pool).
- Job queue: tenant 별 partition / fair scheduler.

```ts
const queue = new BullMQ('jobs');
queue.add('process', data, { jobId: `${tenantId}:${jobId}`, priority: priorityFor(plan) });
```

## 🤔 의사결정 기준
| 상황 | 모델 |
|---|---|
| 작은 SaaS, 많은 작은 tenant | Pool + RLS |
| Compliance 강함 (HIPAA, GDPR) | Silo (DB-per-tenant) |
| 큰 enterprise + small tenants 혼합 | Bridge (큰 = silo, 작은 = pool) |
| Customization 강함 | Schema-per-tenant 또는 silo |
| 자원 분리 필요 | Silo |
| 운영 단순 | Pool |

## ❌ 안티패턴
- **모든 query 에 tenant_id 누락 가능**: RLS 또는 ORM scope 강제.
- **Cross-tenant join 가능**: pool 의 위험. 권한 분리.
- **Silo + 비싼 idle pool**: connection 폭발. lazy / share.
- **Tenant context global mutable**: race. AsyncLocalStorage.
- **모든 tenant 동시 migration — 큰 lock**: 점진 / 병렬.
- **Plan 정보 매 query DB hit**: cache.
- **Tenant 삭제 = 못 함**: hard delete + cascade 또는 soft + 보존.

## 🤖 LLM 활용 힌트
- Pool + RLS = 단순한 안전.
- Silo = compliance / 큰 customer.
- Bridge = 두 세계.
- AsyncLocalStorage 로 tenant context 안전 전달.

## 🔗 관련 문서
- [[DB_Sharding_Strategies]]
- [[DB_Soft_Delete_Patterns]]
- [[Backend_Rate_Limiting]]