Tenancy
Multi-tenancy means one app serves many customer companies (tenants, or teams), and each one must only ever see its own data. A tenant table is a table with a tenant column (tenant_id, or team_id for teams) saying which tenant each row belongs to.
Strutvane’s ORM does the separation for you:
- every query on a tenant table is limited to the active tenant;
- new rows are stamped with the active tenant;
- right before any SQL is sent, a final check refuses a statement that could reach another tenant’s rows;
- with no active tenant, tenant tables return an error, never “all rows”.
You set the active tenant once per request (the HTTP layer does it for you); your queries look exactly like single-tenant ones.
The smallest example
Section titled “The smallest example”import { Model } from '@strutvane/framework'import { Task } from './task.ts'
export class Project extends Model('projects', { fillable: ['name', 'budget'] }) { tasks() { return this.hasMany(Task, 'project_id') }}The model has nothing about tenants: the projects table has a tenant_id column, and that’s enough.
import { runWithTenant } from '@strutvane/framework'
const teamA = '0193a0b2-0000-7000-8000-00000000000a'const teamB = '0193a0b2-0000-7000-8000-00000000000b'
await runWithTenant(teamA, () => Project.create({ name: 'Apollo' }))await runWithTenant(teamB, () => Project.create({ name: 'Borealis' }))
const seenByA = await runWithTenant(teamA, () => Project.all())console.log(seenByA.map((project) => project.name))What you’ll see:
[ 'Apollo' ]Team A never sees Borealis, and tenant_id was filled in for both projects without you passing it.
Making a table a tenant table
Section titled “Making a table a tenant table”-
In the table’s migration, add the tenant column. It holds a UUID: the
idof the row in your teams table.database/migrations/2026_11_14_100000_create_projects_table.ts import { migration } from '@strutvane/framework/schema'export default migration({up(schema) {schema.create('projects', (t) => {t.id()t.tenant() // tenant_id, indexedt.string('name', 120)t.slug('slug').from('name') // unique per team: (tenant_id, slug)t.decimal('budget', 12, 2).default(0)t.timestamps()})},down(schema) {schema.dropIfExists('projects')},}) -
Run
node strut migrate. The generated types now showtenant_id, and the ORM treatsprojectsas scoped. -
Write the model as usual. Don’t list
tenant_idinfillable: it’s filled in for you, and listing it is refused. -
Run every query on it inside a tenant (the next section).
Setting the active tenant
Section titled “Setting the active tenant”runWithTenant(tenantId, fn) runs fn with that tenant active. Everything inside it, however deep, uses that tenant, and concurrent calls never see each other’s tenant (the spike checks 200 interleaved requests).
- In HTTP requests, the framework wraps every request in
runWithTenantwith the signed-in user’s team, so controllers query as usual. - In jobs, commands and tests, wrap the work yourself:
await runWithTenant(teamId, async () => { const projects = await Project.query().latest().get() // …})Tenant ids are UUIDs, such as the id of the row in your teams table. currentTenant() returns the active one (or undefined).
Every way in is covered
Section titled “Every way in is covered”The tenant condition is added to every query that touches a tenant table, not only to get():
await runWithTenant(teamA, async () => { await Project.find(borealisId) // → undefined await Project.query().where('slug', 'borealis').first() // → undefined await Project.query().search('Borealis', ['name']).count() // → 0 await Project.query().paginate(10) // total: 1 await Project.query().with('tasks').withCount('tasks').get() // only A's tasks, A's counts await Project.query().whereHas('tasks', (q) => q.where('title', 'B task')).count() // → 0})OR conditions can’t escape it. Your conditions are put in brackets before the tenant condition is added:
await runWithTenant(teamA, () => Project.query().where('name', 'Apollo').orWhere('name', 'Borealis').get(),)// SQL: WHERE (name = ? OR name = ?) AND tenant_id = ?// → [ 'Apollo' ]Writes are protected too
Section titled “Writes are protected too”- New rows get the active tenant’s id.
tenant_idcan never be mass-assigned, not even withforceCreate(). - Updates and deletes always include
AND tenant_id = ?, so a model loaded as team A and saved as team B is “not found”. - Changing
tenant_idon a saved row is refused. - Pivot links (
attach,sync) first check that every id belongs to the active tenant.
await runWithTenant(teamA, async () => { const smuggled = JSON.parse(`{"name": "Trojan", "tenant_id": "${teamB}"}`) await Project.create(smuggled) // MassAssignmentError: "tenant_id" on "projects" is managed by Strutvane …})Shared tables
Section titled “Shared tables”Some tables belong to everyone: countries, plans, the users table itself. With tenancy on, every table must be either scoped (it has the tenant column) or global (marked as shared in its migration). A table that is neither is refused, so a forgotten column can’t become a leak.
schema.create('countries', (t) => { t.id() t.string('name')}, { global: true })Choosing the tenant column
Section titled “Choosing the tenant column”There is one tenant column for the whole app, set in config/tenancy.ts. Tenancy is off unless you answered yes to “Teams?” in the installer; then no table needs a tenant column or a global flag, and the tenant scope doesn’t run at all.
export default { enabled: true, // false for a single-tenant app column: 'team_id', // tenant_id by default}The framework passes these settings to the ORM at boot (configureOrm({ tenancy: { column } }), or { tenancy: false } when enabled is false), so you don’t call configureOrm yourself for this.
The deliberate exception: unsafeWithoutTenancy
Section titled “The deliberate exception: unsafeWithoutTenancy”A maintenance job or a usage report sometimes really must read across tenants. Say so explicitly, with a reason:
import { configureOrm } from '@strutvane/framework'
configureOrm({ onUnsafeTenancy: (event) => console.warn('tenancy bypass', event) }) // send to your audit log
const all = await Project.query().unsafeWithoutTenancy('nightly usage report').count()Every bypass calls onUnsafeTenancy with { kind: 'query', tables: ['projects'], reason: 'nightly usage report' }, so it shows up in your audit log. Use it in jobs, never in request code.
Raw SQL in a tenant context
Section titled “Raw SQL in a tenant context”Inside runWithTenant, raw SQL that names a tenant table is refused, because Strutvane can’t check it for a tenant condition. Use the query builder instead. Raw SQL on global tables, and outside any tenant (migrations, jobs), is allowed.
MySQL, SQLite and PostgreSQL
Section titled “MySQL, SQLite and PostgreSQL”| Protection | MySQL (default) | SQLite | PostgreSQL |
|---|---|---|---|
| ORM tenant condition on every query | ✔ the guarantee | ✔ the guarantee | ✔ first layer |
| Final SQL check before sending | ✔ | ✔ | ✔ |
Composite foreign keys (tenant_id, x) |
coming in 0.2 | coming in 0.2 | coming in 0.2 |
| Row-level security in the database | not available | not available | ✔ second layer |
| One tenant per transaction | ORM check | ORM check | enforced |
On PostgreSQL, each tenant query also sets the tenant inside the database, and row-level security (ADR-0007) refuses other tenants’ rows even if the app’s condition were bypassed. To make that work, every query on a tenant table runs inside a short transaction that sets the tenant for the database, and one transaction can only ever belong to one tenant. On MySQL and SQLite there’s no such database feature, so the ORM’s condition, its final check and attack-style tests (a tenant trying every way into another’s data) are the guarantee. Once composite foreign keys arrive, tasks also can’t point at another tenant’s project, because the foreign key will include the tenant column.
Common mistakes
Section titled “Common mistakes”No active tenant
Section titled “No active tenant”TenantRequiredError: "projects" is tenant-scoped, but no tenant is active. Wrap the work in runWithTenant(tenantId, () => …) (the HTTP layer does this for you per request). Deliberate cross-tenant jobs use .unsafeWithoutTenancy(reason), which is audited.Why: without a tenant, Strutvane can’t know whose rows you mean, so it fails instead of returning everything.
Fix: wrap the code (a job, a command, a test) in runWithTenant(teamId, async () => { … }).
A table that isn’t scoped or global
Section titled “A table that isn’t scoped or global”TenantScopeMissingError: Refusing to run SQL on "team_projects": it has no "tenant_id" column and is not marked global, so tenancy cannot protect it. Add t.tenant() to its migration, or create it with { global: true } if every tenant may see all of it. Tenant data may only be read or written for the active tenant. If this really must cross tenants (a maintenance job), use unsafeWithoutTenancy(reason) or unsafeRaw(reason, …): both are audited.Fix: add the tenant column to the table in a new migration, or mark the table as global if all tenants share it. Also check that column in config/tenancy.ts names the column your tables really use.
A tenant id that isn’t a UUID
Section titled “A tenant id that isn’t a UUID”OrmUsageError: "acme" is not a valid tenant id. Tenant ids are UUIDs, such as the id of a row in your tenants table.Fix: pass the team’s id, not its name or slug.
A bypass without a reason
Section titled “A bypass without a reason”OrmUsageError: Tenancy bypasses need a short reason for the audit log, e.g. unsafeWithoutTenancy("nightly usage report").Fix: write why: unsafeWithoutTenancy('monthly billing export').
Caching a result across requests
Section titled “Caching a result across requests”Why: a promise or value cached in memory by one request and reused by another still holds the first tenant’s data. The ORM can’t see your cache.
Fix: include the tenant id in every cache key (currentTenant()), or don’t cache tenant data in module-level variables.
Next steps
Section titled “Next steps”- Transactions: one tenant per unit of work.
- Teams & Tenancy: how teams, sign-in and tenancy fit together in an app.
- Authorization: who may do what inside one team.