Use case ยท SaaS multi-tenant

One product. The right isolation per customer.

Start with many small tenants in one database. Move larger customers to a dedicated database. Give enterprise customers their own instance. NonoDB lets you change the isolation model without changing the application contract.

tenant_idDatabase per tenantScoped authVault keysUsage meteringPer-tenant restore

The SaaS problem is isolation, not CRUD

Every SaaS needs the same boring things: workspaces, users, permissions, plan limits, audit history, backups, and the ability to move a large customer without re-platforming. The database choice should make those operational, not turn them into a distributed-systems project.

Many small tenants

Share one database with a tenant_id and index it on every main query.

Larger customers

Give them a database and a token scoped to just that database.

Sensitive payloads

Use vault collections with per-tenant keys for secrets and private notes.

Enterprise isolation

Run a separate daemon and data directory when the contract requires it.

Three isolation models, one application

Pick the cheapest model that satisfies the customer and the regulator. Do not start with a dedicated cluster for every free trial.

ModelIsolationBest forWatch out for
Shared databasetenant_id in every documentMany small tenants; lowest cost per tenant.No row-level security. Application code must enforce tenant_id on every query.
Database per tenantSeparate LMDB environment and auth scopesLarger tenants, per-tenant restore, stronger access separation.One writer per open database; default limit is 64 open databases; no cross-database queries.
Instance per tenantSeparate daemon, data directory, auth registry, and networkEnterprise or regulated customers demanding dedicated infrastructure.Highest operational cost; provision and monitor it like a separate product.
There is no row-level security. Auth scopes are collection- and database-level. In a shared database, every query and update must include tenant_id in application code. If that is not acceptable, use a database per tenant and scope the token to that database.

SaaS feature map

SaaS needNonoDB featureWhat you get
Tenant isolationtenant_id plus database-scoped authKeep shared tenants in one database, or give each tenant a separate database and token.
Sensitive tenant dataVault collections with per-tenant keysEncrypt whole documents at rest while keeping only _id and tenant_id queryable.
Self-serve provisioningcreate_database plus auth principalsCreate a database and a scoped token for a new workspace.
Plan changes and lifecycleTransactional outbox eventsReact to upgrades, cancellations, and trials without dual writes.
Usage meteringEvents plus aggregationCount requests, storage, or seats and produce billing snapshots.
OnboardingWorkers and jobsSend welcome mail, seed sample data, and run checks outside the request path.
Audit and supportDocument history and GUISee what changed and inspect a tenant without writing scripts.
Per-tenant restoreBackup by databaseBack up and restore one workspace without touching the others.
Global read scaleReplication and read replicasServe tenant dashboards near users while writes stay on the primary.
Temporary dataTTL collectionsExpire invites, exports, and sessions automatically.
Existing SDKsMongoDB wire endpointUse official drivers inside the supported subset; vault needs the native client.
Day-two operationsBackups, metrics, replication, GUIRun the SaaS on one stack instead of a platform project.

The control plane and tenant data

Keep a small control-plane database for workspaces, plans, and routing. Tenant product data lives either in the shared database with tenant_id or in a database named after the tenant.

Control plane

tenants, plans, usage_counters, audit_log, and _events.

Tenant data

users, projects, documents, activity, and tenant-specific collections.

Sensitive vault

Provider credentials, private notes, and billing metadata in a vault collection.

Shared indexes

Every main index starts with tenant_id so queries and sorts stay tenant-scoped.

Shared database: start here

For many small tenants, use one database and make tenant_idpart of every document, every main index, and every query. Compound unique indexes enforce tenant-scoped uniqueness.

{"op":"create_indexes","coll":"projects","indexes":[
  {"fields":["tenant_id","slug"],"unique":true},
  {"fields":["tenant_id","owner_id","updated_at"]}
]}
{"op":"create_indexes","coll":"usage_counters","indexes":[
  {"fields":["tenant_id","period"],
   "unique":true}
]}

A missing tenant_id in a filter is a cross-tenant data leak. Put tenant resolution in one request middleware and pass the resolved ID into every repository call. Do not let handlers accept a tenant ID from the browser body.

Database per tenant: stronger separation

Create a database for each larger tenant. A scoped principal can read and write only that database, so a missed filter cannot cross the boundary. Database management still needs a separate control-plane admin token.

# Control plane only โ€” keep this token away from tenant apps
nonodb-cli databases create tenant_acme

# A tenant app can only touch its own database
nonodb-cli auth principal add acme-app read:tenant_acme/*,write:tenant_acme/*
nonodb-cli auth token create acme-app
from nonodb import NonoDB

db = NonoDB(
    "https://db.example.com:7878",
    database="tenant_acme",
    token="nodb_acme_...",
)

projects = db.collection("projects")
projects.find({"owner_id": "u_42"}, limit=20)
Plan for the open-database limit. The defaultNONODB_MAX_OPEN_DATABASES is 64, and each open database has its own writer thread. Raise it deliberately, monitor memory, and do not assume cross-database queries or transactions.

Sensitive tenant data with vault

Vault collections encrypt whole documents with a per-tenant key. Keep searchable product data in standard collections and move only secrets, billing metadata, and private notes to vault.

import os
from nonodb import NonoDB

db = NonoDB("https://db.example.com:7878", token="nodb_...")
vault = db.vault("acme", "acme:v1", os.environ["ACME_VAULT_KEY"])
secrets = vault.collection("vault")

secrets.insert({
    "tenant_id": "acme",
    "type": "billing_secret",
    "payload": {"provider": "stripe", "customer_id": "cus_123"},
})
Vault is intentionally limited. Only _id andtenant_id filters, single-document updates by _id, and history are supported. Search, fuzzy, aggregation, indexes, batch, and write_batch are rejected. MongoDB drivers cannot send vault headers.

Plans, usage, and lifecycle events

Enable events on the control-plane collections. A billing worker, welcome mailer, and provisioning worker can consume the outbox without polling the whole database. Delivery is at-least-once, so handlers must be idempotent.

{"op":"set_collection_events","coll":"projects",
 "enabled":true,"fields":["plan","status"]}
{"op":"watch","coll":"_events","types":["projects.update"],
 "filter":{"payload.after.plan":"pro"},"after":"01J..."}

Usage counters are ordinary documents. Aggregate them for invoices, dashboards, and plan-limit checks. There is no built-in quota engine; enforce quotas in the application or a worker.

{"op":"aggregate","coll":"usage_counters","pipeline":[
  {"$match":{"period":"2026-05"}},
  {"$group":{"_id":"$tenant_id",
             "requests":{"$sum":"$requests"},
             "storage_mb":{"$sum":"$storage_mb"}}},
  {"$sort":{"requests":-1}}
]}

For tenants in their own database, back up and restore one workspace at a time. The auth registry is separate from the database backup.

nonodb-cli --db tenant_acme backup   /var/lib/nonodb /var/backups/nonodb/tenant_acme
nonodb-cli verify-backup /var/backups/nonodb/tenant_acme

Security and operations checklist

When stronger isolation is the better choice

Use database-per-tenant or instance-per-tenant for those cases. The application API can stay the same while the deployment model changes.

One product. Many tenants. One database.

Start shared, graduate when the customer does.