As applications grow, multi-tenancy becomes a key architectural concern, especially for SaaS platforms serving multiple customers. Multi-tenancy allows multiple tenants (organizations or users) to share the same application while keeping their data isolated.
In this article, we’ll explore two common approaches to multi-tenancy in Spring Boot:
- Schema-Based Isolation – Each tenant has a separate schema within the same database.
- Database Sharding (Shared Database Model) – All tenants share a single database, with tenant-specific partitioning.
We’ll also cover best practices and implementation strategies for both models.
1. Understanding Multi-Tenancy
Multi-tenancy is essential for SaaS applications that need to serve multiple customers while optimizing resource usage. The key challenge is how to isolate tenant data while maintaining efficiency.
The two common approaches are:
- Schema-Based Isolation: Each tenant has a separate schema (e.g.,
tenant_1.orders,tenant_2.orders). - Database Sharding (Shared Database with Tenant Column): A single database with tenant-specific identifiers (e.g.,
orderstable withtenant_idcolumn).
Each approach has trade-offs in terms of performance, scalability, and complexity.
2. Approach 1: Schema-Based Isolation
2.1 How It Works
Each tenant gets its own database schema while sharing the same database instance. This ensures strong data isolation but requires schema management.
Example structure:
1 2 3 | tenant_1.orders tenant_2.orders tenant_3.orders |
2.2 Implementation in Spring Boot
We use Hibernate Multi-Tenancy to dynamically switch schemas based on the incoming request.
Step 1: Define a Tenant Identifier Resolver
Spring Boot needs to identify the tenant from incoming requests. This can be done using a request header or a JWT token.
01 02 03 04 05 06 07 08 09 10 11 12 13 14 | @Componentpublic class CurrentTenantIdentifierResolver implements CurrentTenantIdentifierResolver { private static final String DEFAULT_TENANT = "public"; @Override public String resolveCurrentTenantIdentifier() { return TenantContext.getCurrentTenant() != null ? TenantContext.getCurrentTenant() : DEFAULT_TENANT; } @Override public boolean validateExistingCurrentSessions() { return true; }} |
Step 2: Configure Multi-Tenant Data Source
Modify the DataSource configuration to switch schemas dynamically.
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 | @Configurationpublic class MultiTenantConfig { @Bean public DataSource dataSource() { Map<Object, Object> targetDataSources = new HashMap<>(); targetDataSources.put("tenant_1", createDataSource("jdbc:mysql://localhost:3306/tenant_1")); targetDataSources.put("tenant_2", createDataSource("jdbc:mysql://localhost:3306/tenant_2")); return new AbstractRoutingDataSource() { @Override protected Object determineCurrentLookupKey() { return TenantContext.getCurrentTenant(); } }; } private DataSource createDataSource(String url) { return DataSourceBuilder.create().url(url).username("user").password("password").build(); }} |
Step 3: Set Tenant Context Per Request
Intercept incoming requests and set the tenant context.
01 02 03 04 05 06 07 08 09 10 | @Componentpublic class TenantFilter extends OncePerRequestFilter { @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { String tenantId = request.getHeader("X-Tenant-ID"); TenantContext.setCurrentTenant(tenantId); chain.doFilter(request, response); }} |
Now, requests with X-Tenant-ID: tenant_1 will automatically switch to the tenant_1 schema.
2.3 Pros and Cons of Schema-Based Isolation
✔ Strong Data Isolation – Each tenant’s data is fully separate.
✔ Better Compliance – Meets regulatory requirements like GDPR.
✖ Operational Overhead – Managing multiple schemas increases complexity.
✖ Scaling Issues – Large tenant numbers may impact performance.
3. Approach 2: Database Sharding (Shared Database Model)
3.1 How It Works
Instead of using separate schemas, all tenants share the same tables, but each row is tagged with a tenant_id.
Example table structure:
| id | tenant_id | order_details |
|---|---|---|
| 1 | tenant_1 | Order A |
| 2 | tenant_2 | Order B |
3.2 Implementation in Spring Boot
We modify Hibernate to automatically add the tenant filter to every query.
Step 1: Configure a Hibernate Tenant Filter
01 02 03 04 05 06 07 08 09 10 11 | @FilterDef(name = "tenantFilter", parameters = @ParamDef(name = "tenantId", type = "string"))@Filter(name = "tenantFilter", condition = "tenant_id = :tenantId")@Entitypublic class Order { @Id private Long id; private String orderDetails; private String tenantId;} |
Step 2: Apply the Filter on Every Request
Before executing queries, we set the current tenant dynamically.
01 02 03 04 05 06 07 08 09 10 11 | @Componentpublic class HibernateTenantInterceptor { @PersistenceContext private EntityManager entityManager; @Transactional public void applyTenantFilter() { Session session = entityManager.unwrap(Session.class); session.enableFilter("tenantFilter").setParameter("tenantId", TenantContext.getCurrentTenant()); }} |
Now, every query automatically filters results based on the tenant_id.
3.3 Pros and Cons of Database Sharding
✔ Easy to Scale – Single database can handle thousands of tenants.
✔ Simpler Management – No need to create new schemas for each tenant.
✖ Weaker Data Isolation – Accidental queries without tenant filters can expose data.
✖ Performance Bottlenecks – Large databases require indexing and partitioning.
4. Choosing the Right Multi-Tenancy Strategy
| Feature | Schema-Based Isolation | Database Sharding |
|---|---|---|
| Isolation Level | Strong | Weaker (tenant ID filtering) |
| Complexity | High (managing schemas) | Lower (shared DB) |
| Scalability | Medium (limited by DB connections) | High (partitioning possible) |
| Compliance Needs | Better for GDPR & regulations | Riskier for compliance |
If strong isolation and compliance are priorities, Schema-Based Isolation is the best choice. If scalability and efficiency are more important, Database Sharding is often preferable.
5. Final Thoughts
Multi-tenancy in Spring Boot can be implemented using schema-based isolation for better security or database sharding for scalability. The choice depends on your business requirements, compliance needs, and operational capacity.
Further Reading
- Spring Boot & Hibernate Multi-Tenancy Guide
- PostgreSQL Multi-Tenant Strategies
- AWS RDS Best Practices for Multi-Tenant Databases
