Case study
From single-tenant to multi-tenant: transforming a Laravel project
schedule3 min
calendar_today11 December 2024
syncCaricamento...
As software is increasingly expected to be both customizable and scalable, moving from a single-tenant system to a multi-tenant architecture is an interesting challenge. In this article I share the experience of transforming a Laravel project for two specific entities, Valmontone and Barberino, using middleware to manage separate databases and dealing with the technical complexity that this choice brought with it.
Starting point: a single-tenant system
The original project was designed as a single-tenant system, with a standard Laravel configuration that used a single database. This architecture worked, but it was limiting given the need to manage two distinct entities, each with its own database and its own specific configuration.
The multi-tenant idea
The goal was to create a multi-tenant system that would let Valmontone and Barberino share the same codebase while keeping their data fully isolated. The solution we settled on was to use custom middleware to route each request to the correct database according to the tenant.
Technologies and techniques used
- Multi-tenant middleware: The key to the project was a middleware able to intercept every HTTP request, identify the active tenant (based on the domain or on a specific parameter) and dynamically configure the connection to the correct database.
- Queues and commands: One of the biggest challenges was getting the other Laravel subsystems to work correctly, such as queues, artisan commands and scheduled tasks. Every operation had to respect the context of the active tenant, which required a custom integration.
- Relational databases: The project used separate relational databases for each tenant, guaranteeing complete data isolation. The dynamic configuration of the connections was handled with Laravel's
config()method, overriding the connection parameters on the fly. - Multi-tenant testing: To guarantee the quality of the system, specific automated tests were developed to verify that every feature worked correctly in multi-tenant contexts.
Challenges and solutions
- Integration with queues and Artisan commands:
- Laravel queues do not automatically respect the tenant context. This was solved by implementing custom jobs that inherit the tenant information and re-inject it into the context at execution time.
- The Artisan commands were adapted to accept additional parameters, so that the tenant can be specified.
- Performance:
- The middleware adds overhead to each request, so the routing logic and the handling of database connections had to be optimized.
- Maintenance and scalability:
- To simplify maintenance, the multi-tenant logic was centralized and carefully documented, making the system scalable when new tenants are added in the future.
- Scheduled tasks:
- The scheduling system was modified to run tasks in a loop over all tenants, ensuring that every operation is executed in the correct context.
The benefits of the multi-tenant architecture
The transformation brought several benefits:
- Efficiency: Using a single codebase simplified development and maintenance.
- Isolation: Each tenant has an independent database, which guarantees security and privacy.
- Scalability: The structure is ready to support new tenants without significant changes.
Conclusion
Migrating from a single-tenant system to a multi-tenant one was an opportunity to tackle complex technical challenges and implement innovative solutions. Thanks to Laravel and its powerful features, it was possible to build a system that balances flexibility, isolation and scalability, laying solid foundations for future expansion. This experience shows how the right technologies, combined with careful design, can turn challenges into opportunities for growth.