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.
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.
| Model | Isolation | Best for | Watch out for |
|---|---|---|---|
| Shared database | tenant_id in every document | Many small tenants; lowest cost per tenant. | No row-level security. Application code must enforce tenant_id on every query. |
| Database per tenant | Separate LMDB environment and auth scopes | Larger tenants, per-tenant restore, stronger access separation. | One writer per open database; default limit is 64 open databases; no cross-database queries. |
| Instance per tenant | Separate daemon, data directory, auth registry, and network | Enterprise or regulated customers demanding dedicated infrastructure. | Highest operational cost; provision and monitor it like a separate product. |
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 need | NonoDB feature | What you get |
|---|---|---|
| Tenant isolation | tenant_id plus database-scoped auth | Keep shared tenants in one database, or give each tenant a separate database and token. |
| Sensitive tenant data | Vault collections with per-tenant keys | Encrypt whole documents at rest while keeping only _id and tenant_id queryable. |
| Self-serve provisioning | create_database plus auth principals | Create a database and a scoped token for a new workspace. |
| Plan changes and lifecycle | Transactional outbox events | React to upgrades, cancellations, and trials without dual writes. |
| Usage metering | Events plus aggregation | Count requests, storage, or seats and produce billing snapshots. |
| Onboarding | Workers and jobs | Send welcome mail, seed sample data, and run checks outside the request path. |
| Audit and support | Document history and GUI | See what changed and inspect a tenant without writing scripts. |
| Per-tenant restore | Backup by database | Back up and restore one workspace without touching the others. |
| Global read scale | Replication and read replicas | Serve tenant dashboards near users while writes stay on the primary. |
| Temporary data | TTL collections | Expire invites, exports, and sessions automatically. |
| Existing SDKs | MongoDB wire endpoint | Use official drivers inside the supported subset; vault needs the native client. |
| Day-two operations | Backups, metrics, replication, GUI | Run 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-appfrom 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)NONODB_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"},
})_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_acmeSecurity and operations checklist
- Resolve tenant identity server-side; never trust a tenant_id from the browser.
- Use database-scoped tokens for database-per-tenant; keep the global admin token in the control plane only.
- Use TLS/mTLS for cross-network traffic and rotate tokens and certificates.
- Store vault keys in a secret manager, not in NonoDB or application logs.
- Index tenant_id first on the queries and sorts that drive the product.
- Monitor open databases, writer threads, disk, replication lag, and per-tenant usage.
- Back up the control plane separately from tenant data and test per-tenant restores.
When stronger isolation is the better choice
- The customer contract requires physically separate infrastructure.
- Application code cannot be trusted to enforce tenant_id consistently.
- One tenant needs its own backup, restore, encryption keys, or maintenance window.
- You need per-tenant rate limits or noisy-neighbour isolation at the process level.
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.