Packstub Tenancy

• Full documentation
• Features
• Screenshots
• Installation
  • Requirements
  • Purchasing a license
  • Installing with Composer
• Getting started
• Scaling across database servers
• Dedicated or shared — your choice, per tenant
• Testing
• Documentation
• Support
• Changelog
• License

One database per tenant. Any number of database servers.

Packstub Tenancy is a premium plugin that brings stancl/tenancy v4 into Filament v5 panels, fully wired: every tenant gets its own isolated database, new signups are provisioned through your queue while they wait in a polished waiting room, and a load-balanced database pool spreads tenants across as many database servers as you need — adding capacity is one line of config. Filament's built-in tenancy is a great fit for shared-database apps; Packstub Tenancy is the bridge to database-per-tenant when isolation and scale become the requirement.

#Full documentation

Every guide — quickstart, configuration reference, horizontal scaling, custom domains, production checklist — lives at packstub.dev/docs/filament-tenancy.

#Features

• One database per tenant — structural isolation; per-tenant backup, export, or deletion is a single database
• Load-balanced database pool — list your servers, and every new tenant lands on the least-loaded one (least-tenants, round-robin, or weighted); placement is persisted and followed everywhere
• Add a server, add capacity — no proxy, no extra hop, no migration of existing tenants
• Pin tenants to a server — data-residency customers stay exactly where you put them
• Two data-separation strategies — dedicated (database per tenant) or shared (tenant_id scoping across shard databases), selectable per app and overridable per tenant
• PostgreSQL Row-Level Security for the shared strategy, via stancl's tenants:rls toolchain
• Subdomain or path identification — pick one; routing, session cookie domain, and central-domain-aware middleware are wired for you
• Custom domains per tenant — DNS TXT/CNAME verification, a tenant-facing Domains page, single-origin login handoff, and logout-everywhere
• Async provisioning pipeline — CreateDatabase → MigrateDatabase → SeedDatabase → MarkTenantReady on your queue, with a retry command for failures
• Provisioning waiting room — a Livewire-polled page that redirects the moment the tenant is ready; light and dark themes included
• Onboarding page — a Create Organization form with live slug generation, a preview of the tenant's address, and central-safe uniqueness
• Ready-tenant gating — the switcher lists only ready tenants and half-provisioned panels stay unreachable
• Pool overview widget — live tenant counts per server from any panel, plus a tenants:pool command
• Cross-database resource syncing — mirror users, catalogs, or licenses between central and tenant databases with one fluent call
• Strategy-safe defaults — Resource::scopeToTenant() follows your strategy automatically; Octane per-request reset; billing provider hooks
• Translations and publishable views — restyle the waiting room, add a locale
• Test helpers — TenantTestHelpers boots tenancy inside your own test suite with one trait

#Screenshots

Pool overview widget — live tenant counts per server with the next-placement marker

tenants:pool command — tenant distribution across three PostgreSQL servers

Onboarding — Create Organization with live slug generation and address preview

Provisioning waiting room — shown while the tenant database is being created

Tenant switcher — searchable, ready-tenants only, with a provisioning notification

#Installation

#Requirements

• MySQL, MariaDB, or PostgreSQL for tenant databases; the database user needs permission to create and drop databases
• A queue worker (tenant provisioning runs as jobs)
• Wildcard DNS for subdomain identification — Herd and Valet resolve *.myapp.test automatically

stancl/tenancy v4 has no stable tag on Packagist yet — nothing to do on your side. The Packstub registry serves a vetted v4 snapshot as a regular stable release, so a plain composer require works with default stability settings. How that works →

#Purchasing a license

Licenses are sold at packstub.dev/plugins/filament-tenancy. After purchase, sign in to your Packstub dashboard and create an access token on the Install Guide page — it shows the commands below with your token filled in.

#Installing with Composer

Add the Packstub registry and your token, then require the package:

composer config repositories.packstub-filament-tenancy composer https://packstub.dev/composer/filament-tenancy
composer config --auth http-basic.packstub.dev pkg_xxxxxxxxxxxxxxxx your-token-secret

composer require packstub/filament-tenancy

Run the interactive installer — it publishes the config, asks subdomain vs. path, writes your choice into the published config, and prints the exact wiring for your mode:

php artisan packstub-tenancy:install

Migrations run straight from the package, so plugin updates can ship schema changes with no extra steps. Prefer to own them? Publish the migrations →

#Getting started

Add two traits to your user model and register the plugin on your panel:

// app/Models/User.php
class User extends Authenticatable implements HasDefaultTenant, HasTenants
{
    use CentralConnection;     // identity lives in the central database
    use HasPackstubTenants;    // tenants, default tenant, ready-filtering
}

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->plugin(TenancyPlugin::make());
}

Start a queue worker, and your first signup provisions its own database. Full walkthrough: Quickstart →

#Scaling across database servers

Define one ordinary Laravel connection per server, list them as a pool, and every new tenant lands on the least-loaded server. Placement is persisted per tenant — provisioning, runtime connections, migrations, and deletion all follow it automatically.

TenancyPlugin::make()
    ->databasePool(['tenant-db-1', 'tenant-db-2', 'tenant-db-3'])
    // strategies: least-tenants (default) · round-robin · weighted

Need a tenant on a specific server? Pin it — pins are never rebalanced:

Organization::create([
    'name' => 'Fjord GmbH',
    'slug' => 'fjord',
    'tenancy_db_connection' => 'residency-eu-1',
]);

Strategies, the add-a-server runbook, privileges, and operations: Horizontal scaling →

#Dedicated or shared — your choice, per tenant

Both separation models ship behind one config key, and they compose: free tier in the central database, standard tier on shared shards, enterprise on private databases, regulated customers pinned to their own servers — one app, one plugin.

// config/packstub-tenancy.php
'database_strategy' => 'dedicated',  // one database per tenant (default)
'database_strategy' => 'shared',     // many tenants per database, tenant_id-scoped

// Any tenant can override the app default
Tenant::create([
    'name' => 'Enterprise Co',
    'slug' => 'enterprise',
    'isolation_mode' => 'dedicated',
]);

Setup for each model: Database strategies →

#Testing

The package ships with an extensive test suite covering provisioning success and failure paths, transaction-safe onboarding, path-mode Livewire flows, resource-syncing cascades, custom tenant models, and pool placement. A multi-server harness boots three real PostgreSQL servers and verifies end to end that tenants distribute across them, each database exists on its assigned server, and deleting a tenant drops only its own database.

Bring the same confidence to your app with the exported TenantTestHelpers trait (createTenantWithUser(), actingAsTenant(), …). Testing guide →

#Documentation

#Support

• Email: support@packstub.dev — answered within one business day
• Issues: private issue tracker access comes with your license
• Security: report privately to support@packstub.dev; tenant-isolation reports get highest priority

#Changelog

Every release is documented in the package CHANGELOG.md, with upgrade notes in UPGRADE.md. Config keys, the fluent API, and published views are treated as public API and follow semver.

#License

Packstub Tenancy is commercial software. Every license includes the full source code, 12 months of updates and support, and a perpetual license for the versions you received.

• Solo — one production project, unlimited developers
• Unlimited — unlimited projects, including client work

Redistribution and resale are not permitted; the full license agreement ships with the package. Get a license →