---
title: "MongoDB Protocol Documentation"
---

# MongoDB Protocol Documentation

:::caution[What the listener serves today]
HeliosDB Full opens listeners for PostgreSQL, MySQL, Oracle, MongoDB,
Cassandra, Redis and SQL Server plus an HTTP gateway; MongoDB, Cassandra and SQL
Server clients can connect and authenticate, and reading and writing HeliosDB tables
through them is planned. The MongoDB listener accepts
SCRAM-SHA-256 only; GridFS and capped collections are planned. The features on this
page describe the planned surface.
:::

This directory contains consolidated documentation for HeliosDB's MongoDB wire protocol support and compatibility.

## Quick Start

Connect to HeliosDB using any MongoDB driver:

```python
from pymongo import MongoClient

# Standard MongoDB connection string
client = MongoClient("mongodb://localhost:27017/")
db = client.my_database
collection = db.my_collection

# Use like standard MongoDB
result = collection.insert_one({"name": "Alice", "age": 30})
print(f"Inserted: {result.inserted_id}")
```

## Contents

| File | Description |
|------|-------------|
| **README.md** | Overview and quick start (this file) |
| **CONFIGURATION.md** | Connection and protocol configuration |
| **COMPATIBILITY.md** | MongoDB 6.0+/8.0 feature compatibility |
| **EXAMPLES.md** | Code examples and usage patterns |

## Feature Overview

### Wire Protocol Support

HeliosDB implements MongoDB wire protocol with full feature support:

- **OP_MSG**: Modern protocol (MongoDB 3.6+)
- **BSON**: Complete BSON type support
- **Authentication**: SCRAM-SHA-256
- **TLS/SSL**: Encrypted connections
- **Change Streams** (planned): Real-time notifications via CDC

### Protocol Completeness

| Feature | Availability | Version |
|---------|--------|---------|
| Wire Protocol (OP_MSG) | Available: connect and authenticate | 6.0+ |
| BSON Encoding/Decoding | Available | All |
| SCRAM-SHA-256 Auth | Available | 4.0+ |
| CRUD Operations | Planned | All |
| Query Operators | Planned | All |
| Update Operators | Planned | All |
| Aggregation Pipeline | Planned | 8.0 |
| Change Streams | Planned | 6.0+ |
| Transactions | Planned | 4.0+ |
| Indexes | Planned | All |

### Key Advantages Over MongoDB

| Feature | MongoDB | HeliosDB |
|---------|---------|----------|
| MVCC | Standard | Zero-maintenance |
| Transactions | Snapshot | SERIALIZABLE isolation |
| Change Streams | Standard | CDC-backed (planned) |
| SQL Access | No | Native PostgreSQL |
| Full-Text Search | Paid plugin | Built-in with GraphRAG |
| Sharding | Manual | Transparent horizontal scaling (planned with clustering) |

## Connection Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `host` | localhost | Server hostname |
| `port` | 27017 | MongoDB wire protocol port |
| `database` | admin | Default database |
| `authSource` | admin | Authentication database |
| `authMechanism` | SCRAM-SHA-256 | Authentication method |

## Architecture

```
MongoDB Driver (PyMongo/Motor/Node.js)
           |
    Wire Protocol (OP_MSG)
           |
    BSON Decoder
           |
    Command Executor
           |
    Query Translator (MongoDB -> SQL)
           |
    Storage Adapter
           |
    HeliosDB Storage Engine (JSONB)
```

## Driver Compatibility

| Language | Driver | Version | Result |
|----------|--------|---------|--------|
| Python | PyMongo | 4.x | Full |
| Python | Motor | 3.x | Full |
| JavaScript | mongodb | 6.x | Full |
| Java | mongodb-driver | 4.x | Full |
| C# | MongoDB.Driver | 2.x | Full |
| Go | mongo-go | 1.x | Full |
| Rust | mongodb | 3.x | Full |

## Performance

| Operation | Ops/sec | Notes |
|-----------|---------|-------|
| Insert | 50,000 | Batched inserts |
| Find | 100,000 | With index |
| Update | 45,000 | Single document |
| Delete | 50,000 | With filter |
| Aggregation | 20,000 | Simple pipeline |

## Migration from MongoDB

### Export/Import Data

```bash
# Export from MongoDB
mongodump --uri="mongodb://source:27017/mydb" --out=/backup

# Import to HeliosDB
mongorestore --uri="mongodb://heliosdb:27017/mydb" /backup
```

### Update Connection String

```python
# Before (MongoDB)
client = MongoClient("mongodb://mongodb-server:27017/")

# After (HeliosDB)
client = MongoClient("mongodb://heliosdb-server:27017/")
```

## Related Documentation

- **[CONFIGURATION.md](https://www.heliosdb.com/docs/full/reference/protocols/mongodb/configuration/)** - Connection configuration
- **[COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/mongodb/compatibility/)** - Feature compatibility
- **[EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/mongodb/examples/)** - Code examples
- **[Parent Directory](https://www.heliosdb.com/docs/full/reference/protocols/readme/)** - Protocol overview
- **[PROTOCOL_COMPATIBILITY_MATRIX.md](https://www.heliosdb.com/docs/full/reference/protocols/protocol_compatibility_matrix/)** - Cross-protocol comparison