# MongoDB

Lightweight, dependency-free MongoDB implementation speaking the real wire
protocol (OP_MSG + BSON), so the official `mongodb` driver connects with zero
config.

| Key | Value |
|-----|-------|
| Port | 27017 |
| Protocol | Wire protocol / BSON (TCP) |
| Size | ~90 KB |
| Startup | < 300ms |

## Default Connection

```
mongodb://localhost:27017
```

No auth required. Default database: `parlel`.

## Supported Commands

### Handshake / connection

`hello`, `ismaster`, `ping`, `buildInfo`, `hostInfo`, `getParameter`,
`whatsmyuri`, `connectionStatus`, `saslStart`/`saslContinue` (accepted),
`logout`, `getLog`, `endSessions`, `refreshSessions`.

### Write

| Command | Notes |
|---------|-------|
| `insert` | Insert one or many documents (auto `_id` if absent) |
| `update` | `q`/`u` updates, `$set`/`$inc`/etc., `multi`, `upsert` |
| `delete` | Delete by filter, `limit` |
| `findAndModify` | Atomic find + update/remove |

### Read

| Command | Notes |
|---------|-------|
| `find` | Filter, projection, sort, skip, limit |
| `getMore` | Cursor pagination |
| `count` | Count documents |
| `distinct` | Distinct field values |
| `aggregate` | Pipeline: `$match`, `$group`, `$sort`, `$project`, `$limit`, ... |

### Collections / databases / indexes

`create`, `drop`, `dropDatabase`, `listCollections`, `listDatabases`,
`listIndexes`, `createIndexes`, `dropIndexes`, `renameCollection`,
`collStats`, `dbStats`, `validate`.

## Usage Examples

### Via SDK / official driver

```typescript
const instance = await startParallel({ services: [{ name: "mongodb" }] });
const port = instance.services.get("mongodb").port;

import { MongoClient } from "mongodb";
const client = new MongoClient(`mongodb://localhost:${port}`);
await client.connect();
const db = client.db("parlel");

await db.collection("users").insertMany([{ name: "Ada" }, { name: "Bob" }]);
const users = await db.collection("users").find({}).toArray();
await db.collection("users").updateOne({ name: "Ada" }, { $set: { role: "admin" } });
```

### Via CLI

```bash
parlel up mongodb      # starts on the default port 27017
mongosh "mongodb://localhost:27017/parlel"
parlel down mongodb
```

## Access via MCP (Parlel Sandbox)

When MongoDB runs inside a Parlel sandbox, drive it through the sandbox's MCP
endpoint with `parlel_execute`. The `command` is a JSON string — either a raw
Mongo command document or wrapped with an explicit `db`:

Insert:

```json
{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "parlel_execute",
    "arguments": {
      "service": "mongodb",
      "command": "{\"db\":\"parlel\",\"command\":{\"insert\":\"users\",\"documents\":[{\"name\":\"Ada\"},{\"name\":\"Bob\"}]}}"
    }
  }
}
```

Find:

```json
{ "service": "mongodb", "command": "{\"db\":\"parlel\",\"command\":{\"find\":\"users\",\"filter\":{}}}" }
```

`ObjectId` values are rendered as hex strings and `Date` values as ISO strings
in the JSON result.

## Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

| Feature | Status |
|---------|--------|
| CRUD (insert/find/update/delete) | Full support |
| Query operators (`$gt`, `$in`, `$regex`, ...) | Supported |
| Update operators (`$set`, `$inc`, `$push`, ...) | Supported |
| Aggregation pipeline | Common stages supported |
| Indexes | Stored, `_id` uniqueness enforced |
| Transactions / sessions | Accepted, not isolated |
| Change streams | Not supported |