Skip to main content

Multi-Tenant SaaS Architecture: Complete Guide

Executive Summary​

Multi-tenant SaaS architecture enables multiple customers (tenants) to share the same application instance while maintaining data isolation, security, and performance.

1. Architectural Patterns​

Option A: Single Database, Shared Schema (BEST FOR STARTUPS)​

All tenants share the same database and tables, distinguished by a tenant_id column.

Pros:

  • Simplest to implement
  • Best resource utilization
  • Easy to scale horizontally
  • Lowest operational overhead

Cons:

  • Most vulnerable to data leakage
  • Limited data isolation
  • Complex backup/restore per tenant

Best For: SaaS with many small tenants (0-1000), startups

-- All tables include tenant_id
CREATE TABLE users (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
email VARCHAR(255),
INDEX idx_tenant_email (tenant_id, email)
);

-- EVERY query must filter by tenant_id
SELECT * FROM users WHERE tenant_id = 'abc-123';

Option B: Single Database, Separate Schemas​

One database with separate schemas/namespaces per tenant.

Pros:

  • Better data isolation
  • Per-tenant customization possible
  • Easier compliance

Cons:

  • Limited by database schema count
  • Migration complexity
  • Higher operational overhead

Best For: Medium-sized tenants (100-500), industries with compliance


Option C: Separate Database per Tenant (FOR ENTERPRISE)​

Each tenant gets their own dedicated database instance.

Pros:

  • Maximum data isolation
  • Best performance isolation
  • Simplest compliance
  • Independent scaling per tenant

Cons:

  • Highest operational cost
  • Complex connection pooling
  • Resource underutilization

Best For: Enterprise/large tenants, high-security requirements


2. Tenant Resolution Strategies​

URL: tenant1.yourapp.com
↓
Extract: tenant1
↓
Store: req.tenantId = 'tenant1'

Best For: Public-facing SaaS platforms

// Login response includes tenant info
{
"token": "eyJhbGci...",
"user": {
"id": "user-123",
"tenantId": "acme-corp"
}
}

Best For: API-first applications, mobile apps

Option 3: Custom Domain (Enterprise)​

User visits: acme.com
↓
DNS CNAME → yourapp.com
↓
Lookup: which tenant owns acme.com?

Best For: Enterprise customers


3. Data Isolation & Security (CRITICAL)​

Row-Level Security (RLS) - PostgreSQL​

-- Step 1: Enable RLS
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;

-- Step 2: Create isolation policy
CREATE POLICY tenant_isolation ON projects
USING (tenant_id = current_setting('app.current_tenant'));
// Set tenant context in middleware
app.use(async (req, res, next) => {
await db.query(`SET LOCAL app.current_tenant = $1`, [req.tenantId]);
next();
});

Query-Time Enforcement (ALWAYS DO THIS)​

// ✅ CORRECT: Always filter by tenant_id
const projects = await db.query(
'SELECT * FROM projects WHERE tenant_id = ?',
[currentTenant.id]
);

// ❌ NEVER: Query without tenant filter
const projects = await db.query('SELECT * FROM projects'); // DANGER!

Application-Level Protection​

// Middleware to protect ALL routes
function requireTenantAccess(req, res, next) {
const resourceTenantId = req.resource.tenant_id;
const userTenantId = req.user.tenant_id;

if (resourceTenantId !== userTenantId) {
return res.status(403).json({ error: 'Access denied' });
}
next();
}

Caching Strategy (SUPER IMPORTANT)​

// ✅ CORRECT: Tenant-aware cache keys
const cacheKey = `tenant:${tenantId}:projects:${projectId}`;

// ❌ NEVER: Shared cache keys
const cacheKey = `project:${projectId}`; // DATA LEAK RISK!

// Always include tenant in cache operations
redis.get(`tenant:${req.user.tenantId}:data`);
redis.set(`tenant:${req.user.tenantId}:data`, data);

4. Multi-Tenant Authentication​

User Identity Structure​

{
"id": "user-123",
"email": "john@acme.com",
"tenant_id": "acme-corp",
"tenant_role": "admin"
}

Domain-Based Login​

app.post('/login', async (req, res) => {
const { email, password } = req.body;
const subdomain = extractSubdomain(req); // "acme" from acme.yourapp.com

// Verify user belongs to THIS tenant
const user = await db('users')
.where({ email, tenant_id: subdomain })
.first();

if (!user || !verifyPassword(password, user.password)) {
return res.status(401).json({ error: 'Invalid credentials' });
}

// Create session with tenant context
req.session.userId = user.id;
req.session.tenantId = subdomain;

res.json({ success: true, tenantId: subdomain });
});

JWT with Tenant Info​

// Login endpoint
app.post('/login', async (req, res) => {
const { email, password, tenantId } = req.body;

const user = await db('users')
.where({ email, tenant_id: tenantId })
.first();

if (!user || !verifyPassword(password, user.password)) {
return res.status(401).json({ error: 'Invalid credentials' });
}

// JWT includes tenant info
const token = jwt.sign(
{ userId: user.id, tenantId: user.tenant_id },
process.env.JWT_SECRET,
{ expiresIn: '24h' }
);

res.json({ token });
});

// Protected route middleware
function authenticateJWT(req, res, next) {
const token = req.headers.authorization?.split(' ')[1];
jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
if (err) return res.status(401).json({ error: 'Invalid token' });
req.user = decoded;
next();
});
}

5. Scalability Considerations​

Database Scaling​

Read Replicas​

[App Server]
↓
[Primary DB] ← Writes only
↓ Replication
[Replica 1] ← Reads
[Replica 2] ← Reads
// Route reads to replicas, writes to primary
const primaryPool = new Pool({ connectionString: PRIMARY_DB_URL });
const replicaPool = new Pool({ connectionString: REPLICA_DB_URL });

// Write operations
await primaryPool.query('INSERT INTO projects...');

// Read operations
const projects = await replicaPool.query(
'SELECT * FROM projects WHERE tenant_id = $1',
[tenantId]
);

Connection Pooling​

const { Pool } = require('pg');

const pool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 20, // Max 20 concurrent connections
idleTimeoutMillis: 30000, // Close idle after 30s
connectionTimeoutMillis: 2000 // Timeout after 2s
});

Per-Tenant Connection Limits (Stop Noisy Neighbors)​

const tenantPools = new Map();

function getTenantPool(tenantId, plan) {
if (!tenantPools.has(tenantId)) {
const limits = { free: 2, pro: 5, enterprise: 20 };
tenantPools.set(tenantId, new Pool({
connectionString: process.env.DATABASE_URL,
max: limits[plan] || 2
}));
}
return tenantPools.get(tenantId);
}

Application Scaling​

Stateless Servers (Scale Horizontally)​

// Session stored in Redis (not in server memory!)
app.use(session({
store: new RedisStore({ client: redis }),
secret: process.env.SESSION_SECRET,
resave: false,
saveUninitialized: false
}));

// Add servers anytime - no session data lost!

Noisy Neighbor Prevention​

// Rate Limiting Per Tenant
const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
keyGenerator: (req) => req.user?.tenantId, // Key by tenant!
max: 1000, // 1000 requests
windowMs: 60 * 1000 // per minute
});

app.use(limiter);

// Resource Quotas
const tenantQuotas = {
free: { storage: '5GB', apiCalls: 10000 },
pro: { storage: '50GB', apiCalls: 100000 },
enterprise: { storage: 'unlimited', apiCalls: 'unlimited' }
};

Caching Layer​

function cache(key, ttlSeconds, fetchFn) {
const cacheKey = `tenant:${tenantId}:${key}`;

const cached = await redis.get(cacheKey);
if (cached) return JSON.parse(cached);

const data = await fetchFn();
await redis.setex(cacheKey, ttlSeconds, JSON.stringify(data));
return data;
}

// Usage
const projects = await cache('projects', 300, () =>
db('projects').where({ tenant_id: tenantId })
);

Queue Workers​

const Queue = require('bull');
const emailQueue = new Queue('email', { redis: { port: 6379 } });

// Add job with tenant context
await emailQueue.add('send-welcome', { userId, tenantId });

// Process (with tenant validation)
emailQueue.process(async (job) => {
const { userId, tenantId } = job.data;

// Always validate tenant!
const tenant = await db('tenants').where({ id: tenantId }).first();
if (!tenant) throw new Error('Invalid tenant');

await sendWelcomeEmail(userId);
});

6. Migration: Single-Tenant → Multi-Tenant​

Phase 1: Database Changes (Week 1)​

-- Add tenant_id to all tables
ALTER TABLE users ADD COLUMN tenant_id UUID;
ALTER TABLE projects ADD COLUMN tenant_id UUID;
ALTER TABLE tasks ADD COLUMN tenant_id UUID;

-- Add indexes (CRITICAL for performance!)
CREATE INDEX idx_users_tenant ON users(tenant_id);
CREATE INDEX idx_projects_tenant ON projects(tenant_id);
CREATE INDEX idx_tasks_tenant ON tasks(tenant_id);

-- Backfill existing data
UPDATE users SET tenant_id = 'your-tenant-id';
UPDATE projects SET tenant_id = 'your-tenant-id';
UPDATE tasks SET tenant_id = 'your-tenant-id';

-- Make it required
ALTER TABLE users ALTER COLUMN tenant_id SET NOT NULL;

Phase 2: Application Changes (Week 2)​

// Add tenant resolution middleware
app.use((req, res, next) => {
req.tenantId = extractTenantId(req); // From subdomain/JWT/URL
next();
});

// Update ALL queries to include tenant filter
// BEFORE (dangerous!):
app.get('/projects', async (req, res) => {
const projects = await db('projects'); // ❌ NO TENANT FILTER!
res.json(projects);
});

// AFTER (safe):
app.get('/projects', async (req, res) => {
const projects = await db('projects')
.where({ tenant_id: req.tenantId }); // ✅ ALWAYS FILTER!
res.json(projects);
});

Phase 3: Add Row-Level Security (Week 3)​

ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON projects
USING (tenant_id = current_setting('app.current_tenant'));

Phase 4: Testing (Week 4)​

it('Prevents cross-tenant data access', async () => {
const tenantA = await createTenant('A');
const tenantB = await createTenant('B');

const projectB = await createProject('B Project', tenantB.id);

const response = await request(app)
.get(`/projects/${projectB.id}`)
.set('Authorization', `Bearer ${tenantAToken}`);

expect(response.status).toBe(403); // FORBIDDEN
});

Deployment Strategy​

1. Deploy backwards-compatible code
(tenant_id nullable, both old and new code work)
↓
2. Monitor for errors (1 week)
↓
3. Make tenant_id NOT NULL
↓
4. Add row-level security (optional, later)

7. Monitoring & Observability​

Tenant-Aware Metrics​

app.use((req, res, next) => {
const start = Date.now();

res.on('finish', () => {
const duration = Date.now() - start;

console.log({
timestamp: new Date().toISOString(),
tenant_id: req.user?.tenantId,
user_id: req.user?.id,
method: req.method,
path: req.path,
status: res.statusCode,
duration_ms: duration
});

metrics.record({
tenant: req.user?.tenantId,
status: res.statusCode,
duration
});
});

next();
});

Key Metrics to Track​

Per-Tenant:

  • Request rate (req/min)
  • Error rate (%)
  • Database query time (ms)
  • Cache hit rate (%)
  • Storage usage (MB)
  • Active users

System-Wide:

  • Noisy neighbor detection
  • Resource utilization
  • Cost per tenant

Structured Logging​

{
"timestamp": "2024-01-15T10:00:00Z",
"tenant_id": "abc-123",
"user_id": "user-456",
"level": "INFO",
"message": "User accessed dashboard",
"request_id": "req-789",
"method": "GET",
"path": "/dashboard",
"status": 200,
"duration_ms": 45
}

8. Security Best Practices​

Data Protection​

  • TLS 1.3 for data in transit
  • AES-256 for data at rest
  • Tenant-specific encryption keys (advanced)

Access Control​

Principle of Least Privilege:

  • Tenant can only access THEIR data
  • Users only access their tenant's data
  • No cross-tenant queries EVER
  • Row-level security policies
  • tenant_id in ALL queries
  • No cross-tenant joins allowed

Audit Logging​

{
timestamp: "2024-01-15T10:00:00Z",
tenant_id: "abc-123",
user_id: "user-456",
action: "DELETE_PROJECT",
resource_type: "project",
resource_id: "proj-789",
ip_address: "203.0.113.42",
outcome: "SUCCESS",
before_state: { name: "Old Project" },
after_state: null
}

9. Compliance​

GDPR​

  • Data portability per tenant
  • Right to deletion
  • Data processing agreements
  • EU data residency options
  • Encryption at rest and in transit

SOC 2​

  • Access controls
  • Change management
  • Monitoring and alerting
  • Incident response
  • Regular security audits

HIPAA​

  • Business Associate Agreements (BAA) per tenant
  • Enhanced encryption
  • Access audit trails
  • Data segmentation per tenant
  • 7-year retention policies

Data Residency​

{
"tenant_id": "eu-customer",
"data_residency": "eu-west-1",
"encryption_key_region": "eu-west-1"
}

10. Implementation Roadmap​

Phase 1: Foundation (Weeks 1-2) ✅ MUST DO​

  • Add tenant_id to ALL tables
  • Create indexes on tenant_id
  • Create tenant resolution middleware
  • Implement tenant context
  • Update ALL queries with tenant filter
  • Test isolation

Phase 2: Security (Weeks 3-4) ✅ CRITICAL​

  • Tenant-aware authorization
  • Row-level security
  • Tenant-aware caching
  • Isolation tests
  • Security audit
  • Audit logging

Phase 3: Features (Weeks 5-6) ✅ IMPORTANT​

  • Tenant management UI
  • Onboarding workflow
  • Billing integration
  • Tenant configuration
  • Feature flags
  • Custom domains

Phase 4: Scale (Weeks 7-8) ✅ PERFORMANCE​

  • Connection pooling
  • Redis caching
  • Rate limiting
  • Read replicas
  • Load balancer
  • Performance testing

Phase 5: Monitoring (Weeks 9-10) ✅ OBSERVABILITY​

  • Tenant metrics
  • Per-tenant alerting
  • Audit log dashboard
  • Cost tracking
  • Error tracking
  • Performance monitoring

11. Common Pitfalls & Solutions​

❌ Pitfall 1: Missing Tenant Filter = DATA BREACH​

// ❌ DANGER: No tenant filter!
const users = await db.raw('SELECT * FROM users WHERE email = ?', [email]);

// ✅ SAFE: Always filter by tenant_id
const users = await db('users')
.where({
tenant_id: req.user.tenantId, // ← ALWAYS HERE
email: email
});

Prevention:

  • Use query builder that auto-adds tenant filter
  • Code review: "Is tenant_id in where clause?"
  • Automated tests on all queries

❌ Pitfall 2: Cross-Tenant Joins​

-- ❌ DANGER: Missing tenant_id in JOIN!
SELECT * FROM orders o
JOIN users u ON o.user_id = u.id -- Missing tenant_id!
WHERE o.tenant_id = ?

-- ✅ SAFE: Always join on tenant_id too
SELECT * FROM orders o
JOIN users u ON o.user_id = u.id AND o.tenant_id = u.tenant_id
WHERE o.tenant_id = ?

Prevention:

  • Query builder adds tenant_id to all joins
  • Lint rules for joins
  • Code review checklist

❌ Pitfall 3: Cache Contamination​

// ❌ DANGER: Cache shared across tenants!
const cacheKey = `user:${userId}`;
const cached = await redis.get(cacheKey);
// Tenant A gets Tenant B's cached data!

// ✅ SAFE: Tenant-aware cache keys
const cacheKey = `tenant:${tenantId}:user:${userId}`;
const cached = await redis.get(cacheKey);
// Each tenant has separate cache!

Prevention:

  • Cache wrapper prepends tenant_id
  • Lint rules for cache keys
  • Multi-tenant testing

❌ Pitfall 4: Background Jobs Without Tenant​

// ❌ DANGER: Job has no tenant context!
queue.add('send-email', { userId: 123 });
// Worker doesn't know which tenant!

// ✅ SAFE: Always include tenant in job data
queue.add('send-email', {
userId: 123,
tenantId: req.user.tenantId // ← ALWAYS HERE
});

// Worker validates tenant
worker.process(async (job) => {
const { userId, tenantId } = job.data;

const tenant = await db('tenants').where({ id: tenantId }).first();
if (!tenant) throw new Error('Invalid tenant');

const user = await db('users')
.where({ id: userId, tenant_id: tenantId })
.first();

await sendEmail(user.email);
});

Prevention:

  • Queue requires tenant_id
  • Worker validates tenant
  • Alert on missing tenant_id

❌ Pitfall 5: No Row-Level Security​

// ❌ DANGER: App-level check can be bypassed
app.get('/projects/:id', async (req, res) => {
const project = await db('projects').where({ id: req.params.id }).first();
// What if someone calls this directly??
if (project.tenant_id !== req.user.tenant_id) {
return res.status(403); // Too late, data already queried!
}
res.json(project);
});

// ✅ SAFE: Row-Level Security (Database enforced!)
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON projects
USING (tenant_id = current_setting('app.current_tenant'));

// ✅ ALSO: Application check (defense in depth)
app.get('/projects/:id', async (req, res) => {
const project = await db('projects')
.where({
id: req.params.id,
tenant_id: req.user.tenant_id // Still filter in app!
})
.first();

if (!project) return res.status(404).json({ error: 'Not found' });
res.json(project);
});

Prevention:

  • Enable RLS on all tables
  • Defense in depth (app + db)
  • Regular security audits

12. Backup Strategies​

Shared Schema: Point-in-Time Recovery (PITR)​

# Enable WAL archiving
# postgresql.conf:
archive_mode = on
archive_command = 'cp %p /backup/wal/%f'

# Restore to any point in time

Per-Tenant Extraction​

# Backup one tenant
pg_dump saas_db \
--data-only \
--where="tenant_id = 'abc-123'" \
> tenant_backup.sql

Separate Database: Simple​

# One database per tenant = one backup per tenant
pg_dump tenant_abc_db > backup.sql

Best Practices​

  1. Test restores regularly
  2. 3-2-1 rule: 3 copies, 2 media, 1 offsite
  3. Automate everything
  4. Encrypt sensitive backups
  5. Document recovery procedure
  6. Monitor backup status

13. Decision Matrix​

FactorShared SchemaSeparate SchemaSeparate DB
Cost$ (Low)$$ (Medium)$$$ (High)
IsolationLowMediumHigh
ComplianceHardModerateEasy
ScalingEasyModerateComplex
BackupComplexModerateEasy
Best ForStartupsMid-marketEnterprise

Recommendation: Start with Shared Schema, evolve as needed.


14. Key Takeaways​

  1. Start Simple: Begin with shared schema, evolve as needed
  2. Isolate Relentlessly: Every query, every cache, every job
  3. Plan for Scale: Connection pooling, sharding, caching
  4. Security First: Row-level security, audit logs, encryption
  5. Monitor Everything: Per-tenant metrics and alerts
  6. Test Thoroughly: Isolation testing, load testing
  7. Evolve Gradually: Add complexity as needed, not all at once

15. Emergency Checklist​

If You Suspect a Data Breach​

  1. ✋ STOP all data access immediately
  2. 🔍 Identify affected tenants
  3. 📊 Audit all queries without tenant filters
  4. 🔐 Disable compromised accounts
  5. 📝 Document everything
  6. 🗣️ Notify affected customers
  7. 🔧 Fix the root cause
  8. ✅ Test thoroughly before restoring

16. Quick Reference​

Must-Have Security​

  • All tables have tenant_id
  • All queries filter by tenant_id
  • Row-level security enabled
  • Tenant-aware middleware
  • No cross-tenant joins
  • Tenant-aware caching
  • Audit logging enabled
  • Rate limiting per tenant
  • Encryption (TLS + at rest)
  • Regular security audits

Implementation Priority​

Week 1-2: Foundation
✓ Add tenant_id to all tables
✓ Create tenant middleware
✓ Update queries with filters

Week 3-4: Security
✓ Implement authorization
✓ Add row-level security
✓ Security audit

Week 5-6: Features
✓ Tenant management UI
✓ Provisioning workflow
✓ Billing integration

Week 7-8: Scale
✓ Connection pooling
✓ Caching layer
✓ Rate limiting

Week 9-10: Monitoring
✓ Tenant metrics
✓ Per-tenant alerting
✓ Audit logging

17. Questions?​

Common Questions:

  1. Which architecture pattern should I start with? → Shared Schema
  2. How do I implement row-level security? → PostgreSQL RLS
  3. What about multi-tenant authentication? → JWT with tenant info
  4. How do I handle tenant-specific customizations? → Configuration over code
  5. What are the best backup practices? → PITR or per-tenant backups
  6. How do I migrate from single-tenant? → Gradual, careful migration
  7. What about rate limiting and scaling? → Per-tenant limits, stateless servers

Need help? Check the full guide above or ask specific questions!


Last Updated: January 2024
Version: 1.0