---
title: "MongoDB Protocol Configuration"
---

# MongoDB Protocol Configuration

:::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.
:::

Complete configuration reference for HeliosDB's MongoDB protocol implementation.

## Server Configuration

### Network Settings

```toml
[mongodb]
# Listen address for MongoDB wire protocol
listen_address = "0.0.0.0"

# MongoDB wire protocol port (default: 27017)
port = 27017

# Maximum concurrent connections
max_connections = 1000

# Connection timeout in seconds
connection_timeout = 30

# Idle connection timeout (0 = disabled)
idle_timeout = 600
```

### Authentication

```toml
[mongodb.auth]
# Enable authentication
enabled = true

# Authentication mechanism: "SCRAM-SHA-256", "MONGODB-X509"
mechanism = "SCRAM-SHA-256"

# Authentication database
auth_source = "admin"

# User credentials file
users_file = "/etc/heliosdb/mongodb_users.json"
```

### TLS/SSL Configuration

```toml
[mongodb.ssl]
# Enable TLS
enabled = false

# Certificate files
cert_file = "/etc/heliosdb/server.crt"
key_file = "/etc/heliosdb/server.key"
ca_file = "/etc/heliosdb/ca.crt"

# Require client certificates
require_client_cert = false

# Minimum TLS version
min_version = "1.2"
```

### Wire Protocol Settings

```toml
[mongodb.protocol]
# Maximum message size (bytes)
max_message_size = 48000000  # 48MB

# Maximum BSON document size (bytes)
max_bson_size = 16777216  # 16MB

# Maximum batch size for operations
max_batch_size = 100000

# Enable compression
compression = true
compression_algorithms = ["zstd", "snappy", "zlib"]
```

### Cursor Settings

```toml
[mongodb.cursors]
# Default cursor batch size
default_batch_size = 101

# Cursor timeout in seconds
cursor_timeout = 600

# Maximum cursors per connection
max_cursors_per_connection = 1000
```

### Change Streams

```toml
[mongodb.change_streams]
# Enable change streams
enabled = true

# Maximum change stream connections
max_streams = 100

# Full document lookup: "default", "updateLookup", "whenAvailable", "required"
full_document = "updateLookup"

# Resume token expiration (hours)
resume_token_expiration = 24
```

## Connection String Format

### Standard Format

```
mongodb://[username:password@]host[:port][/database][?options]
```

### Connection Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `authSource` | string | admin | Authentication database |
| `authMechanism` | string | SCRAM-SHA-256 | Auth mechanism |
| `replicaSet` | string | - | Replica set name |
| `tls` | boolean | false | Enable TLS |
| `tlsCAFile` | string | - | CA certificate file |
| `tlsCertificateKeyFile` | string | - | Client cert/key file |
| `connectTimeoutMS` | integer | 10000 | Connection timeout |
| `socketTimeoutMS` | integer | 0 | Socket timeout |
| `maxPoolSize` | integer | 100 | Connection pool size |
| `minPoolSize` | integer | 0 | Minimum pool size |
| `maxIdleTimeMS` | integer | 0 | Max idle time |
| `retryWrites` | boolean | true | Retry failed writes |
| `retryReads` | boolean | true | Retry failed reads |
| `w` | string/int | 1 | Write concern |
| `journal` | boolean | false | Journal write concern |
| `readPreference` | string | primary | Read preference |
| `compressors` | string | - | Compression algorithms |

### Connection Examples

```python
# Basic connection
mongodb://localhost:27017/mydb

# With authentication
mongodb://user:password@localhost:27017/mydb?authSource=admin

# With TLS
mongodb://user:password@localhost:27017/?tls=true&tlsCAFile=/path/to/ca.pem

# With connection pool
mongodb://localhost:27017/?maxPoolSize=50&minPoolSize=10

# Replica set
mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=rs0

# Full configuration
mongodb://user:password@host:27017/mydb?authSource=admin&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=true&w=majority
```

## Client Configuration

### Python (PyMongo)

```python
from pymongo import MongoClient

# Using connection string
client = MongoClient(
    "mongodb://localhost:27017/",
    authSource="admin",
    authMechanism="SCRAM-SHA-256",
    maxPoolSize=50,
    minPoolSize=10,
    socketTimeoutMS=30000,
    connectTimeoutMS=10000,
    retryWrites=True
)

# Using MongoClient parameters
client = MongoClient(
    host="localhost",
    port=27017,
    username="user",
    password="password",
    authSource="admin",
    tls=True,
    tlsCAFile="/path/to/ca.pem"
)
```

### Node.js

```javascript
const { MongoClient } = require('mongodb');

const client = new MongoClient('mongodb://localhost:27017/', {
    auth: {
        username: 'user',
        password: 'password'
    },
    authSource: 'admin',
    maxPoolSize: 50,
    minPoolSize: 10,
    socketTimeoutMS: 30000,
    connectTimeoutMS: 10000,
    retryWrites: true,
    retryReads: true
});
```

### Java

```java
import com.mongodb.ConnectionString;
import com.mongodb.MongoClientSettings;
import com.mongodb.client.MongoClients;

String connectionString =
    "mongodb://user:password@localhost:27017/?authSource=admin";

MongoClientSettings settings = MongoClientSettings.builder()
    .applyConnectionString(new ConnectionString(connectionString))
    .applyToConnectionPoolSettings(builder ->
        builder.maxSize(50).minSize(10))
    .applyToSocketSettings(builder ->
        builder.connectTimeout(10, TimeUnit.SECONDS)
               .readTimeout(30, TimeUnit.SECONDS))
    .retryWrites(true)
    .retryReads(true)
    .build();

MongoClient client = MongoClients.create(settings);
```

## Write Concern

### Configuration

```python
from pymongo import WriteConcern

# Acknowledged write
collection.with_options(write_concern=WriteConcern(w=1))

# Majority write
collection.with_options(write_concern=WriteConcern(w="majority"))

# Journaled write
collection.with_options(write_concern=WriteConcern(w=1, j=True))

# Unacknowledged write
collection.with_options(write_concern=WriteConcern(w=0))
```

### Write Concern Options

| Option | Description |
|--------|-------------|
| `w=0` | Unacknowledged, no response |
| `w=1` | Acknowledged by primary |
| `w=majority` | Acknowledged by majority |
| `w=<n>` | Acknowledged by n nodes |
| `j=true` | Written to journal |
| `wtimeout=<ms>` | Write timeout |

## Read Preference

### Configuration

```python
from pymongo import ReadPreference

# Primary (default)
collection.with_options(read_preference=ReadPreference.PRIMARY)

# Primary preferred
collection.with_options(read_preference=ReadPreference.PRIMARY_PREFERRED)

# Secondary
collection.with_options(read_preference=ReadPreference.SECONDARY)

# Secondary preferred
collection.with_options(read_preference=ReadPreference.SECONDARY_PREFERRED)

# Nearest
collection.with_options(read_preference=ReadPreference.NEAREST)
```

## Transaction Settings

```python
from pymongo import WriteConcern, ReadConcern
from pymongo.read_preferences import ReadPreference

with client.start_session() as session:
    session.start_transaction(
        read_concern=ReadConcern("snapshot"),
        write_concern=WriteConcern("majority"),
        read_preference=ReadPreference.PRIMARY
    )

    try:
        # Operations
        session.commit_transaction()
    except Exception:
        session.abort_transaction()
```

## Performance Tuning

### Connection Pool

```toml
[mongodb.pool]
# Maximum connections
max_size = 100

# Minimum connections
min_size = 10

# Maximum idle time (ms)
max_idle_time_ms = 60000

# Wait queue timeout (ms)
wait_queue_timeout_ms = 30000
```

### Query Optimization

```toml
[mongodb.query]
# Enable query cache
query_cache = true

# Query cache size (MB)
query_cache_size = 256

# Slow query threshold (ms)
slow_query_threshold_ms = 100

# Log slow queries
log_slow_queries = true
```

## Monitoring

### Server state

```javascript
// Check server status
db.adminCommand({ serverStatus: 1 })

// Check connection info
db.adminCommand({ connectionStatus: 1 })

// Get current operations
db.adminCommand({ currentOp: 1 })
```

### Metrics

```javascript
// Collection stats
db.collection.stats()

// Database stats
db.stats()

// Index stats
db.collection.aggregate([{ $indexStats: {} }])
```

---

**Related**: [README.md](https://www.heliosdb.com/docs/full/reference/protocols/mongodb/readme/) | [COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/mongodb/compatibility/) | [EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/mongodb/examples/)