MongoDB Protocol Configuration¶

Complete configuration reference for HeliosDB's MongoDB protocol implementation.

Server Configuration¶

Network Settings¶

[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¶

[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¶

[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¶

[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¶

[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¶

[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¶

# 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)¶

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¶

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¶

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¶

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¶

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¶

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¶

[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¶

[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 Status¶

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

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

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

Metrics¶

// Collection stats
db.collection.stats()

// Database stats
db.stats()

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

Related: README.md | COMPATIBILITY.md | EXAMPLES.md

Last Updated: December 2025