> ## Documentation Index
> Fetch the complete documentation index at: https://warden.buildlab.in/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

> The second engine: command documents governed the same way as SQL.

MongoDB is Warden's second engine. Requests are command documents, not strings, and every guarantee is the same vocabulary PostgreSQL uses.

| | |
| - | - |
| Versions | MongoDB 6.0+ (standalone or replica set) |
| Certification | Strict in CI against a single-node replica set — `wardencert -engine mongodb -strict` — plus live integration tests |
| Driver | `mongo-driver v2` |

## What it provides, and who provides it

| Guarantee | Level | How |
| - | - | - |
| Record scoping | `enforced` | Lease bindings are conjoined into the document filter before it reaches the server |
| Field masking | `enforced` | Result-path masking before rows leave the gateway |
| Statement timeout | `native` | Context deadline derived from `statement_timeout_ms`; the server cancels on close |
| Attribution | `native` | Sanitised `comment` on every operation, visible in `currentOp` |
| Row limits | `enforced` | Limit injected into finds, re-capped in the gateway with honest truncation |
| Dry run | `enforced` | Count from the server plus sampled before/after images, at `estimated` fidelity; DDL reports `static` |
| Cost estimate | `advisory` | Counts only |
| Fence | `enforced` | Content hash over the targeted documents; on a replica set the staleness check and the write commit in one transaction, on standalone they run back-to-back |
| Per-agent identity | `enforced` | Gateway-side identity; no engine principal exists |
| Lease revocation | `enforced` | Sessions under a revoked lease are refused on next use |
| Transactional DDL | `unavailable` | MongoDB DDL is not transactional |

Replica-set versus standalone is probed at connect time and recorded in the capability note. Standalone has no multi-document transactions, so fences and previews are content hashes rather than transactional guarantees.

## Command grammar

```json theme={null}
{
  "verb": "find | insert | update | delete | create | drop | eval",
  "resource": "orders",
  "filter": {"id": "ord_1", "status": {"in": ["paid", "pending"]}},
  "set": {"status": "refunded"},
  "unset": ["note"],
  "fields": ["id", "status"],
  "documents": [{"id": "ord_1", "status": "paid"}],
  "from": "customers"
}
```

A value of the form `"$N"` references `params[N]`. Everything else is a literal. A key the verb does not use is refused, not ignored, so a `find` carrying `set` fails rather than passing review as a harmless read. Unknown filter operators become `unparsed_construct` and deny. A parameter holding a document or a list is refused as a filter value rather than executed: in that position the driver would read it as an operator.

## Writes carry the scope too

Reads and deletes are restricted by conjoining the lease's bindings into the
filter. Writes are restricted by what they write: an insert must set every
scoped field explicitly to the lease's value, and an update may neither assign
a scoped field a different value nor remove it. Anything else is refused
rather than corrected, so the operation that executes is the one a reviewer
approved.

## Setting it up

```yaml theme={null}
connections:
  - name: shop
    engine: mongodb
    dsn: mongodb://warden_gateway:secret@mongo.internal:27017
    policy: ./policies/shop.yaml
    options:
      database: shop
      collections: orders,customers
      statement_timeout_ms: "5000"
      max_pool_size: "10"
      application_name: warden
```

Set `database`. It may also come from the DSN path, but an empty value is refused rather than inferred silently. Set `collections` on any non-trivial database; without it the catalog includes every collection.

## Known gaps

* **Native per-lease principals.** MongoDB users and roles exist, but this connector reports gateway-enforced identity honestly rather than minting database users per lease.
* **Relationship scoping** is not supported.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.