Tenancy modes
Standard, Enterprise (cloud), and Enterprise (self-hosted) — how they differ, when to use each.
Tenelix supports three tenancy modes via the TENANCY_MODE environment
variable:
| Mode | Description | Best for |
|---|---|---|
shared | All tenants share one database, scoped by tenant_id | Cost-effective SaaS, small clinics |
enterprise | Each tenant gets a dedicated database | Large hospitals, strict compliance |
hybrid | Shared by default, dedicated on graduation (default) | Flexible SaaS with enterprise options |
Shared mode
In shared mode, all operational data lives in tenelix_tenants_shared.
Every table has a tenant_id column, and queries are automatically
scoped via Eloquent global scopes. This is the most cost-effective
model, suitable for the majority of SaaS clinics.
Enterprise mode
In enterprise mode, every tenant has a dedicated PostgreSQL database
named tenant_{uuid}. Tables don't carry a tenant_id column — the
database itself is the isolation boundary. This provides the strongest
isolation for compliance-sensitive customers (HIPAA, NDPA-2023).
Hybrid mode (recommended)
Hybrid mode combines both: tenants start in shared mode for cost efficiency, and graduate to enterprise mode when they need dedicated resources. The graduation is operational — application code is unchanged. See the Hybrid multi-tenancy blog post for the architectural detail.
Service connection management
Laravel's session, cache, and queue services need to write to the
correct tenant database. The HybridServiceConnectionBootstrapper
handles this automatically — application code keeps using
Cache::get() and Auth::user() like nothing changed.
| Service | Shared tenant | Enterprise tenant |
|---|---|---|
| Sessions | tenelix_tenants_shared.sessions | tenant_{uuid}.sessions |
| Cache | tenelix_tenants_shared.cache | tenant_{uuid}.cache |
| Queue | tenelix_tenants_shared.jobs | tenant_{uuid}.jobs |