Building Scalable SaaS: My Real-World Journey Using spatie/laravel-multitenancy for Multi-Tenant Arc | HackerNoon

Introduction

Over the past few months, I’ve built multiple SaaS applications that required full multi-tenant capabilities – including regression application, HR platforms, finance dashboards, and a payroll system, a multi-tenant compensation analytics platform.

Instead of reinventing the wheel, I leaned heavily on the incredible spatie/laravel-multitenancy package. It gave me a solid, reliable, and scalable foundation for handling multiple companies (tenants) on a single Laravel codebase, while keeping each tenant’s data fully isolated.

This article breaks down how I’ve used this package in real production systems, what worked, what didn’t, and the lessons I learned building multi-tenant SaaS applications in Laravel.

What is Multi-Tenant Architecture?

A multi-tenant system allows multiple companies (tenants) to use the same application while ensuring:

• Their data is fully isolated
• Their resources are separated
• Their settings, users, and permissions remain independent

Good examples: n Stripe, HubSpot, Freshdesk, Workday – all multi-tenant SaaS.

Three Types of Multi-Tenant

Single Database, Shared Schema

• One DB for all tenants
• Tenant ID used to separate data
• Easiest to implement
• Higher risk of accidental data leaks

Single Database, Separate Schema

• Each tenant has its own schema/tables
• More isolation
• Slightly more maintenance

Multiple Database (One per Tenant)

• each tenant has completely separate DB
• Maximum security + isolation
• Perfect for enterprise SaaS
• Spatie supports this best

For most of the applications and other products I’ve built, I used the “separate database per tenant” model because I prefer stronger data isolation and easier backups.

Why I choose spatie/laravel-multitenancy

Spatie makes multi-tenancy in Laravel simple, flexible, and production-ready. n Key advantages I was able to highlight are:

• Supports all three multi-tenant strategies
• Automatic tenant identification (domain, subdomain, path, or custom logic)
• Automatic database switching
• Tenant-aware queues & jobs
• Tenant-specific migrations + storage directories
• Fully extendable and customisable
• Reliable and actively maintained

This package saved me weeks per project .

Setting up Multi-Tenancy

A. Tenant Identification

I use domain-based identification:

class TenantFinder extends SpatieTenantFinder
{
    public function findForRequest(Request $request): ?Tenant
    {
        return Tenant::where('domain', $request->getHost())->first();
    }
}

This automatically switches the application context depending on the domain.

B. Running Tenant Migration

Each tenant has its own database. n I run migrations like this:

php artisan tenants:migrate

When I add a feature, every tenant gets the update without manual work.

C. Tenant-Aware Queues

Spatie automatically ensures queues run under the correct tenant:

Bus::chain([
   new ProcessPayroll($tenant),
   new GenerateReports($tenant),
   new ProcessPayment($tenant),
])->dispatch();

This isolates queued jobs per tenant and avoids cross-data issues.

D. Central Database vs Tenant Database

I separate components like this:

Central Database

• All tenants
• Subscriptions
• Billing
• System-wide settings

Tenant Database

• Employees
• Payroll
• Reports
• Logs
• Configurations

This separation has been a huge scaling advantage.

Challenges I Faced (And How I Solved Them)

1. Queue Context Issues

Sometimes queued jobs executed without tenant context

Solution:

Explicitly set tenant in queued jobs:

$this->tenant->makeCurrent();

2. Cache Leakage

Cached values from one tenant were leaking to another.

Solution:

Use tenant-scoped cache:

cache()->tenant($tenant->id)->put();

3. Migration Order Problems

If I ran central migrations after tenant migrations, conflicts appeared.

Solution:

Create a CI pipeline process: n central migrate → tenant migrate

Best Practices for Multi-Tenant Laravel Systems

• [ ] Always force tenant context in jobs & events
• [ ] Use a separate DB per tenant for high-risk / financial system
• [ ] Add logging for tenant identification issues
• [ ] Isolate cache, queue, and storage
• [ ] Build modular services per domain
• [ ] Never mix tenant & central logic in the same model

This has helped me scale to hundreds of tenants without issues.

When NOT to Use Multi-Tenancy

Avoid multi-tenancy if:

• The system is for only one organisation
• The app requires heavy, tenant-level analytics
• Government/security rules require total infrastructure isolation
• On-prem installations are required
• The tech team is very junior

A monolithic single-tenant system might be simpler in these cases.

My Conclusion

Multi-tenant architecture is powerful, cost-effective, and ideal for modern SaaS applications. With spatie/laravel-multitenancy, I’ve been able to deliver multiple production-ready platforms quickly and safely.

Laravel + Spatie gives you the structure, isolation, performance, and flexibility you need to build serious SaaS products without fighting the framework.

If you’re building SaaS in Laravel, this package is one of the best decisions you can make.