Multi-Tenant SaaS Platform

Problem Being Solved

Core Problem Statement

Traditional approaches force teams to choose between shared-schema designs (risking data leakage from missed tenant filters) and database-per-tenant isolation (creating operational complexity with thousands of database instances).

Who Suffers Most

1. SaaS DevOps Teams: Managing database-per-tenant architectures where 1000 tenants means 1000 PostgreSQL instances, each requiring individual backup, monitoring, migration, and connection pool management, consuming 3-5 full-time engineers.

2. SaaS Security Teams: Responsible for SOC2/ISO27001 compliance who cannot prove tenant isolation guarantees when isolation depends on application code correctness, forcing expensive manual security audits every quarter.

HeliosDB Lite Solution

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                 HeliosDB-Lite Multi-Tenant Stack                        │
├─────────────────────────────────────────────────────────────────────────┤
│  SaaS Application Layer (API Gateway / Auth Service)                    │
├─────────────────────────────────────────────────────────────────────────┤
│  HeliosProxy: Tenant Resolution │ RLS Injection │ Connection Pooling    │
│  ┌──────────┐ ┌──────────────┐ ┌─────────────────────┐                 │
│  │JWT/API   │ │ SQL Rewrite  │ │ 100:1 Multiplexing  │                 │
│  │Key Parse │ │ + RLS WHERE  │ │ + Session Affinity   │                 │
│  └──────────┘ └──────────────┘ └─────────────────────┘                 │
├─────────────────────────────────────────────────────────────────────────┤
│  HeliosCore: Query Engine │ Storage Layer │ Transaction Manager          │
├─────────────────────────────────────────────────────────────────────────┤
│              Shared Tables with tenant_id Column + B-tree Indexes        │
└─────────────────────────────────────────────────────────────────────────┘

Concrete Examples with Code, Config & Architecture

Example 1: SaaS Platform with Proxy-Injected Tenant Filters - Embedded Configuration

Scenario: B2B project management SaaS with 5,000 tenants, 50,000 concurrent users, shared database with tenant filters injected at the HeliosProxy layer. Each tenant has 10,000-500,000 rows across 20 tables. Deploy on 3-node Kubernetes cluster with automatic failover.

Architecture:

SaaS Application (API Server)
    ↓ (PostgreSQL wire protocol)
HeliosProxy (Tenant Resolution + RLS)
    ↓ (Multiplexed connections)
HeliosCore (Query Engine + Storage)
    ↓
Shared Tables (tenant_id column, B-tree indexed)

Configuration (heliosdb-proxy.toml):

# HeliosProxy configuration for multi-tenant SaaS
[proxy]
listen_addr = "0.0.0.0:5432"
max_client_connections = 10000
max_backend_connections = 100           # 100:1 multiplexing ratio
connection_timeout_ms = 5000

[proxy.tls]
enabled = true
cert_file = "/etc/ssl/heliosdb/server.crt"
key_file = "/etc/ssl/heliosdb/server.key"

[proxy.auth]
# Tenant resolution from JWT token
mode = "jwt"
jwt_secret = "${JWT_SECRET}"
tenant_claim = "org_id"                 # Extract tenant ID from JWT claim
user_claim = "sub"

[proxy.rls]
# Automatic RLS enforcement
enabled = true
default_tenant_column = "tenant_id"
# Tables exempt from RLS (system tables)
exempt_tables = ["migrations", "system_config"]
# RLS mode: "inject" adds WHERE clause; "reject" blocks queries without tenant filter
mode = "inject"

[proxy.rls.table_overrides]
# Custom tenant column for specific tables
"audit_logs" = { tenant_column = "organization_id" }
"shared_templates" = { tenant_column = "owner_tenant_id", allow_shared = true }

[proxy.rate_limiting]
enabled = true
default_queries_per_second = 100
default_max_concurrent = 10

[proxy.rate_limiting.tier_overrides]
"enterprise" = { queries_per_second = 1000, max_concurrent = 50 }
"professional" = { queries_per_second = 500, max_concurrent = 25 }
"starter" = { queries_per_second = 100, max_concurrent = 10 }

[database]
path = "/data/saas.db"
memory_limit_mb = 4096
enable_wal = true
max_connections = 100

[monitoring]
metrics_enabled = true
prometheus_port = 9090
slow_query_threshold_ms = 100

Example 2: Multi-Tenant API with Automatic Tenant Filters - Python Integration

Architecture Pattern:

┌─────────────────────────────────────────┐
│     FastAPI Application (Python)         │
├─────────────────────────────────────────┤
│  JWT Authentication Middleware           │
├─────────────────────────────────────────┤
│  HeliosProxy Python Client (PyO3)       │
│  - Tenant context from JWT              │
│  - Automatic RLS enforcement            │
├─────────────────────────────────────────┤
│  HeliosProxy (Connection Multiplexing)  │
│  - SQL rewriting with tenant_id         │
│  - Rate limiting per tenant tier        │
├─────────────────────────────────────────┤
│  HeliosCore (Shared Database)           │
│  - tenant_id indexed columns            │
│  - WAL for durability                   │
└─────────────────────────────────────────┘

Example 3: Multi-Tenant SaaS Kubernetes Deployment - Infrastructure & Container

Scenario: Production deployment of multi-tenant SaaS with HeliosProxy on Kubernetes, supporting 5,000 tenants across 3 availability zones with automatic failover.

Docker Deployment (Dockerfile):

FROM rust:1.75-slim as builder

WORKDIR /app

RUN apt-get update && apt-get install -y \
    build-essential \
    libssl-dev \
    pkg-config \
    && rm -rf /var/lib/apt/lists/*

COPY . .

# Build HeliosDB-Lite with proxy and multi-tenant features
RUN cargo build --release --features proxy,rls,session-migration

# Runtime stage
FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    ca-certificates \
    libssl3 \
    curl \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /app/target/release/heliosdb-saas /usr/local/bin/
COPY --from=builder /app/target/release/helios-proxy /usr/local/bin/

RUN mkdir -p /data /etc/heliosdb && chmod 755 /data

EXPOSE 5432 8080 9090

HEALTHCHECK --interval=15s --timeout=3s --start-period=30s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

VOLUME ["/data"]

ENTRYPOINT ["heliosdb-saas"]
CMD ["--config", "/etc/heliosdb/config.toml", "--data-dir", "/data"]

Docker Compose (docker-compose.yml):

version: '3.8'

services:
  heliosdb-proxy:
    build:
      context: .
      dockerfile: Dockerfile
    image: heliosdb-saas:latest
    container_name: heliosdb-saas-prod

    ports:
      - "5432:5432"      # PostgreSQL wire protocol (tenant connections)
      - "8080:8080"      # Admin API + health checks
      - "9090:9090"      # Prometheus metrics

    volumes:
      - ./data:/data
      - ./config/heliosdb-proxy.toml:/etc/heliosdb/config.toml:ro
      - ./certs:/etc/ssl/heliosdb:ro

    environment:
      RUST_LOG: "info"
      HELIOSDB_DATA_DIR: "/data"
      JWT_SECRET: "${JWT_SECRET}"

    restart: unless-stopped

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 30s

    networks:
      - saas-network

    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G

networks:
  saas-network:
    driver: bridge

volumes:
  saas_data:
    driver: local

Kubernetes Deployment (k8s-deployment.yaml):

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: heliosdb-saas
  namespace: saas-platform
spec:
  serviceName: heliosdb-saas
  replicas: 3
  selector:
    matchLabels:
      app: heliosdb-saas
  template:
    metadata:
      labels:
        app: heliosdb-saas
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9090"
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchExpressions:
              - key: app
                operator: In
                values:
                - heliosdb-saas
            topologyKey: "topology.kubernetes.io/zone"
      containers:
      - name: heliosdb-saas
        image: heliosdb-saas:<version>
        imagePullPolicy: Always

        ports:
        - containerPort: 5432
          name: postgres
          protocol: TCP
        - containerPort: 8080
          name: admin
          protocol: TCP
        - containerPort: 9090
          name: metrics
          protocol: TCP

        env:
        - name: RUST_LOG
          value: "info"
        - name: HELIOSDB_DATA_DIR
          value: "/data"
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: heliosdb-secrets
              key: jwt-secret
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name

        volumeMounts:
        - name: data
          mountPath: /data
        - name: config
          mountPath: /etc/heliosdb
          readOnly: true
        - name: tls-certs
          mountPath: /etc/ssl/heliosdb
          readOnly: true

        resources:
          requests:
            memory: "4Gi"
            cpu: "2000m"
          limits:
            memory: "8Gi"
            cpu: "4000m"

        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3

        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 2

  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 100Gi

---
apiVersion: v1
kind: Service
metadata:
  name: heliosdb-saas
  namespace: saas-platform
spec:
  type: ClusterIP
  selector:
    app: heliosdb-saas
  ports:
  - port: 5432
    targetPort: 5432
    name: postgres
  - port: 8080
    targetPort: 8080
    name: admin
  - port: 9090
    targetPort: 9090
    name: metrics

Configuration for Multi-Tenant Cluster (config.toml):

[server]
host = "0.0.0.0"
admin_port = 8080

[proxy]
listen_addr = "0.0.0.0:5432"
max_client_connections = 10000
max_backend_connections = 100

[proxy.rls]
enabled = true
default_tenant_column = "tenant_id"
mode = "inject"
audit_log_enabled = true

[proxy.session_migration]
enabled = true
peer_discovery = "kubernetes"
migration_timeout_ms = 100

[database]
path = "/data/saas.db"
memory_limit_mb = 4096
enable_wal = true
page_size = 8192

[monitoring]
metrics_enabled = true
prometheus_port = 9090
slow_query_threshold_ms = 50

Example 4: Tenant-Scoped Microservice with gRPC - Microservices Integration

Scenario: Multi-tenant billing microservice handling 10,000 invoice operations per second across 2,000 tenants. gRPC API for internal service-to-service communication with automatic tenant propagation via gRPC metadata.

Service Architecture:

┌─────────────────────────────────────────┐
│     gRPC Request (Tonic Framework)       │
│     x-tenant-id in gRPC metadata        │
├─────────────────────────────────────────┤
│  BillingService Handler (Async Tokio)    │
├─────────────────────────────────────────┤
│  HeliosProxy Tenant Connection           │
│  - Tenant resolved from gRPC metadata   │
│  - RLS WHERE clause auto-injected       │
├─────────────────────────────────────────┤
│  HeliosCore (Shared Database)            │
│  - Composite indexes (tenant_id + ...)  │
│  - WAL for transaction durability       │
└─────────────────────────────────────────┘

Example 5: Edge-Deployed Multi-Tenant SaaS - Edge Computing & IoT

Scenario: Point-of-sale (POS) SaaS system deployed at retail locations, each location serving multiple merchant tenants.

Edge Device Configuration (config.toml):

[database]
path = "/var/lib/heliosdb/pos.db"
memory_limit_mb = 512
page_size = 4096
enable_wal = true
cache_mb = 128

[proxy]
listen_addr = "0.0.0.0:5432"
max_client_connections = 100       # Local POS terminals
max_backend_connections = 10

[proxy.rls]
enabled = true
default_tenant_column = "merchant_id"
mode = "inject"
audit_log_enabled = true

[proxy.auth]
mode = "api_key"
key_header = "X-Merchant-Key"

[sync]
enable_remote_sync = true
sync_interval_secs = 300
sync_endpoint = "https://cloud.possaas.com/api/sync"
batch_size = 500
conflict_resolution = "last_write_wins"

[logging]
level = "info"
output = "/var/log/heliosdb/pos.log"
max_size_mb = 50

Edge Architecture:

┌──────────────────────────────────────────────┐
│    Retail Location (Intel NUC / Edge Device)  │
├──────────────────────────────────────────────┤
│   POS Terminal 1  │  Terminal 2  │  Terminal 3│
│   (Merchant A)    │  (Merchant B)│  (Merchant A)
├──────────────────────────────────────────────┤
│   HeliosProxy (Tenant Isolation via RLS)     │
│   - API key → merchant_id resolution         │
│   - Automatic WHERE merchant_id = ? injection│
├──────────────────────────────────────────────┤
│   HeliosCore (Local Persistent Storage)      │
│   - All merchants in shared tables           │
│   - Offline-capable, sync when connected     │
├──────────────────────────────────────────────┤
│   Sync Engine (Background, every 5 min)      │
├──────────────────────────────────────────────┤
│   Network (Broadband/4G, intermittent)       │
├──────────────────────────────────────────────┤
│   Cloud Backend (Aggregation & Analytics)    │
└──────────────────────────────────────────────┘

Adoption Strategy

Phase 1: Proof of Concept (Weeks 1-4)

Target: Validate proxy-injected tenant filters with an existing SaaS application

Tactics: - Deploy HeliosProxy in front of existing database - List 2-3 core tables in tenant_tables - Run existing test suite to verify tenant isolation - Benchmark connection multiplexing savings

Phase 3: Full Rollout

Target: All tenants on HeliosProxy with DB-per-tenant retirement

Conclusion

HeliosProxy's multi-tenancy feature isolates tenants by injecting a predicate on the configured tenant column into queries on the tables listed in tenant_tables; queries on other tables pass through unchanged. The proxy identifies the tenant from a connection attribute: a startup parameter such as application_name (the default) or user, or the database name. The same feature provides per-tenant connection pools, rate limits and connection caps.