Multi-Tenancy Architecture with Spring Boot Microservices

Modern SaaS (Software-as-a-Service) applications need to cater to multiple customers (tenants) while maintaining data isolation and security. This requirement introduces the concept of multi-tenancy, where a single application serves multiple tenants, each with its own data and configurations.

The design of a multi-tenancy architecture is integral to the scalability, security, and maintainability of your microservices. With Spring Boot, implementing multi-tenancy becomes manageable thanks to its robust features and frameworks.

This guide explores key aspects of multi-tenancy in Spring Boot microservices, focusing on database strategies, tenant contexts, tenant-aware data access, and request-level tenant resolution.

Table of Contents

1. What is Multi-Tenancy?
2. Shared vs Isolated Database Strategies
3. Implementing Tenant Context
4. Tenant-Aware Data Access Layer
5. Request-Level Tenant Resolution
6. Summary

What is Multi-Tenancy?

Multi-tenancy is an architecture where a single application instance serves multiple customers (tenants). Each tenant could represent a business, organization, or individual user group.

Key aspects of multi-tenancy:

• Data Isolation: Tenants should not access each other’s data.
• Optimized Resource Use: Shared instances minimize infrastructure costs compared to single-tenant setups.
• Flexibility: Tenants might need custom configurations or data segregation.

An example of multi-tenancy is a cloud accounting software where each tenant (business) manages its own financial records, but all share the same underlying application.

Shared vs Isolated Database Strategies

One of the most critical architectural decisions is choosing a database strategy. Here, we compare common options.

1. Shared Database, Shared Schema

All tenants share the same database and schema, with data partitioned by a tenant identifier.

Example Design:

A table might look like this:

Pros:

• Cost-Efficient: Minimal infrastructure costs.
• Simpler Management: Only one database to maintain.

Cons:

• Performance Issues: Heavy query loads from multiple tenants can degrade performance.
• Data Complexity: Queries must include tenant filters (WHERE tenant_id = ?) to ensure data isolation.

2. Shared Database, Separate Schemas

All tenants share a single database, but each tenant has its own schema.

Example:

Schemas:

• alice_schema.orders
• bob_schema.orders

Pros:

• Good Data Isolation: Tenants have separate schemas.
• Easier Customization: Schema-specific adjustments (e.g., indexes) can improve tenant performance.

Cons:

• Higher Complexity: Managing multiple schemas requires careful oversight.
• Limited Scalability: Single database constraints still apply.

3. Separate Databases

Each tenant has its own database.

Example:

Databases:

• alice_db
• bob_db

Pros:

• Full Isolation: Strong security guarantees as tenants cannot access each other’s data.
• High Scalability: Each database can be optimized for its workload.

Cons:

• Costly: More infrastructure overhead.
• Complex Deployment: Managing database connections for each tenant adds complexity.

Which Strategy to Choose?

The choice depends on:

1. Tenant Size: Small tenants might fit well in shared databases, while large tenants may require dedicated ones.
2. Compliance Requirements: Some regulations mandate strict data isolation, favoring separate databases.

Implementing Tenant Context

What is Tenant Context?

The tenant context is a mechanism to hold tenant-specific information for the duration of a request. This information can include:

• Tenant ID
• Geographical location
• Runtime preferences

Spring Boot facilitates tenant context setup through filters and context holders.

Storing Tenant Context Using ThreadLocal

A ThreadLocal variable ensures each thread (e.g., HTTP request) maintains its own tenant data.

TenantContextHolder:

public class TenantContextHolder {
    private static final ThreadLocal<String> tenantId = new ThreadLocal<>();

    public static void setTenantId(String tenant) {
        tenantId.set(tenant);
    }

    public static String getTenantId() {
        return tenantId.get();
    }

    public static void clear() {
        tenantId.remove();
    }
}

Managing Context with a Filter

Use a Spring filter to extract the tenant ID from request headers:

@Component
public class TenantFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
            throws ServletException, IOException {
        String tenantId = request.getHeader("X-Tenant-ID");
        if (tenantId != null) {
            TenantContextHolder.setTenantId(tenantId);
        }
        filterChain.doFilter(request, response);
        TenantContextHolder.clear();
    }
}

Why ThreadLocal?

ThreadLocal is well-suited for request-scoped data. However, it should be cleared after each request to avoid memory leaks.

Tenant-Aware Data Access Layer

To ensure data isolation in shared database strategies, you need a data access layer that incorporates tenant-specific logic.

Using Hibernate Interceptors

Hibernate provides interceptors to inject tenant-specific logic into queries.

Multi-Tenancy Configuration:

Set up a tenant-aware DataSource:

@Configuration
public class TenantDataSourceConfig {

    @Bean
    public DataSource dataSource() {
        return new TenantAwareDataSource();
    }
}

Interceptor Implementation:

public class TenantInterceptor implements Interceptor {

    @Override
    public String onPrepareStatement(String sql) {
        String tenantId = TenantContextHolder.getTenantId();
        if (tenantId != null) {
            sql = sql.replace("{tenantId}", tenantId);
        }
        return sql;
    }
}

This ensures queries dynamically include tenant-specific filters.

Schema-Based Multi-Tenancy

For schema separation, Hibernate supports schema-based multi-tenancy:

properties.put(Environment.MULTI_TENANT, MultiTenancyStrategy.SCHEMA);
properties.put(Environment.MULTI_TENANT_CONNECTION_PROVIDER, new SchemaBasedConnectionProvider());

Request-Level Tenant Resolution

Tenant resolution determines which tenant a request serves. Spring Boot provides flexibility for tenant identification at different levels:

1. Header-Based Resolution: Extract tenant information from HTTP headers (e.g., X-Tenant-ID).
2. Domain-Based Resolution: Identify tenant by subdomain (e.g., tenant1.example.com).
3. Request Parameter-Based Resolution: Retrieve tenant context from query parameters.

Example Header-Based Resolution

Assume each request includes a header like X-Tenant-ID.

Define a Custom Filter:

The previously shown TenantFilter identifies tenants by reading this header.

Key Considerations:

• Validate headers to prevent spoofing.
• Logging tenant activities for auditing purposes.

Summary

Implementing multi-tenancy in Spring Boot microservices is crucial for scalability and tenant security. Here’s a quick recap:

1. Database Strategies: Choose between shared or isolated database models based on performance, isolation needs, and cost.
2. Tenant Context: Store tenant-specific data during request processing using ThreadLocal and Spring filters.
3. Data Access Layer: Make your data access tenant-aware using Hibernate interceptors or schema-based separation.
4. Request-Level Resolution: Identify tenants dynamically using headers, domains, or query parameters.

By following these best practices, your microservices can efficiently serve multiple tenants while maintaining robust data and application integrity. Start building multi-tenant architectures today with Spring Boot!