MongoDB
A local endpoint that speaks MongoDB's wire protocol. mongosh, the Node.js driver, Mongoose and your app connect to it unchanged.
Start it
A source in sosie.yml, its connection string in a variable of yours. npx @sosie/cli writes this for you the first
time.
sources:
app:
upstream: ${APP_URL}
export APP_URL='mongodb://readonly:…@db.internal:27017/app'
npx @sosie/cli
✓ app db.internal:27017/app, read-only: 12 collections, 1 view
✓ Every value is faked
app: mongodb://127.0.0.1:7674/app?directConnection=true
The address takes no user and no password: a client that sends a login is told so. It listens on 127.0.0.1 and
::1 only, unless sosie.yml gives another host. directConnection=true tells the driver Sosie is one server, not a replica set
to discover.
The connection string names the database. Atlas’s mongodb+srv:// strings work as they are. For a replica set, give one
host and its replicaSet option: the driver finds the other members from it.
MongoDB 6.0, 7.0 and 8.0 are tested; anything older is refused at start-up.
A read-only login
Sosie runs no command that writes, but a login that cannot write is safer. Sosie warns when its login can change data or is an administrator.
db.getSiblingDB('app').createUser({ user: 'sosie_reader', pwd: '…', roles: [{ role: 'read', db: 'app' }] })
Sosie reads the database’s collections and their validators when it starts, which takes listCollections on the
database, as the read role has: a login with privileges on single collections only cannot start it.
Clients
Tested with the Node.js driver, which Mongoose uses, and checked by hand with mongosh 2. Sosie answers the handshake itself, as a standalone server, with the upstream’s version, and runs each read upstream in a session of its own. It offers no TLS and no compression on its own address: it is on your machine. A client’s sessions are taken; transactions are refused.
Over MCP
sosie mcp adds two tools for a MongoDB Sosie: find (a collection, and optionally a filter, a projection, a sort
and a limit) and aggregate (a collection and a pipeline). Each takes JSON or Extended JSON, such as
{"_id": {"$oid": "…"}}, and returns up to 200 documents as Extended JSON.
What the guard allows
Commands are documents, so Sosie needs no parser: it allows each by name, and reads each pipeline stage by stage.
- Allowed:
find,aggregate,count,distinct,getMoreandkillCursors;listCollections,listIndexes,listDatabases,listSearchIndexesanddbStats, which show the schema and sizes. - Refused: every command that writes or changes the server, with
This command changes data. Sosie is read-only.;explain, whose plan would print the real values Sosie puts in your filter;mapReduce; transactions. - Refused databases and collections:
admin(users and their password hashes),local(the oplog, every write with its values),config; andsystem.profile,system.jsandsystem.usersin any database. - Refused stages:
$outand$merge, which write;$currentOp,$listSessions,$planCacheStatsand$changeStream, which show other sessions’ queries or every change;$collStatsand$indexStats, which say where the server is; and any stage Sosie does not know the shape of. - No JavaScript on the server:
$where,$function,$accumulator, and code in a document, in a filter, a projection, a pipeline or a command’slet: what it computes cannot be read. - Answered by Sosie, not the upstream:
hello,ping,buildInfo,connectionStatus(no users),getLog(empty).hostInfo,getCmdLineOptsandserverStatusare refused: they say where the server is.
The session upstream
One client upstream, with a session for each of your client’s sessions (the lsid a driver sends), so a cursor’s
getMore reaches the session that opened it, from whichever connection of the driver’s pool sends it. A cursor is
its session’s: another client neither reads its batches nor closes it.
| Setting | Value |
|---|---|
maxTimeMS |
30 s, or the source’s timeout, on each find, aggregate, count and distinct; a client may lower it, never lift it |
| Documents per cursor | max-rows: past it, the cursor is closed, and the terminal running Sosie says so |
| A message half sent | A minute: past it, the connection is closed |
| Read preference | The connection string’s |
| Heartbeats | Polled, so no hello waits on each server |
Query by what you saw
A value compared by equality with a field is looked up in that field’s domain and turned back into the real value:
{ email: '…' }, $eq, $ne, $in, $nin and $all, inside $and, $or, $nor, $not and $elemMatch, and
a document compared whole. That holds in find, count and distinct, and in each $match of a pipeline, against
the documents it filters: a $match after a $group compares with what the group made.
Every ObjectId shares one domain, so the fake _id of a user finds that user’s orders:
db.orders.find({ userId: ObjectId('…the _id you saw…') })
What each value becomes
MongoDB’s answers say nothing of where a value came from, as Postgres’s and MySQL’s metadata do. Sosie reads it from the command: a find’s documents are its collection’s, through its projection; an aggregation’s are read stage by stage.
| The value | Becomes |
|---|---|
A field of a collection’s documents, through a projection, $project, $lookup, $unwind, $replaceRoot and $facet |
A fake by its field: collection.path |
| An ObjectId, in any field | A fake in the one domain all ObjectIds share: 24 hex digits, its time shifted by up to a year |
A $group’s _id by a field, and $first, $last, $min, $max, $push or $addToSet of one |
A fake by that field |
A count: $count, $sum: 1, the count command |
Unchanged |
A literal you wrote: $literal, a value in $documents |
Unchanged; a server’s variable there ($$NOW, $$USER_ROLES) is faked by its type |
Anything else a pipeline computes ($toUpper, $avg, $concat) |
A fake by its BSON type |
A field a $unionWith takes from two collections |
A fake by its type, unless both name the same field |
| A key that is not a word, as in a map keyed by email; a key a pipeline makes from values that you did not write | Faked, each to one fake |
Each value keeps its BSON type: an Int32 stays an Int32, and a Long, a Double, a Decimal128, a date, an
ObjectId, a UUID and binary data their own. Sosie learns each field as documents come, and from a collection’s
$jsonSchema validator: describe lists them, and sosie.yml names them as collection.path
(users.address.city).
Errors
- An error about the command itself (an unknown operator or stage, a bad option, the time limit) comes back, scrubbed of every value Sosie turned back.
- Any other comes back as its code only:
Error 241 (ConversionFailure): Sosie hides the rest of this message, which may quote a value from your documents.
Limits
- Order and ranges follow the real values:
sortorders by them, and$gtor$ltcompare them. - A regular expression,
$textand what$exprcomputes filter on the real values, so a piece of a fake finds nothing. - A value Sosie never showed is used as written, so it filters on the real value it happens to be.
- A stage Sosie does not know the shape of is refused, as is anything it cannot read: change streams, JavaScript.
- A cursor cut at
max-rowsends with nothing to say so: MongoDB has no warnings for Sosie to add one to. The terminal running Sosie says so. - A timestamp (BSON’s internal type) is faked as a date, to the second.
MinKeyandMaxKeypass. listIndexesandlistCollectionsshow an index’s filter and a view’s pipeline as they were written, a value in them included.- A fake in a
$lookup’slet, in an index bound, or in what$exprcomputes (anything but a field compared by$eq,$neor$in) is used as written. - A key that looks like a word, in a collection’s own documents, is taken for a field’s name and shown: a map stored
keyed by lowercase words (
{ prefs: { quillon: … } }) shows them. A key a pipeline makes from values is faked, unless you wrote it. - A
$unionWithmixes two collections’ documents, and MongoDB does not say which each came from: a value there is faked by its type, unless both collections name the same field.