Every multi-tenant SaaS has the same problem: you need to make sure every query only returns data for the right tenant. Forget a WHERE tenant_id = ? once, and you have a data leak.

The obvious solution — a separate database per tenant — doesn't scale. Connections are expensive, migration overhead multiplies, and you lose cross-tenant reporting.

For Kumiko we went a different route: a single DB pool, but every query automatically gets the tenantId injected — without handler code ever having to do it manually.

The Idea: TenantDb Instead of a Raw DbRunner

Instead of passing a raw DB connection around, we create a TenantDb wrapper per request:

const db = createTenantDb(rawDb, tenantId)

From that point, db behaves like a normal database — but with automatic isolation baked in:

// Handler code — no tenantId needed
const users = await ctx.db.selectMany(usersTable)
// → SELECT * FROM users WHERE tenant_id IN ('tenant-123', 'system')

await ctx.db.insertOne(usersTable, { name: 'Max' })
// → INSERT INTO users (name, tenant_id) VALUES ('Max', 'tenant-123')

await ctx.db.updateMany(usersTable, { name: 'Moritz' }, { id: userId })
// → UPDATE users SET name='Moritz' WHERE id=? AND tenant_id='tenant-123'

Handlers write plain CRUD code. Isolation happens underneath — invisible, but enforced.

How the Injection Works

Reads: own rows + reference data

Read queries always see two tenants: the current one and SYSTEM_TENANT_ID. This allows reference data (e.g. global config) to be visible to all tenants without duplicating it:

// tenantId filter === [currentTenantId, SYSTEM_TENANT_ID]

If a handler passes its own tenantId in the WHERE clause, it can only narrow the scope, never widen it. A where: { tenantId: 'other-tenant' } is silently dropped.

Writes: own rows only

Inserts get tenantId forced in — and the value cannot be overridden by the caller:

// mode === "tenant": tenantId on INSERT is enforced last
return { ...data, tenantId }  // overwrites whatever the handler passed

Updates and deletes without a WHERE clause throw an error instead of hitting all rows:

// Prevents accidental mass-updates
"TenantDb.updateMany without where would mass-update all tenant rows."

System mode for operators

For admin screens there's r.systemScope() — queries run unfiltered across all tenants. Explicit opt-in only, never the default.

Tenant Resolution in Hono

TenantDb needs a tenantId. It comes from middleware that resolves it from the request — either from the hostname (for custom domains) or from the JWT:

// Middleware (simplified)
app.use('*', async (c, next) => {
  const tenant = await resolveTenant(c.req)
  c.set('db', createTenantDb(rawDb, tenant.id))
  await next()
})

Every handler then gets proper isolation through ctx.db — without a single line of tenant logic in actual feature code.

What This Means in Practice

Across three years of production use and several apps (CashColt, publicstatus, kumiko-studio) we've had zero data leak bugs from forgotten tenant filters. Not because we were particularly careful, but because it's structurally impossible to forget.

The overhead: nearly zero. A few extra conditions per query, no extra DB connection pool, no migration overhead multiplied per tenant.

If you want to try the framework: kumiko.rocks — open source under BUSL-1.1.