kashifleo/multi-db-bridge

A Laravel package for managing central and tenant databases simultaneously using explicit, secure tenant connections.

v1.0.3 2025-12-19 10:21 UTC

Requires

• php: ^8.2 || ^8.3
• illuminate/database: ^11.0 || ^12.0
• illuminate/support: ^11.0 || ^12.0

Requires (Dev)

• orchestra/testbench: ^9.0 || ^10.0
• phpunit/phpunit: ^10.5 || ^11.0

MIT

• Muhammad Kashif

README

DbBridge is a Laravel package for managing central and tenant databases simultaneously using explicit, secure tenant connections.

Features

• Central-Managed Tenancy: Single central database storing tenant credentials.
• Explicit Connection: No auto-magic middleware. You control when to connect.
• Simultaneous Access: Query User::on('central') and Order::on('tenant') at the same time.
• Secure: Credentials stored in DB, not separate .env files.
• Job Support: Full support for queues and jobs with automatic tenant context preservation.

Installation

composer require kashifleo/multi-db-bridge

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Kashifleo\MultiDBBridge\DbBridgeServiceProvider"

This will create config/dbbridge.php:

return [
    'central_connection' => 'mysql', // Your main connection
    'tenant_connection' => 'tenant', // The dynamic connection name
    'tenant_model' => App\Models\Tenant::class, // Your Tenant Model
    'tenant_migrations_path' => 'database/migrations/tenants', // Path to tenant migrations
    'tenant_database_prefix' => 'tenant_', // Prefix for tenant databases
];

Usage

Tenant Model

Your App's Tenant model must implement Kashifleo\MultiDBBridge\Contracts\DbBridgeConnectionContract:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Kashifleo\MultiDBBridge\Contracts\DbBridgeConnectionContract;

class Tenant extends Model implements DbBridgeConnectionContract
{
    public function getDatabaseDriver(): string { return $this->db_driver; }
    public function getDatabaseHost(): string { return $this->db_host; }
    public function getDatabasePort(): int { return $this->db_port; }
    public function getDatabaseName(): string { return $this->db_name; }
    public function getDatabaseUsername(): string { return $this->db_username; }
    public function getDatabasePassword(): string { return $this->db_password; }
}

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Kashifleo\MultiDBBridge\Contracts\DbBridgeConnectionContract;

class Tenant extends Model implements DbBridgeConnectionContract
{
    // Tenant connection name defined
    protected $connection  = 'tenant';

    public function getDatabaseDriver(): string { return $this->db_driver; }
    public function getDatabaseHost(): string { return $this->db_host; }
    public function getDatabasePort(): int { return $this->db_port; }
    public function getDatabaseName(): string { return $this->db_name; }
    public function getDatabaseUsername(): string { return $this->db_username; }
    public function getDatabasePassword(): string { return $this->db_password; }
}

// Query Tenant DB
$orders = \App\Models\Order::find(1);

Database Management

You can programmatically manage tenant databases using the DbBridge facade. This is useful for onboarding flows.

use Kashifleo\MultiDBBridge\Facades\DbBridge;

// Generate a standard database name
// Pattern: {prefix}{id}_{slug}_{year}
$dbName = DbBridge::generateDatabaseName($tenant);
$tenant->update(['db_database' => $dbName]);

// Create the tenant's database
// This uses the 'tenant_database_prefix' from config if you use it in your model
DbBridge::createDatabase($tenant);

// Run migrations for the tenant
DbBridge::migrate($tenant);

// Drop the tenant's database (careful!)
DbBridge::dropDatabase($tenant);

Connecting to a Tenant

use Kashifleo\MultiDBBridge\Facades\DbBridge;
use App\Models\Tenant;

$tenant = Tenant::find(1);

// Connect explicitly
DbBridge::connect($tenant);

// Check connection
if (DbBridge::isConnected()) {
    $current = DbBridge::current();
}

// Disconnect
DbBridge::disconnect();

Simultaneous Database Usage

// Query Central DB (default connection)
$users = \App\Models\User::on('mysql')->get(); // or default

// Query Tenant DB
$orders = \App\Models\Order::on('tenant')->get();

Tenant Database Migrations

This package provides a robust way to manage tenant database migrations separate from your central migrations.

Configuration

Ensure your config/dbbridge.php has the migrations path configured:

'tenant_migrations_path' => 'database/migrations/tenants',

Creating Tenant Migrations

Use the dbbridge:make-migration command to create a migration file specifically for tenant databases. These files will be placed in the configured tenant migrations path.

# Create a new table
php artisan dbbridge:make-migration create_orders_table --create=orders

# Add a column to an existing table
php artisan dbbridge:make-migration add_status_to_orders_table --table=orders

Running Tenant Migrations

Use the dbbridge:migrate command to run migrations on tenant databases.

Migrate a Single Tenant:

php artisan dbbridge:migrate --id=1

Migrate All Tenants:

php artisan dbbridge:migrate --all

The command dynamically connects to each tenant's database using the credentials stored in your central database and runs the migrations found in the tenant_migrations_path.

Middleware Usage

The EnsureDbBridgeConnected middleware acts as a Guard. It aborts the request with a 403 Unauthorized error if no tenant is connected. It does not automatically connect for you; it only ensures security.

Registering the Middleware

As this is a package, you must register the middleware in your application.

For Laravel 11+ (bootstrap/app.php):

use Kashifleo\MultiDBBridge\Middleware\EnsureDbBridgeConnected;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'tenant.auth' => EnsureDbBridgeConnected::class,
    ]);
})

Applying to Routes

Use it on routes that strictly require a tenant context (e.g., dashboard, orders).

Route::middleware([
    'web', 
    'auth', 
    'tenant.auth' // Ensures a tenant is connected before proceeding
])->group(function () {
    
    Route::get('/dashboard', function () {
        return DbBridge::current()->name . ' Dashboard';
    });
    
});

Queue Support

To use tenant connections inside Queued Jobs, you should pass the Tenant model to the Job's constructor and explicitly connect within the handle method. This ensures clarity and control.

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Kashifleo\MultiDBBridge\Facades\DbBridge;
use App\Models\Tenant as TenantModel;

class ProcessTenantOrder implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    protected $tenant;

    public function __construct(TenantModel $tenant)
    {
        $this->tenant = $tenant;
    }

    public function handle()
    {
        // Explicitly connect to the tenant
        DbBridge::connect($this->tenant);

        // Perform actions on the tenant database
        // ...

        // Optional: Disconnect if needed, though the worker will likely reset for next job
        // DbBridge::disconnect();
    }
}

License

MIT