Tenant Migrations: Ensuring Data Consistency in Multi-Tenant Applications

When building multi-tenant applications with Laravel, ensuring each tenant's database schema is correctly migrated can be a challenge. In the Reimpact platform, we encountered issues with tenant schemas either re-running all migrations on each deploy or skipping them entirely. This led to potential data inconsistencies and application instability.

The Problem

Without a dedicated migration tracking table for each tenant, Laravel struggles to determine which migrations have already been applied. This can result in:

• Repeated Migrations: Migrations are executed multiple times, potentially corrupting data or causing errors.
• Skipped Migrations: New migrations are not applied, leading to outdated schemas and application malfunctions.

The Solution

To address this, we implemented a tenant_migrations table within each tenant's schema. This table tracks the migrations that have been run for that specific tenant.

Here's how it works:

1. Tenant Migration Table: A tenant_migrations table is created in each tenant's schema.
2. Automatic Seeding: When a new tenant is created, the tenant_migrations table is automatically seeded with the names of existing migrations.
3. tenants:migrate Artisan Command: A new Artisan command, tenants:migrate, is introduced to run migrations specifically for each tenant.

This ensures that migrations are only run once per tenant, preventing data corruption and ensuring schema consistency.

Example: Implementing Tenant-Aware Data Retrieval

Consider a scenario where you need to retrieve data specific to a tenant. Using a repository pattern, you might have a method like this:

<?php

namespace App\Repositories;

use App\Models\GeneratedReport;

class GeneratedReportRepository
{
    public function getTenantReports()
    {
        return GeneratedReport::where('tenant_id', auth()->user()->tenant_id)->get();
    }
}

This code snippet shows how to scope a query to a specific tenant using the tenant_id column. This ensures that users only have access to data within their own tenant.

The Benefits

By implementing tenant-specific migration tracking, we achieve:

• Data Consistency: Each tenant's schema is up-to-date and consistent.
• Improved Stability: Prevents errors caused by repeated or skipped migrations.
• Simplified Deployment: Makes deployments more reliable and predictable in multi-tenant environments.

This approach ensures a more robust and maintainable multi-tenant application, reducing the risk of data inconsistencies and improving overall system stability.