Table of Contents

1. What is Multi-Tenancy?

2. Multi-Tenancy Strategies

3. Use Cases

4. Overview

5. Installation

6. Database Structure

7. Migrations Setup

8. Database Configuration

9. Running Landlord Migrations

10. Creating Tenants

11. Running Tenant Migrations

12. Configuring multitenancy.php

13. Tenant Finder

14. Switch Tenant Tasks

15. Tenant Asset Handling

16. Virtual Host Setup (Nginx)

17. Tips & Gotchas

What is Multi-Tenancy?

Multi-tenancy is a software architecture where a single application instance serves multiple independent customers (tenants). Each tenant believes they have a dedicated product — their own data, their own configuration, sometimes their own branding — but under the hood, they all run on the same codebase and infrastructure.

Think of it like an apartment building: one building, many separate units. Residents share the structure, the plumbing, and the electricity, but each unit is private. Nobody walks into their neighbour's flat.

In web applications, a tenant is typically an organisation, a company, or a distinct customer account. The landlord is the platform itself — the part that manages tenants, billing, and global configuration.

                  ┌─────────────────────────────────────┐
                  │       Your Laravel Application       │
                  │          (Single Codebase)           │
                  └──────────┬──────────────┬────────────┘
                             │              │
               ┌─────────────▼──┐      ┌───▼─────────────┐
               │   Tenant A     │      │   Tenant B       │
               │  acme.app.com  │      │  globex.app.com  │
               │  [own DB]      │      │  [own DB]        │
               └────────────────┘      └──────────────────┘

Multi-Tenancy Strategies

There are three common approaches, each with different trade-offs:

This guide uses the separate database strategy. It offers the strongest data isolation, makes it trivial to backup or restore a single tenant, and lets you place tenants on different database servers if needed. The trade-off is slightly more operational overhead when onboarding new tenants.

Use Cases

Multi-tenancy is the backbone of most SaaS products. You might need it if you're building:

• HR or payroll platforms — each company's employee data must be completely isolated from others

• Project management tools — think Jira, Asana, Linear; each organisation manages their own projects and users

• CRM systems — customer and sales data is sensitive and must never leak between organisations

• E-commerce platforms — each store owner manages their own products, orders, and customers

• School or university management systems — each institution has its own students, courses, and grades

• Accounting or invoicing software — financial data requires strict isolation for compliance reasons

• Helpdesk / ticketing systems — each company's support tickets and agents are private

• White-label SaaS — you build one product, and other businesses run it under their own brand and domain

The common thread: you are building one product that many independent organisations pay to use, and those organisations must not see each other's data.

Overview

This guide walks through a multiple database multi-tenancy setup using spatie/laravel-multitenancy. The architecture is:

• One landlord database — stores tenant records (domain, credentials, etc.)

• One database per tenant — fully isolated data per tenant

Each incoming request is matched to a tenant by its domain. The app then dynamically switches the database connection, log channel, and storage paths for that tenant.

Installation

composer require spatie/laravel-multitenancy

Publish the config and migrations:

php artisan vendor:publish --provider="Spatie\Multitenancy\MultitenancyServiceProvider" --tag="multitenancy-migrations"
php artisan vendor:publish --provider="Spatie\Multitenancy\MultitenancyServiceProvider" --tag="multitenancy-config"

Database Structure

Organise your migrations into two folders to keep landlord and tenant migrations separate:

database/
  migrations/
    landlord/       ← landlord-only migrations (tenants table, etc.)
    tenant/         ← per-tenant migrations (your app tables)

This makes it much cleaner to migrate each side independently.

Migrations Setup

After publishing, move the generated create_tenants_table migration into database/migrations/landlord/. Then update it to include the fields your tenants need:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up()
    {
        Schema::create('tenants', function (Blueprint $table) {
            $table->id();

            $table->string('name');
            $table->string('domain')->unique();
            $table->string('database');

            $table->string('db_driver');
            $table->string('db_host');
            $table->unsignedInteger('db_port');
            $table->string('db_username');
            $table->text('db_password');   // store encrypted (recommended)
            $table->string('db_charset');
            $table->string('db_collation');

            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::dropIfExists('tenants');
    }
};

Why remove nullable()? Every tenant should have full database credentials. Making them non-nullable enforces data integrity and prevents silent connection failures caused by missing credentials.

Database Configuration

Add two named connections to config/database.php: one for the landlord database and a template for tenant connections.

'landlord' => [
    'driver'    => 'mysql',
    'url'       => env('DATABASE_URL'),
    'host'      => env('DB_HOST', '127.0.0.1'),
    'port'      => env('DB_PORT', '3306'),
    'database'  => env('DB_DATABASE', 'forge'),
    'username'  => env('DB_USERNAME', 'forge'),
    'password'  => env('DB_PASSWORD', ''),
    'unix_socket' => env('DB_SOCKET', ''),
    'charset'   => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix'    => '',
    'prefix_indexes' => true,
    'strict'    => true,
    'engine'    => null,
    'options'   => extension_loaded('pdo_mysql') ? array_filter([
        (PHP_VERSION_ID >= 80500
            ? \Pdo\Mysql::ATTR_SSL_CA
            : \PDO::MYSQL_ATTR_SSL_CA) => env('MYSQL_ATTR_SSL_CA'),
    ]) : [],
],

'tenant' => [
    'driver'    => 'mysql',
    'host'      => env('DB_HOST'),
    'port'      => env('DB_PORT', 3306),
    'database'  => null,   // ← filled dynamically at runtime
    'username'  => env('DB_USERNAME'),
    'password'  => env('DB_PASSWORD'),
    'charset'   => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
],

The tenant connection has database: null intentionally — it acts as a template. At runtime, SwitchTenantDatabaseTask copies this config and fills in the actual values from the tenant record.

Running Landlord Migrations

php artisan migrate --path=database/migrations/landlord --database=landlord

This creates the tenants table in your landlord database only.

Creating Tenants

You can create tenants directly in the database or via Tinker:

php artisan tinker

Tenant::create([
    'name'         => 'acme',
    'domain'       => 'acme.yourdomain.com',
    'database'     => 'acme_db',
    'db_driver'    => 'mysql',
    'db_host'      => '127.0.0.1',   // see note below
    'db_port'      => 3306,
    'db_username'  => 'root',
    'db_password'  => 'your_password',
    'db_charset'   => 'utf8mb4',
    'db_collation' => 'utf8mb4_unicode_ci',
]);

Note on db_host in Docker: If your app is running inside a Docker container, 127.0.0.1 refers to the container itself — not your host machine or the database container. Use the Docker service name (e.g. mysql, db) defined in your docker-compose.yml instead. For example, if your database service is named mysql, use db_host: 'mysql'.

Note on domain for localhost: If you're running on localhost:8080, set the domain as localhost or use a subdomain like app.localhost. Note that assets may not resolve correctly on non-standard ports — see the Virtual Host Setup section.

Running Tenant Migrations

Run migrations for all tenants at once:

php artisan tenants:artisan "migrate --database=tenant"

If your tenant migrations are in a specific folder (as set up in this guide):

php artisan tenants:artisan "migrate --path=database/migrations/tenant --database=tenant"

Run migrations for a single tenant by ID:

php artisan tenants:artisan "migrate --path=database/migrations/tenant --database=tenant" --tenant=1

The tenants:artisan command loops through all tenants (or the specified one), makes each tenant current, and runs the Artisan command in that tenant's context.

Configuring multitenancy.php

Below is a full annotated config/multitenancy.php:

return [
    /*
     |--------------------------------------------------------------------------
     | Tenant Finder
     |--------------------------------------------------------------------------
     | Resolves which tenant owns the current request.
     | Your custom finder should extend TenantFinder.
     */
    'tenant_finder' => \App\Multitenancy\TenantFinder\DomainTenantFinder::class,

    /*
     | Fields used by `tenants:artisan` to match a tenant (e.g. --tenant=1).
     */
    'tenant_artisan_search_fields' => ['id'],

    /*
     |--------------------------------------------------------------------------
     | Switch Tenant Tasks
     |--------------------------------------------------------------------------
     | These tasks run in order whenever a tenant becomes "current".
     | Each must implement SwitchTenantTask.
     */
    'switch_tenant_tasks' => [
        \Spatie\Multitenancy\Tasks\PrefixCacheTask::class,           // prefixes cache keys
        \App\Multitenancy\Tasks\SwitchTenantDatabaseTask::class,     // switches DB connection
        \Spatie\Multitenancy\Tasks\SwitchRouteCacheTask::class,      // scopes route cache
        \App\Multitenancy\Tasks\SwitchTenantLogTask::class,          // per-tenant log files
        \App\Multitenancy\Tasks\SwitchTenantStorageTask::class,      // per-tenant file storage
    ],

    'tenant_model' => \Spatie\Multitenancy\Models\Tenant::class,

    /*
     | When true, queued jobs automatically carry the current tenant's ID
     | and restore that tenant when the job executes.
     */
    'queues_are_tenant_aware_by_default' => true,

    'tenant_database_connection_name'  => 'tenant',
    'landlord_database_connection_name' => 'landlord',

    'current_tenant_context_key'   => 'tenantId',
    'current_tenant_container_key' => 'currentTenant',

    'shared_routes_cache' => false,

    'actions' => [
        'make_tenant_current_action'    => \Spatie\Multitenancy\Actions\MakeTenantCurrentAction::class,
        'forget_current_tenant_action'  => \Spatie\Multitenancy\Actions\ForgetCurrentTenantAction::class,
        'make_queue_tenant_aware_action' => \Spatie\Multitenancy\Actions\MakeQueueTenantAwareAction::class,
        'migrate_tenant'                => \Spatie\Multitenancy\Actions\MigrateTenantAction::class,
    ],

    'queueable_to_job' => [
        \Illuminate\Mail\SendQueuedMailable::class          => 'mailable',
        \Illuminate\Notifications\SendQueuedNotifications::class => 'notification',
        \Illuminate\Queue\CallQueuedClosure::class          => 'closure',
        \Illuminate\Events\CallQueuedListener::class        => 'class',
        \Illuminate\Broadcasting\BroadcastEvent::class      => 'event',
    ],

    'tenant_aware_interface'     => \Spatie\Multitenancy\Jobs\TenantAware::class,
    'not_tenant_aware_interface' => \Spatie\Multitenancy\Jobs\NotTenantAware::class,

    'tenant_aware_jobs'     => [],
    'not_tenant_aware_jobs' => [],
];

Tenant Finder

The TenantFinder is called on every request to resolve which tenant is active.

<?php

namespace App\Multitenancy\TenantFinder;

use Illuminate\Http\Request;
use Spatie\Multitenancy\Models\Tenant;
use Spatie\Multitenancy\TenantFinder\TenantFinder;

class DomainTenantFinder extends TenantFinder
{
    public function findForRequest(Request $request): ?Tenant
    {
        // getHost() strips the port number automatically
        \(host = \)request->getHost();

        // In production, bypass landlord/admin domains — they don't belong to a tenant
        if (env('APP_ENV') === 'production') {
            if (in_array($host, ['localhost', 'landlord.yourdomain.com'], true)) {
                return null;
            }
        }

        return Tenant::query()->where('domain', $host)->first();
    }
}

How it works:

1. $request->getHost() extracts just the hostname (no port). For tenant1.example.com:8080 it returns tenant1.example.com.

2. In production, certain hostnames (admin panels, the landlord app) are excluded — returning null means no tenant context is set, so the app behaves as the landlord/default app.

3. A simple WHERE domain = ? query finds the matching tenant record. If none is found, null is returned and Spatie will leave the app in "no tenant" mode.

Switch Tenant Tasks

Tasks are classes that run (in order) when a tenant becomes current, and again when a tenant is forgotten (i.e., at the end of a request or job). They are the heart of the isolation mechanism.

SwitchTenantDatabaseTask

This is the most critical task — it physically switches the active database connection.

<?php

namespace App\Multitenancy\Tasks;

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Config;
use Spatie\Multitenancy\Contracts\IsTenant;
use Spatie\Multitenancy\Tasks\SwitchTenantTask;

class SwitchTenantDatabaseTask implements SwitchTenantTask
{
    public function makeCurrent(IsTenant $tenant): void
    {
        $connectionName = config('multitenancy.tenant_database_connection_name', 'tenant');

        // Copy the template connection config from database.php
        \(base = Config::get("database.connections.{\)connectionName}", []);

        // Override with tenant-specific values
        \(new = \)base;
        \(new['database']   = \)tenant->database;
        \(new['driver']     = \)tenant->db_driver    ?: ($base['driver']    ?? 'mysql');
        \(new['host']       = \)tenant->db_host      ?: ($base['host']      ?? null);
        \(new['port']       = \)tenant->db_port      ?: ($base['port']      ?? null);
        \(new['username']   = \)tenant->db_username  ?: ($base['username']  ?? null);
        \(new['password']   = \)tenant->db_password  ?: ($base['password']  ?? null);
        \(new['charset']    = \)tenant->db_charset   ?: ($base['charset']   ?? null);
        \(new['collation']  = \)tenant->db_collation ?: ($base['collation'] ?? null);

        // Apply new config, purge old connection, open a fresh one
        Config::set("database.connections.{\(connectionName}", \)new);
        DB::purge($connectionName);
        DB::reconnect($connectionName);

        // Make this the default connection so models don't need explicit connection names
        DB::setDefaultConnection($connectionName);
    }

    public function forgetCurrent(): void
    {
        $connectionName = config('multitenancy.tenant_database_connection_name', 'tenant');
        DB::purge($connectionName);

        // Revert to landlord as the default
        $landlord = config('multitenancy.landlord_database_connection_name', 'landlord');
        DB::setDefaultConnection($landlord);
    }
}

How it works:

• makeCurrent takes the tenant connection from config/database.php as a base template, then patches it with the current tenant's credentials. It then calls DB::purge() to discard any cached connection, and DB::reconnect() to open a fresh one.

• Setting DB::setDefaultConnection() means all Eloquent models that don't specify a connection will automatically use the tenant database.

• forgetCurrent tears down the tenant connection and hands the default back to the landlord — preventing data leaking between requests.

SwitchTenantLogTask

Isolates logs so each tenant's activity is written to its own log file.

<?php

namespace App\Multitenancy\Tasks;

use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\File;
use Illuminate\Support\Facades\Log;
use Spatie\Multitenancy\Contracts\IsTenant;
use Spatie\Multitenancy\Tasks\SwitchTenantTask;

class SwitchTenantLogTask implements SwitchTenantTask
{
    public function makeCurrent(IsTenant $tenant): void
    {
        \(tenantKey = (string) \)tenant->name; // or domain, id, uuid — your choice

        \(dir = storage_path("logs/tenants/{\)tenantKey}");
        File::ensureDirectoryExists($dir);

        Config::set('logging.channels.daily.path', "{$dir}/laravel.log");

        // Force the logger to re-resolve with the new path
        app()->forgetInstance('log');
        Log::getLogger();
    }

    public function forgetCurrent(): void
    {
        Config::set('logging.channels.daily.path', storage_path('logs/laravel.log'));
        app()->forgetInstance('log');
        Log::getLogger();
    }
}

How it works:

• Overrides the daily channel's path to point to storage/logs/tenants/{name}/laravel.log.

• After changing config, the logger instance is flushed from the container so the next log write picks up the new path.

• forgetCurrent restores the default path.

Tip: Use \(tenant->id or \)tenant->domain as the key if name might contain spaces or characters that are invalid in directory names.

SwitchTenantStorageTask

Redirects file storage so uploaded files from different tenants don't collide.

<?php

namespace App\Multitenancy\Tasks;

use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\File;
use Spatie\Multitenancy\Contracts\IsTenant;
use Spatie\Multitenancy\Tasks\SwitchTenantTask;

class SwitchTenantStorageTask implements SwitchTenantTask
{
    protected array $original = [];

    public function __construct()
    {
        // Cache the original values so forgetCurrent can restore them
        $this->original = [
            'public_root' => config('filesystems.disks.public.root'),
            'public_url'  => config('filesystems.disks.public.url'),
        ];
    }

    public function makeCurrent(IsTenant $tenant): void
    {
        \(tenantKey = (string) \)tenant->getKey();

        \(publicRoot = storage_path("app/public/tenants/{\)tenantKey}");
        File::ensureDirectoryExists($publicRoot);

        $scheme = request()?->getScheme() ?? 'http';
        \(publicUrl = "{\)scheme}://{\(tenant->domain}/storage/tenants/{\)tenantKey}";

        Config::set('filesystems.disks.public.root', $publicRoot);
        Config::set('filesystems.disks.public.url', $publicUrl);

        // Flush the filesystem manager so it re-resolves with new config
        app()->forgetInstance('filesystem');
    }

    public function forgetCurrent(): void
    {
        Config::set('filesystems.disks.public.root', $this->original['public_root']);
        Config::set('filesystems.disks.public.url', $this->original['public_url']);
        app()->forgetInstance('filesystem');
    }
}

How it works:

• Physical path: Files are stored under storage/app/public/tenants/{id}/. This keeps files from all tenants under the same storage/app/public tree, but isolated in subfolders.

• Public URL: The url is set to https://{tenant.domain}/storage/tenants/{id}, which maps through Laravel's storage:link symlink (public/storage => storage/app/public).

• The filesystem singleton is flushed so the new disk config is picked up immediately.

Tenant Asset Handling

Add this helper function (e.g., in app/helpers.php):

if (! function_exists('tenant_asset')) {
    function tenant_asset(string \(path, string \)disk = 'public'): string
    {
        return \Illuminate\Support\Facades\Storage::disk(\(disk)->url(\)path);
    }
}

Register it in your composer.json autoload section:

"autoload": {
    "files": [
        "app/helpers.php"
    ]
}

Then run composer dump-autoload.

Usage in Blade:

<img src="{{ tenant_asset('avatars/profile.jpg') }}" alt="Profile">

Why not asset()? The standard asset() helper generates URLs relative to the public/ folder, with no awareness of tenant context. tenant_asset() uses the Storage disk, which at this point has already been redirected to the tenant's subdirectory by SwitchTenantStorageTask.

Important: This only works correctly when the domain is accessed directly (e.g. tenant.yourdomain.com). If you're on localhost:8080, the generated URL will be http://localhost/storage/... — missing the port — and assets will fail to load. See the next section for the fix.

Virtual Host Setup (Nginx)

Running on localhost:8080 breaks asset URLs because SwitchTenantStorageTask builds the URL from the tenant's domain (e.g. http://app.localhost), not http://localhost:8080. To solve this, set up a local Nginx virtual host that proxies to your dev server.

Step 1 — Install Nginx (if needed)

sudo apt update
sudo apt install nginx
sudo systemctl start nginx
sudo systemctl enable nginx

Step 2 — Create a virtual host config

cd /etc/nginx/sites-available
sudo nano app.localhost

Paste:

server {
    listen 80;
    server_name app.localhost;

    location / {
        proxy_pass         http://localhost:8080;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Replace app.localhost with your tenant domain (e.g. tenant1.test) and 8080 with your dev server port.

Step 3 — Enable the site

sudo ln -s /etc/nginx/sites-available/app.localhost /etc/nginx/sites-enabled/
sudo nginx -t       # verify config
sudo systemctl reload nginx

Step 4 — Update /etc/hosts

sudo nano /etc/hosts

Add:

127.0.0.1   app.localhost
127.0.0.1   tenant1.test
127.0.0.1   tenant2.test

Add a line for every tenant domain you're testing locally.

Now requests to http://app.localhost route through Nginx → your Laravel dev server, and asset URLs generated by tenant_asset() will resolve correctly.

Tips & Gotchas

Docker hosts Inside a Docker container, 127.0.0.1 is the container itself. Use the service name from docker-compose.yml as db_host (e.g. mysql or db).

Encrypt passwords Use Laravel's encrypted cast on the Tenant model for db_password so it's never stored in plaintext:

protected $casts = ['db_password' => 'encrypted'];

The SwitchTenantDatabaseTask will receive the already-decrypted value automatically.

Don't forget storage:link Run php artisan storage:link so public/storage symlinks to storage/app/public. Without this, tenant file URLs return 404.

Tenant-aware queues With queues_are_tenant_aware_by_default: true, dispatched jobs automatically carry the current tenant ID and restore it when executing. If a specific job should NOT be tenant-aware, implement \Spatie\Multitenancy\Jobs\NotTenantAware.

Seeding per tenant To run a seeder for a specific tenant:

php artisan tenants:artisan "db:seed --class=TenantSeeder" --tenant=1

Rolling back tenant migrations

php artisan tenants:artisan "migrate:rollback --path=database/migrations/tenant --database=tenant" --tenant=1