Multi-tenancy lets one application serve many customers (tenants) while keeping each customer's data separate. It is the foundation of most SaaS products, from quoting tools to CRMs to learning platforms. Laravel is a popular choice for building them, but the architecture decisions you make early are hard to change later.
This guide explains the main multi-tenancy models, how to identify tenants, a simple Eloquent example, and the mistakes that cause real problems in production.
What is multi-tenancy?
In a multi-tenant application, many customers share the same codebase and infrastructure, but each sees only their own data, settings and users. The alternative, deploying a separate copy of the app per customer, is simpler to isolate but much more expensive to run and update.
Three common multi-tenancy models
1. Single database, shared tables (tenant_id column)
All tenants share the same tables, and every row has a tenant_id. It is the simplest and cheapest model, and easy to scale for many small tenants. The risk is that one missed filter can expose another tenant's data.
2. Single database, separate schemas
Each tenant gets its own schema inside one database (for example in PostgreSQL). Isolation is stronger than a shared table, with moderate operational complexity.
3. Database per tenant
Each tenant has a dedicated database. This gives the strongest isolation, simpler per-tenant backup and restore, and an easier path to data residency or enterprise requirements. The trade-off is more complex migrations, connection management and monitoring as tenant numbers grow.
Which should you choose?
- Many small tenants, cost-sensitive: shared tables with a tenant_id.
- Stricter isolation needs or a few large tenants: database per tenant.
- Unsure: design your code so tenant access goes through one layer, which keeps the option to move later.
How to identify the current tenant
- Subdomain:
acme.yourapp.com, the most common approach. - Custom domain:
quotes.acme.commapped to the tenant, popular for white-label products. - Path or header:
/acme/dashboardor an API header, useful for APIs and internal tools.
Resolve the tenant early in the request (middleware), store it in the container, and make the rest of the app read it from there.
Example: a tenant scope in Eloquent
For the shared-tables model, a reusable trait can apply the tenant filter automatically and set tenant_id on new records.
<?php
namespace App\Models\Concerns;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
trait BelongsToTenant
{
protected static function bootBelongsToTenant(): void
{
static::addGlobalScope('tenant', function (Builder $query) {
if (app()->bound('currentTenant')) {
$query->where(
$query->getModel()->getTable() . '.tenant_id',
app('currentTenant')->id
);
}
});
static::creating(function (Model $model) {
if (app()->bound('currentTenant') && ! $model->tenant_id) {
$model->tenant_id = app('currentTenant')->id;
}
});
}
}Use the trait on every tenant-owned model. For production, consider failing closed (throwing an exception when no tenant is set in a web request) rather than silently returning all rows.
Packages worth evaluating
You do not have to build everything yourself. Packages such as stancl/tenancy and spatie/laravel-multitenancy handle tenant resolution, database switching and queue context. Review their approach against your isolation needs before committing.
Common multi-tenancy mistakes
- Forgetting the scope. Raw queries, joins and reports can bypass model scopes. Review and test them specifically.
- Failing open. If no tenant is resolved and the scope silently does nothing, users can see everyone's data. Fail closed.
- Unscoped validation. A global unique rule can leak whether a value exists in another tenant. Scope it:
use Illuminate\Validation\Rule;
'email' => [
'required',
'email',
Rule::unique('users', 'email')
->where('tenant_id', app('currentTenant')->id),
],- Losing tenant context in queues. Jobs and scheduled tasks run outside the web request, so pass and restore the tenant explicitly.
- Shared cache and storage keys. Prefix cache keys and file paths with the tenant ID to avoid cross-tenant collisions.
- No isolation tests. Write automated tests that create two tenants and assert one can never read or modify the other's data.
- Ignoring per-tenant limits. Plan for plans, quotas, rate limits and feature flags per tenant from the start.
- Weak admin tooling. Support teams need safe ways to view and impersonate tenants, with an audit log.
Checklist before you launch
- Tenant resolution is tested for subdomains, custom domains and unknown hosts.
- All tenant-owned models use the scope, and raw queries are reviewed.
- Queues, cache, storage and mail are tenant-aware.
- Backups and a restore process are tested, ideally per tenant.
- Billing, plan limits and onboarding flow are defined.
- Security review and automated isolation tests pass.
Building a SaaS product? Our team designs and develops custom software and SaaS platforms with Laravel and React, with scalability and tenant isolation planned from the architecture stage.
Frequently asked questions
Is a tenant_id column secure enough?
It can be, if every query path is scoped, tested and fails closed. For stricter isolation requirements, a database per tenant is the safer model.
Can I change the multi-tenancy model later?
Yes, but migrating live data is expensive. Keep tenant access behind a single layer in your code to make a future change easier.
Should I use a package or build my own?
Packages save time on common problems. Build your own only if your isolation or deployment needs are unusual, and always add your own isolation tests either way.
Ready to talk about your project?
NextDigit is a Pune-based digital engineering studio building websites, custom software, mobile apps and AI-powered products. Start a conversation with our team and tell us what you want to build.
