Database
The kits use two kinds of database on the same server. Each tenant gets its own database, so tenant data is physically separate and one tenant can't query another tenant's rows.
| Central database | Tenant database | |
|---|---|---|
| Name | DB_DATABASE | tenant<id>, one per tenant |
| Holds | Tenants, domains, central users, global settings, the queue | That tenant's users, roles, menus and sessions |
| Migrations | database/migrations | database/migrations/tenant |
| Seeder | DatabaseSeeder | tenant\TenantDatabaseSeeder |
Migrations
Central and tenant migrations live in different folders and run with different commands.
| Folder | Runs on | Command |
|---|---|---|
database/migrations | Central database | php artisan migrate |
database/migrations/tenant | Every tenant database | php artisan tenants:migrate (also runs automatically when a tenant is created) |
Put migrations in the right folder
A migration in database/migrations never reaches the tenant databases, and it works the same the other way round. Tables that both contexts need (users, menus, permissions, cache, jobs) exist in both folders.
For example, to add a tenant table:
php artisan make:migration create_projects_table --path=database/migrations/tenant
php artisan tenants:migrateThere are a few more tenant commands. Each one accepts --tenants=<id> if you only want to target specific tenants:
| Command | Does |
|---|---|
tenants:rollback | Roll back tenant migrations |
tenants:migrate-fresh | Drop and re-run tenant migrations |
tenants:seed | Run the tenant seeder |
tenants:list | List tenants |
tenants:run | Run any artisan command per tenant |
The tenant migration path comes from migration_parameters in config/tenancy.php.
Seeders
| Seeder | Context | Calls |
|---|---|---|
Database\Seeders\DatabaseSeeder | Central (php artisan db:seed) | RoleSeeder, PermissionSeeder, MenuSeeder, DefaultUserSeeder |
Database\Seeders\tenant\TenantDatabaseSeeder | Tenant (tenants:seed, tenant creation) | tenant\RoleSeeder, PermissionSeeder, tenant\MenuSeeder, DefaultUserSeeder |
RoleSeeder and PermissionSeeder work in both contexts. They check tenancy()->initialized to pick the guard (web or tenant) and the permission folder. For what ends up in the database, see Local development → Seeded data.
Tenant database naming
stancl builds each tenant database name from prefix + tenant id + suffix. Tenant IDs are auto-increment integers (App\Models\Tenant), so you get tenant1, tenant2 and so on.
Key in config/tenancy.php | Vue, Svelte | React |
|---|---|---|
database.prefix | 'tenant' | env('TENANCY_DB_PREFIX', 'tenant') |
database.suffix | '' | '' |
Sharing a MySQL server
If two apps on one server use the same prefix, both will try to create tenant1. Pick a unique prefix per app (for example acme_tenant) before the first tenant is created. In the React kit, set TENANCY_DB_PREFIX. In Vue and Svelte, edit config/tenancy.php.
What drops a tenant database, and what doesn't:
| Action | Tenant database |
|---|---|
| Delete a tenant in the UI | Dropped (TenantDeleted → DeleteDatabase) |
migrate:fresh on the central database | Not dropped |
Key tables
Central
| Table | Model | Notes |
|---|---|---|
users | App\Models\User | Includes locale, invited_at, 2FA columns |
tenants | App\Models\Tenant | first_name, last_name, email, phone, company, team_size + data JSON (industry, status, work week, ...) |
domains | App\Models\Domain | domain (unique), tenant_id, is_primary, locale, app_name, auth_features JSON |
menus | App\Models\Menu | Central navigation |
layout_settings | App\Models\LayoutSetting | user_id = null row is the global default |
settings | App\Models\Setting | Key/JSON value store (e.g. tenant_maintenance) |
roles, permissions, model_has_*, role_has_permissions | spatie | Guard web |
passkeys | Fortify | |
sessions, cache, cache_locks, password_reset_tokens | Laravel | |
jobs, job_batches, failed_jobs | Laravel | Used by all tenants (see Configuration) |
Tenant
| Table | Notes |
|---|---|
users, password_reset_tokens, sessions | Tenant accounts |
passkeys | |
menus, layout_settings | Tenant navigation and layouts |
roles, permissions, pivots | Guard tenant |
cache, cache_locks | |
jobs, job_batches, failed_jobs | Created, but the queue writes to the central connection |
Testing database
Tests never touch MySQL. phpunit.xml uses SQLite in memory (DB_CONNECTION=sqlite, DB_DATABASE=:memory:), and Pest applies RefreshDatabase to tests/Feature. There's more in Testing.