Multi-Tenancy in SaaS: Data Isolation with PostgreSQL
Citai Team
March 6, 2026 · 10 min read
What is multi-tenancy and why does it matter?
Multi-tenancy means multiple organizations (tenants) use the same application and infrastructure, but each sees only their data. It’s the standard SaaS model — one database, one server, but total isolation between customers.
Why not separate databases?
| Approach | Pros | Cons |
|---|---|---|
| Separate DBs | Physical isolation | Expensive, hard to maintain, N migrations |
| Schema per tenant | Good isolation | Complex, N migrations |
| tenant_id (Citai) | Simple, scalable, 1 migration | Requires query discipline |
Citai uses the tenant_id approach — same PostgreSQL database, but every record has a tenant_id guaranteeing logical isolation.
Isolation by tenant_id: no exceptions
Every table has a tenant_id column. Every query always filters by tenant.
Layer 1: Business data
SELECT * FROM knowledge_bases WHERE tenant_id = :current_tenant;
SELECT * FROM conversations WHERE tenant_id = :current_tenant;
Isolated tables: KBs, documents, chunks, FAQs, conversations, messages, feedback, usage logs, API keys, widget sessions.
Layer 2: Metrics and analytics
Per-tenant. A tenant_admin’s dashboard shows only their organization’s data.
Layer 3: Super admin isolation
Hierarchical role system
| Role | Scope | Can see |
|---|---|---|
| super_admin | Platform | Tenants, plans, aggregate revenue, global config |
| tenant_admin | Organization | KBs, users, analytics, RAG config, API keys |
| member | Their access | Chat, assigned KBs (public + their groups) |
KB access control
Within each tenant: Public (all members), Private (creator + admins), Groups (specific group members).
Anti-fraud plan enforcement
| Resource | Free | Starter | Pro |
|---|---|---|---|
| AI queries/month | 50 | 500 | 5,000 |
| Knowledge bases | 2 | 5 | 20 |
| Documents | 10 | 50 | 500 |
| API keys | 1 | 3 | 10 |
Atomic counters
Usage counters use atomic UPSERT to prevent race conditions. Counters only increment (never decrement). Redis handles SSE streaming concurrency. Over limit → HTTP 403 + upgrade_required event. FAQs are always free.
Additional security
- API keys: SHA-256 hashed storage
- Email tokens: Hashed (forgot password, verification, invites)
- JWT rotation: Access 30min, refresh 7d with rotation
- Rate limiting: Redis sliding window on sensitive endpoints
Enterprise security from the Free plan. Create account →
Try Citai for free
Create your intelligent knowledge base in minutes. No credit card required.
Create free accountRelated articles
AI Chatbot Security: 2FA, OAuth, Headers and More
Complete security guide for AI assistants: multi-factor authentication, OAuth, HTTP headers, API key hashing, and rate limiting.
Read article → Practical GuideGDPR and Privacy in AI Assistants: A Practical Guide
How to comply with GDPR when deploying AI chatbots: data portability, right to erasure, retention, and auditing.
Read article → TechnologyAudit Logging: Complete Traceability for AI Compliance
How audit logs in Citai enable complete action traceability, regulatory compliance, and forensic analysis.
Read article →