PHPackages                             aloisogomes/laravel-db-tenant - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. aloisogomes/laravel-db-tenant

ActiveLibrary[Database & ORM](/categories/database)

aloisogomes/laravel-db-tenant
=============================

Library to help you have multiple connections to the database while keeping the context clean without changing anything in the structure of your tables

v1.0.0(5mo ago)01MITPHPPHP ^8.3CI failing

Since Dec 1Pushed 5mo agoCompare

[ Source](https://github.com/aloisogomes/laravel-db-tenant)[ Packagist](https://packagist.org/packages/aloisogomes/laravel-db-tenant)[ RSS](/packages/aloisogomes-laravel-db-tenant/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

Laravel DB Tenant
=================

[](#laravel-db-tenant)

[![GitHub Release](https://camo.githubusercontent.com/d3404d147264990e5c5506bc31ce011162e16294176c1d70fa62f183b3d3981b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f616c6f69736f676f6d65732f6c61726176656c2d64622d74656e616e74)](https://camo.githubusercontent.com/d3404d147264990e5c5506bc31ce011162e16294176c1d70fa62f183b3d3981b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f616c6f69736f676f6d65732f6c61726176656c2d64622d74656e616e74)

**Laravel DB Tenant** is a lightweight, elegant package that allows you to switch database connections "on the fly" for specific blocks of code. Unlike global configuration changes, this package uses a **Context Stack**, allowing for nested connection switches while ensuring Eloquent models remain "sticky" to the connection they were created in.

It is perfect for:

- Multi-tenant applications with separate databases per client.
- Data migration scripts moving data between connections.
- Archival systems where you need to access historical data on a separate DB.

Features
--------

[](#features)

- **Context Stacking:** Supports nested `start()` and `end()` calls.
- **Sticky Connections:** Models instantiated inside a tenant block "remember" their connection, even after the block ends.
- **Safe Transactions:** Helper to run transactions on the *current* active context.
- **Queue & Request Safety:** Automatically resets the connection stack after every HTTP request and Queue Job to prevent data leaks.
- **Zero Config:** Works out of the box with standard Laravel database configurations.

Before you start..
==================

[](#before-you-start)

This package assumes that your connections are to separate databases, but with the same table structure, precisely to take advantage of the rules defined in your models and business logic. Think, for example, of a store platform, where each store has its own database and works separately on different servers, etc... But you want to give an accountant a single platform where he can obtain data from each of the stores in just one place.

This package is not for you if you expect:
------------------------------------------

[](#this-package-is-not-for-you-if-you-expect)

- Create complex relationships between tables from different databases (joins, unions, views, etc.);
- Harmonize data from different tables;
- Alert, handle or ensure data consistency involving distinct connections;
- Manage transactions and locks in operations involving objects from different databases\*;
- Create replications, mirroring, or backups\*\*

\**You can create a script that orchestrates an operation flow ensuring the order and criteria for separate transactions, but it is not the responsibility of this package to manage that flow.*

\*\**You may create a listener in your application to manage events in your models and use this package to update another database, but handling failures or ensuring consistency is out of the scope of this project. The responsibility for these flows remains with the developer who desires this behavior.*

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require aloisogomes/laravel-db-tenant
```

Setup
-----

[](#setup)

Configure your known connections in `config/database.php` at `connections` list:

```
use Illuminate\Support\Str;

return [
  'default' => env('DB_CONNECTION', 'default'),
  // the main key of each connection will be available to our Tenant context
  'connections' => [
    'default' => [
        'driver' => 'sqlite',
        'url' => env('DB_URL'),
        'database' => env('DB_DATABASE', database_path('database.sqlite')),
        'prefix' => '',
        'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
        'busy_timeout' => null,
        'journal_mode' => null,
        'synchronous' => null,
    ],
    'legacy' => [
        'driver' => 'sqlite',
        'url' => env('DB_URL_LEGACY'),
        'database' => env('DB_DATABASE_LEGACY', database_path('database_legacy.sqlite')),
        'prefix' => '',
        'foreign_key_constraints' => env('DB_FOREIGN_KEYS_LEGACY', true),
        'busy_timeout' => null,
        'journal_mode' => null,
        'synchronous' => null,
    ],
    /******
     * 'other_conn' => [...],
     * ...
     * ****/
  ],
  // Others configs...
];
```

Add the `HasTenantConnection` trait to any Eloquent Model you want to be tenant-aware.

```
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use AloisoGomes\LaravelDbTenant\Traits\HasTenantConnection;

class User extends Model
{
    use HasTenantConnection;

    // ...
}
```

That's it. Your model is now ready to react to context switches.

Usage
-----

[](#usage)

### 1. Basic Context Switching

[](#1-basic-context-switching)

Use the `Tenant` facade to define the context. Any model retrieved inside the block will use the specified connection.

```
use AloisoGomes\LaravelDbTenant\Facades\Tenant;
use App\Models\User;

// 1. Default Context (uses default connection from .env), in our example connection named as 'default'
$defaultUser = User::find(1);

// 2. Switch to 'legacy' connection
Tenant::start('legacy');

$legacyUser = User::find(1);
// This query runs on 'lagacy'

// 3. End context (returns to previous state)
Tenant::end();
```

### 2. Sticky Connections (The Power Feature)

[](#2-sticky-connections-the-power-feature)

Models created within a tenant context retain their connection reference forever. You can manipulate and save them safely outside the tenant block.

```
Tenant::start('legacy');
$legacyUser = User::find(500);
Tenant::end();

// We are back to the default connection here
$defaultUser = User::find(1);

// UPDATE TEST:
$defaultUser->update(['name' => 'Local']); // Updates default DB
$legacyUser->update(['name' => 'Legacy']); // Updates 'legacy' automatically!
```

### 3. Nested Contexts (Stacking)

[](#3-nested-contexts-stacking)

The package manages a LIFO (Last In, First Out) stack.

```
// Stack: [] (Default)
Tenant::start('legacy');

    // Stack: ['legacy']
    $legacyUser = User::first();

    Tenant::start('other_conn');

        // Stack: ['legacy', 'other_conn']
        $otherConnUser = User::first();

    Tenant::end();

    // Stack: ['legacy'] (Back to Legacy)
    $anotherLegacyUser = User::find(500);

Tenant::end();
// Stack: [] (Back to Default)
```

### 4. Explicit Override

[](#4-explicit-override)

If you need to force a specific connection regardless of the current context, use the `tenant()` static method (alias for `on`):

```
Tenant::start('legacy');

// Forces 'default' connection even inside the 'lagacy' block
$admin = User::tenant('default')->find(1);
```

### 5. Transactions

[](#5-transactions)

To safely run transactions within the current active context (whether it is the default or a tenant), use the `transaction` helper:

```
Tenant::start('legacy');

Tenant::transaction(function () {
    // This transaction starts specifically on 'legacy' connection
    $user = User::find(1);
    $user->balance -= 100;
    $user->save();

    // If this fails, only 'legacy' is rolled back
});

Tenant::end();
```

Safety Measures
---------------

[](#safety-measures)

One of the biggest risks with runtime connection switching is "polluting" the state for subsequent requests (e.g., in Laravel Octane or Queue Workers).

This package automatically handles cleanup:

- **HTTP Requests:** The stack is reset when the app terminates (after the response is sent).
- **Queue Jobs:** The stack is reset after every Job is processed or failed.

You can also manually reset the stack at any time:

```
// Emergency reset
Tenant::reset();
```

Credits
-------

[](#credits)

- [Aloiso Gomes](https://github.com/aloisogomes)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance71

Regular maintenance activity

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

162d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cbaa2d3df46788fdd0c8228d84411f07dc3765dd6b00a0b13ca121a3bd1f6045?d=identicon)[aloisogomes](/maintainers/aloisogomes)

---

Top Contributors

[![aloisogomes](https://avatars.githubusercontent.com/u/32063861?v=4)](https://github.com/aloisogomes "aloisogomes (10 commits)")

---

Tags

connection-managerdatabase-managementdbeloquentlaravelmulti-connectionmulti-tenancymulti-tenanttenantlaraveldatabasetenantmulti-tenantmulti-databasemulti-connection

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/aloisogomes-laravel-db-tenant/health.svg)

```
[![Health](https://phpackages.com/badges/aloisogomes-laravel-db-tenant/health.svg)](https://phpackages.com/packages/aloisogomes-laravel-db-tenant)
```

###  Alternatives

[waad/laravel-model-metadata

A robust Laravel package for handling metadata with JSON casting, custom relation names, and advanced querying capabilities.

823.1k](/packages/waad-laravel-model-metadata)[nevadskiy/laravel-geonames

Populate your database using the GeoNames service.

2715.1k](/packages/nevadskiy-laravel-geonames)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)