2nd/10_Wiki/Topic_Programming/Coding/Backend_Multi_Tenant_Architecture.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
backend-multi-tenant-architecture	Multi-tenant — Pool / Silo / Bridge 모델	Coding	draft	B	conceptual	2026-05-09	2026-05-09	backend multi-tenant saas vibe-coding	language applicable_to TS / SQL Backend		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 (가장 단순)

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);

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

RLS (Row Level Security)

ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

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

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

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

Schema-per-tenant (Postgres)

CREATE SCHEMA tenant_acme;
CREATE TABLE tenant_acme.orders (...);
-- 모든 테이블 동일 schema, tenant 별 분리

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

Database-per-tenant (Silo)

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 식별

// 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)

// 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 강점)

# 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)

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.

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