Building Multi-Tenant SaaS with qqq

Multi-tenancy is one of the most complex patterns in SaaS development. How do you isolate customer data while sharing infrastructure? How do you handle per-tenant customization without code sprawl? At Infoplus, we served thousands of tenants on a shared platform - and the patterns we developed became core to qqq.

Multi-tenancy is a first-class concern in qqq. The framework provides automatic tenant isolation at the data layer, configurable per-tenant features, and white-labeling support out of the box.

Understanding Tenant Isolation

qqq supports multiple isolation strategies, each with different tradeoffs:

Shared Database with Row-Level Security: All tenants share the same tables. A tenant_id column is automatically added to every table, and queries are automatically filtered. Lowest cost, easiest to manage, but requires careful security attention.

Schema-per-Tenant: Each tenant gets their own database schema within a shared database. Better isolation, slightly more complex operations. Good for regulated industries.

Database-per-Tenant: Complete isolation with separate databases. Highest cost, maximum security. Essential for enterprise customers with strict compliance requirements.

Hybrid Approaches: Mix strategies based on customer tier. Free users share tables; enterprise customers get dedicated schemas.

Configuring Multi-Tenancy

Setting up multi-tenancy in qqq is declarative:

qInstance.withMultiTenantConfig(
   new QMultiTenantConfig()
      .withIsolationMode(IsolationMode.ROW_LEVEL)
      .withTenantIdField("tenantId")
      .withTenantResolver(new SessionTenantResolver())
);

Once configured, every query automatically includes tenant filtering. Developers don't need to remember to add WHERE tenant_id = ? - the framework handles it. Cross-tenant data access is prevented at the core level.

Per-Tenant Configuration

Real SaaS applications need per-tenant customization. qqq provides a configuration layer that lets you:

• Enable or disable features per tenant
• Configure integrations (each tenant uses their own API keys)
• Set tenant-specific business rules
• Apply custom validation logic

TenantConfig config = TenantConfigManager.getConfig(tenantId);
if (config.hasFeature("advanced-reporting")) {
   // Show advanced reports
}

Configuration is stored in the database and cached for performance. Changes take effect immediately without deployment.

White-Labeling and Branding

For B2B SaaS, branding matters. qqq's admin UI supports per-tenant customization:

• Custom logos and colors
• Custom domain support (tenant.yourapp.com)
• Branded email templates
• Custom login pages

This is configured through metadata, not code changes. Add a new tenant, configure their branding, and they're live.

Handling Tenant Onboarding

New tenants need their data structures created. qqq handles this through a provisioning workflow:

new TenantProvisioningProcess()
   .withSteps(List.of(
      new CreateTenantSchemaStep(),
      new ApplyMigrationsStep(),
      new SeedDefaultDataStep(),
      new ConfigureBrandingStep(),
      new SendWelcomeEmailStep()
   ));

Whether you're creating a shared tenant or a dedicated database, the same process handles it. Schema isolation mode determines the actual operations performed.

Performance Considerations

Multi-tenant applications have unique performance challenges. qqq addresses these with:

• Connection pooling per tenant: Prevents one tenant from exhausting the pool
• Query optimization: Tenant filtering uses indexed columns
• Caching layers: Per-tenant caching with proper isolation
• Background jobs: Tenant-aware job scheduling prevents starvation

Real-World Patterns

At Infoplus, we learned that multi-tenancy isn't just about data isolation. It's about:

1. Noisy neighbors: One tenant's heavy usage shouldn't affect others
2. Compliance boundaries: Some tenants need geographic data residency
3. Feature flags: Roll out features to specific tenants first
4. Support context: Support staff need to view data as the tenant sees it

qqq's multi-tenant implementation addresses all of these. When you build on qqq, you get patterns battle-tested across thousands of tenants.

Getting Started

Ready to build multi-tenant SaaS? Check out our multi-tenancy documentation or see it in action with our quickstart guide.