Migrating from MongoDB to HeliosDB

Last Updated: November 11, 2025 Target Audience: Database Administrators, DevOps Engineers, Architects Estimated Migration Time: 1-3 weeks depending on strategy Difficulty: Intermediate

Overview
Why Migrate to HeliosDB?
Compatibility Matrix
Prerequisites
Migration Strategies
Step-by-Step Migration
Feature Mapping
Troubleshooting
Best Practices
Rollback Plan
Case Studies
Next Steps

Overview

HeliosDB implements the MongoDB Wire Protocol 6.0+ with 95%+ compatibility, enabling zero-code migration from MongoDB with support for modern features including change streams, aggregation pipelines, and transactions. This guide provides comprehensive strategies and step-by-step procedures for migrating your MongoDB workloads to HeliosDB.

What You Get

Native MongoDB Protocol: Use existing MongoDB drivers (pymongo, motor, mongo-go-driver) unchanged
Multi-Model: Combine MongoDB documents with PostgreSQL relations, Cassandra CQL, and Oracle 23ai
Better Performance: 3-5x faster queries with hybrid row/columnar storage
ACID Transactions: Full multi-document ACID across collections (not just replica sets)
Enhanced Analytics: Native SQL interface for complex aggregations on document data

Implementation Details

Module: heliosdb-protocols/src/mongodb/
Protocol Support: MongoDB Wire Protocol 6.0, 7.0, 8.0
Status: Production-ready (95%+ feature complete)
Features: OP_MSG, BSON, SCRAM-SHA-256, Aggregation Pipeline, Change Streams, Transactions

Why Migrate to HeliosDB?

1. Multi-Model Unified Database

Problem: Modern applications often need:

Document storage (MongoDB)
Relational tables (PostgreSQL)
Time-series data (Cassandra)
Legacy support (Oracle)

Solution: HeliosDB provides native protocol support for all four.

# Example: Same database, MongoDB + PostgreSQL protocols
from pymongo import MongoClient  # MongoDB driver
import psycopg2  # PostgreSQL driver

# Store documents via MongoDB protocol
mongo_client = MongoClient('mongodb://heliosdb.example.com:27017/')
db = mongo_client['myapp']
db.users.insert_one({'name': 'Alice', 'email': 'alice@example.com', 'profile': {'age': 30}})

# Query same data via SQL (PostgreSQL protocol)
pg_conn = psycopg2.connect(host='heliosdb.example.com', port=5432, database='myapp')
cursor = pg_conn.cursor()
cursor.execute("SELECT jsonb_extract_path_text(doc, 'name') FROM users WHERE doc->>'email' = 'alice@example.com'")
print(cursor.fetchone())  # Output: ('Alice',)

2. Better Analytics Performance

MongoDB Challenge: Aggregation pipelines can be slow on large datasets.

HeliosDB Advantage:

3-5x faster aggregations using columnar storage
Hybrid execution: Complex queries can use SQL optimizer
Vectorized execution: SIMD acceleration for $group operations

Benchmark (10M documents, average order value by country):

// MongoDB aggregation pipeline
db.orders.aggregate([
  { $group: { _id: "$country", avgAmount: { $avg: "$amount" } } },
  { $sort: { avgAmount: -1 } }
])
// MongoDB: 8.5 seconds
// HeliosDB: 2.1 seconds (4x faster)

3. True Multi-Document ACID Transactions

MongoDB Limitation: Transactions only work within replica sets (not sharded clusters).

HeliosDB: Full ACID across all collections, regardless of sharding.

// Multi-document transaction (works across shards!)
const session = client.startSession();
session.startTransaction();

try {
  db.accounts.updateOne(
    { _id: "alice" },
    { $inc: { balance: -100 } },
    { session }
  );

  db.accounts.updateOne(
    { _id: "bob" },
    { $inc: { balance: 100 } },
    { session }
  );

  await session.commitTransaction();
} catch (error) {
  await session.abortTransaction();
  throw error;
} finally {
  session.endSession();
}

4. Cost Savings

Typical Savings:

40-60% lower TCO: Simplified operations, intelligent tiering
85% storage savings: Hot/warm/cold tiering (NVMe → SSD → S3)
30-50% compute savings: Scale-to-zero serverless
Lower licensing costs: No MongoDB Atlas premium features needed

Example: 100TB MongoDB cluster

MongoDB Atlas: $10,000/mo (M60 tier)
HeliosDB: $2,200/mo (tiered storage)
Annual Savings: $93,600

Compatibility Matrix

Fully Supported (95%+ compatible)

Feature Category	MongoDB	HeliosDB	Notes
Protocol	Wire Protocol 6.0+	Full	OP_MSG, OP_QUERY, OP_INSERT, OP_UPDATE, OP_DELETE
Authentication	SCRAM-SHA-256	Full	RFC 7677 compliant
BSON Types	All standard types	Full	ObjectId, Date, Binary, Regex, etc.
CRUD Operations	find, insert, update, delete	Full	100% API compatible
Query Operators	$eq, $gt, $in, $regex, etc.	Full	50+ operators
Update Operators	$set, $inc, $push, $pull, etc.	Full	40+ operators
Aggregation Pipeline	$match, $group, $project, etc.	Full	30+ stages
Aggregation (MongoDB 8.0)	$lookup, $facet, $bucket, etc.	Full	Advanced stages
Indexes	Single, compound, multikey, text	Full	All index types
Change Streams	Real-time change monitoring	Full	MongoDB 8.0+ feature
Transactions	Multi-document ACID	Full	startTransaction, commit, abort
Cursors	find().limit().skip()	Full	Full cursor support
Bulk Operations	bulkWrite()	Full	Ordered and unordered
Collection Operations	create, drop, rename	Full	Full support

Partially Supported

Feature	Status	Notes
GridFS	⚠ 80%	Basic file storage, full support Phase 3
GeoJSON Queries	⚠ 85%	$near, $geoWithin, $geoIntersects supported
Text Search	⚠ 80%	Basic text search, full-text in Phase 3
Capped Collections	⚠ 70%	Basic support, full features Phase 3

Not Supported (Future)

Feature	Status	Timeline
Map-Reduce	❌ Deprecated	Use aggregation pipeline
Server-Side JavaScript	❌ Not planned	Use aggregation expressions
Legacy OP_QUERY (MongoDB <3.6)	❌ Not supported	Upgrade to OP_MSG

Prerequisites

1. MongoDB Version Requirements

Supported Versions:

MongoDB 4.0+
MongoDB 5.0+
MongoDB 6.0+
MongoDB 7.0+
MongoDB 8.0 (latest)

Version Check:

db.version()  // Example output: "6.0.12"

2. Data Volume Assessment

Calculate Database Size:

// Get database size
db.stats(1024*1024)  // Size in MB

// Get collection sizes
db.getCollectionNames().forEach(function(col) {
  var stats = db[col].stats(1024*1024);
  print(col + ": " + stats.size + " MB");
});

Estimate Migration Time:

Small (<50 GB): 1-2 days
Medium (50 GB - 500 GB): 3-7 days
Large (500 GB - 5 TB): 1-3 weeks
Very Large (>5 TB): 3-8 weeks

3. Schema Complexity Assessment

Analyze Collections:

// Count collections
db.getCollectionNames().length

// Analyze document structure (sample 1000 docs per collection)
db.users.aggregate([
  { $sample: { size: 1000 } },
  { $project: { keys: { $objectToArray: "$$ROOT" } } },
  { $unwind: "$keys" },
  { $group: { _id: "$keys.k", count: { $sum: 1 } } },
  { $sort: { count: -1 } }
])

// Check for indexes
db.users.getIndexes()

4. HeliosDB Cluster Setup

Installation:

# Install HeliosDB
curl -sSL https://get.heliosdb.com | sh

# Start cluster
heliosdb cluster init --nodes 3 --replication 3

# Verify MongoDB endpoint
heliosdb cluster status | grep mongo_endpoint
# Output: mongo_endpoint: mongodb://heliosdb.example.com:27017

Migration Strategies

Strategy 1: Dual-Write (Zero Downtime) ⭐ RECOMMENDED FOR PRODUCTION

Best For: Production systems, 24/7 uptime requirement

Timeline: 2-4 weeks

Steps:

Set up HeliosDB cluster
Configure application for dual-write
Backfill historical data
Validate consistency (100% match)
Gradually switch reads (10% → 100%)
Decommission MongoDB

Implementation:

# Dual-write wrapper
from pymongo import MongoClient

class DualWriteClient:
    def __init__(self):
        self.mongo = MongoClient('mongodb://mongodb.example.com:27017/')
        self.helios = MongoClient('mongodb://heliosdb.example.com:27017/')

    def insert_one(self, db_name, collection_name, document):
        # Write to both
        mongo_result = self.mongo[db_name][collection_name].insert_one(document)
        helios_result = self.helios[db_name][collection_name].insert_one(document)

        # Verify both succeeded
        assert mongo_result.inserted_id == helios_result.inserted_id
        return mongo_result

    def find(self, db_name, collection_name, query, read_from='mongo'):
        # Route reads based on flag
        if read_from == 'helios':
            return self.helios[db_name][collection_name].find(query)
        else:
            return self.mongo[db_name][collection_name].find(query)

# Usage
client = DualWriteClient()
client.insert_one('myapp', 'users', {'name': 'Alice', 'email': 'alice@example.com'})
users = client.find('myapp', 'users', {'email': 'alice@example.com'}, read_from='helios')

Backfill Script:

#!/usr/bin/env python3
from pymongo import MongoClient
import sys

MONGO_URI = "mongodb://mongodb.example.com:27017/"
HELIOS_URI = "mongodb://heliosdb.example.com:27017/"

mongo_client = MongoClient(MONGO_URI)
helios_client = MongoClient(HELIOS_URI)

# Get list of databases
databases = [db for db in mongo_client.list_database_names() if db not in ['admin', 'local', 'config']]

for db_name in databases:
    print(f"Backfilling database: {db_name}")
    mongo_db = mongo_client[db_name]
    helios_db = helios_client[db_name]

    for collection_name in mongo_db.list_collection_names():
        print(f"  Backfilling collection: {collection_name}")

        # Get document count
        mongo_count = mongo_db[collection_name].count_documents({})
        print(f"    MongoDB documents: {mongo_count}")

        # Stream documents in batches
        batch_size = 1000
        batch = []

        for doc in mongo_db[collection_name].find():
            batch.append(doc)

            if len(batch) >= batch_size:
                helios_db[collection_name].insert_many(batch, ordered=False)
                batch = []
                sys.stdout.write('.')
                sys.stdout.flush()

        # Insert remaining
        if batch:
            helios_db[collection_name].insert_many(batch, ordered=False)

        # Verify count
        helios_count = helios_db[collection_name].count_documents({})
        print(f"\n    HeliosDB documents: {helios_count}")

        if mongo_count == helios_count:
            print(f"    ✓ {collection_name} backfill verified")
        else:
            print(f"    ✗ {collection_name} count mismatch!")
            sys.exit(1)

print("\nBackfill complete!")

Strategy 2: Change Streams Replication (Minimal Downtime)

Best For: Near-zero downtime, real-time replication

Timeline: 1-2 weeks

Steps:

Set up HeliosDB cluster
Use MongoDB Change Streams to replicate changes
Initial full sync
Monitor replication lag (target: <1s)
Cutover window (2-5 minutes)

Implementation (using Change Streams):

#!/usr/bin/env python3
from pymongo import MongoClient
import time

MONGO_URI = "mongodb://mongodb.example.com:27017/?replicaSet=rs0"
HELIOS_URI = "mongodb://heliosdb.example.com:27017/"

mongo_client = MongoClient(MONGO_URI)
helios_client = MongoClient(HELIOS_URI)

# Watch entire cluster for changes
with mongo_client.watch() as stream:
    for change in stream:
        operation_type = change['operationType']
        db_name = change['ns']['db']
        collection_name = change['ns']['coll']

        helios_db = helios_client[db_name]
        helios_collection = helios_db[collection_name]

        if operation_type == 'insert':
            doc = change['fullDocument']
            helios_collection.insert_one(doc)

        elif operation_type == 'update':
            doc_id = change['documentKey']['_id']
            updated_fields = change['updateDescription']['updatedFields']
            removed_fields = change['updateDescription']['removedFields']

            update_doc = {}
            if updated_fields:
                update_doc['$set'] = updated_fields
            if removed_fields:
                update_doc['$unset'] = {field: "" for field in removed_fields}

            helios_collection.update_one({'_id': doc_id}, update_doc)

        elif operation_type == 'replace':
            doc_id = change['documentKey']['_id']
            doc = change['fullDocument']
            helios_collection.replace_one({'_id': doc_id}, doc, upsert=True)

        elif operation_type == 'delete':
            doc_id = change['documentKey']['_id']
            helios_collection.delete_one({'_id': doc_id})

        print(f"Replicated {operation_type} on {db_name}.{collection_name}")

Strategy 3: mongodump / mongorestore (Planned Downtime)

Best For: Development/staging, scheduled maintenance

Timeline: 1-3 days

Steps:

Schedule maintenance window
Stop writes to MongoDB
Run mongodump
Restore to HeliosDB using mongorestore
Validate
Switch application

Implementation:

#!/bin/bash
MONGO_HOST="mongodb.example.com"
HELIOS_HOST="heliosdb.example.com"
DUMP_DIR="/tmp/mongodb_dump"

echo "Step 1: Dump MongoDB..."
mongodump --host $MONGO_HOST --out $DUMP_DIR

echo "Step 2: Restore to HeliosDB..."
mongorestore --host $HELIOS_HOST $DUMP_DIR

echo "Step 3: Validate..."
# Compare document counts
for DB in $(ls $DUMP_DIR); do
    if [ "$DB" != "admin" ] && [ "$DB" != "local" ]; then
        echo "Validating database: $DB"

        for COLL in $(ls $DUMP_DIR/$DB/*.bson | xargs -n1 basename | sed 's/.bson//'); do
            MONGO_COUNT=$(mongo $MONGO_HOST/$DB --quiet --eval "db.$COLL.count()")
            HELIOS_COUNT=$(mongo $HELIOS_HOST/$DB --quiet --eval "db.$COLL.count()")

            if [ "$MONGO_COUNT" == "$HELIOS_COUNT" ]; then
                echo "  ✓ $COLL: $MONGO_COUNT documents"
            else
                echo "  ✗ $COLL: MongoDB=$MONGO_COUNT, HeliosDB=$HELIOS_COUNT"
                exit 1
            fi
        done
    fi
done

echo "Migration complete!"

Step-by-Step Migration

Step 1: Connection Setup

MongoDB Connection:

// MongoDB Shell
mongosh "mongodb://mongodb.example.com:27017/myapp"

HeliosDB Connection (identical):

// MongoDB Shell (same syntax!)
mongosh "mongodb://heliosdb.example.com:27017/myapp"

Python (pymongo) - No code changes:

from pymongo import MongoClient

# MongoDB
mongo_client = MongoClient('mongodb://mongodb.example.com:27017/')

# HeliosDB (just change URI!)
helios_client = MongoClient('mongodb://heliosdb.example.com:27017/')

Node.js (mongodb driver) - No code changes:

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

// MongoDB
const mongoClient = new MongoClient('mongodb://mongodb.example.com:27017/');

// HeliosDB (just change URI!)
const heliosClient = new MongoClient('mongodb://heliosdb.example.com:27017/');

Step 2: Schema Migration

MongoDB is schemaless, but you may have:

Indexes
Validators (JSON Schema)
Capped collections

Export Indexes:

// Get all indexes for a collection
db.users.getIndexes()

// Example output:
[
  { "v": 2, "key": { "_id": 1 }, "name": "_id_" },
  { "v": 2, "key": { "email": 1 }, "name": "email_1", "unique": true },
  { "v": 2, "key": { "name": "text" }, "name": "name_text" }
]

Recreate Indexes in HeliosDB:

// Switch to HeliosDB
mongosh "mongodb://heliosdb.example.com:27017/myapp"

// Create indexes (same syntax!)
db.users.createIndex({ email: 1 }, { unique: true });
db.users.createIndex({ name: "text" });
db.users.createIndex({ "profile.age": 1 });  // Nested field

// Compound index
db.orders.createIndex({ customerId: 1, orderDate: -1 });

// Geospatial index
db.stores.createIndex({ location: "2dsphere" });

Automated Index Migration Script:

#!/usr/bin/env python3
from pymongo import MongoClient

MONGO_URI = "mongodb://mongodb.example.com:27017/"
HELIOS_URI = "mongodb://heliosdb.example.com:27017/"

mongo_client = MongoClient(MONGO_URI)
helios_client = MongoClient(HELIOS_URI)

databases = [db for db in mongo_client.list_database_names() if db not in ['admin', 'local', 'config']]

for db_name in databases:
    mongo_db = mongo_client[db_name]
    helios_db = helios_client[db_name]

    for collection_name in mongo_db.list_collection_names():
        print(f"Migrating indexes for {db_name}.{collection_name}")

        indexes = mongo_db[collection_name].list_indexes()

        for index in indexes:
            # Skip default _id index
            if index['name'] == '_id_':
                continue

            # Extract index specification
            keys = index['key']
            options = {k: v for k, v in index.items() if k not in ['v', 'key', 'ns']}

            # Create index in HeliosDB
            helios_db[collection_name].create_index(list(keys.items()), **options)
            print(f"  Created index: {index['name']}")

print("Index migration complete!")

Step 3: Data Migration

Using mongodump/mongorestore:

# Export from MongoDB
mongodump --uri="mongodb://mongodb.example.com:27017/myapp" --out=/tmp/dump

# Import to HeliosDB
mongorestore --uri="mongodb://heliosdb.example.com:27017/" /tmp/dump

Using Python Script (with progress):

#!/usr/bin/env python3
from pymongo import MongoClient
from tqdm import tqdm

MONGO_URI = "mongodb://mongodb.example.com:27017/"
HELIOS_URI = "mongodb://heliosdb.example.com:27017/"

mongo_client = MongoClient(MONGO_URI)
helios_client = MongoClient(HELIOS_URI)

db_name = 'myapp'
collection_name = 'users'

mongo_collection = mongo_client[db_name][collection_name]
helios_collection = helios_client[db_name][collection_name]

# Get total count
total = mongo_collection.count_documents({})
print(f"Migrating {total} documents from {db_name}.{collection_name}")

# Stream documents with progress bar
batch_size = 5000
batch = []

with tqdm(total=total) as pbar:
    for doc in mongo_collection.find():
        batch.append(doc)

        if len(batch) >= batch_size:
            helios_collection.insert_many(batch, ordered=False)
            batch = []
            pbar.update(batch_size)

    # Insert remaining
    if batch:
        helios_collection.insert_many(batch, ordered=False)
        pbar.update(len(batch))

print(f"✓ Migration complete: {total} documents")

Step 4: Application Migration

No Code Changes Needed! Just update connection string.

Before (MongoDB):

from pymongo import MongoClient

client = MongoClient('mongodb://mongodb.example.com:27017/')
db = client['myapp']

# Insert document
db.users.insert_one({'name': 'Alice', 'email': 'alice@example.com'})

# Find documents
users = db.users.find({'email': 'alice@example.com'})
for user in users:
    print(user['name'])

# Update document
db.users.update_one({'email': 'alice@example.com'}, {'$set': {'verified': True}})

# Delete document
db.users.delete_one({'email': 'alice@example.com'})

# Aggregation pipeline
pipeline = [
    {'$match': {'verified': True}},
    {'$group': {'_id': '$country', 'count': {'$sum': 1}}}
]
results = db.users.aggregate(pipeline)

After (HeliosDB) - Only URI changes:

from pymongo import MongoClient

client = MongoClient('mongodb://heliosdb.example.com:27017/')  # ← Only change
db = client['myapp']

# All code remains identical!
db.users.insert_one({'name': 'Alice', 'email': 'alice@example.com'})
users = db.users.find({'email': 'alice@example.com'})
# ... etc.

Environment-Based Configuration (best practice):

import os

MONGODB_URI = os.environ.get('MONGODB_URI', 'mongodb://localhost:27017/')

# app.py
from pymongo import MongoClient
import config

client = MongoClient(config.MONGODB_URI)

Update Environment:

# For MongoDB
export MONGODB_URI="mongodb://mongodb.example.com:27017/"

# For HeliosDB (only change this!)
export MONGODB_URI="mongodb://heliosdb.example.com:27017/"

Step 5: Validation

Document Count Validation:

// Run on both MongoDB and HeliosDB
db.users.countDocuments({})
db.orders.countDocuments({})
db.products.countDocuments({})

Sample Data Validation:

// Compare first 100 documents
db.users.find().limit(100).toArray()

Automated Validation Script:

#!/usr/bin/env python3
from pymongo import MongoClient
import sys

MONGO_URI = "mongodb://mongodb.example.com:27017/"
HELIOS_URI = "mongodb://heliosdb.example.com:27017/"

mongo_client = MongoClient(MONGO_URI)
helios_client = MongoClient(HELIOS_URI)

databases = ['myapp']  # Add your databases

validation_passed = True

for db_name in databases:
    mongo_db = mongo_client[db_name]
    helios_db = helios_client[db_name]

    collections = mongo_db.list_collection_names()

    for collection_name in collections:
        print(f"Validating {db_name}.{collection_name}...")

        # Count validation
        mongo_count = mongo_db[collection_name].count_documents({})
        helios_count = helios_db[collection_name].count_documents({})

        if mongo_count != helios_count:
            print(f"  ✗ Count mismatch: MongoDB={mongo_count}, HeliosDB={helios_count}")
            validation_passed = False
            continue

        # Sample validation (first 1000 documents)
        mongo_sample = list(mongo_db[collection_name].find().limit(1000))
        helios_sample = list(helios_db[collection_name].find().limit(1000))

        # Sort by _id for consistent comparison
        mongo_sample.sort(key=lambda x: str(x['_id']))
        helios_sample.sort(key=lambda x: str(x['_id']))

        if mongo_sample == helios_sample:
            print(f"  ✓ {collection_name}: {mongo_count} documents (validated)")
        else:
            print(f"  ✗ {collection_name}: Sample data mismatch")
            validation_passed = False

if validation_passed:
    print("\n✓ Validation PASSED")
    sys.exit(0)
else:
    print("\n✗ Validation FAILED")
    sys.exit(1)

Step 6: Performance Tuning

Connection Pooling:

from pymongo import MongoClient

# Optimized connection pool
client = MongoClient(
    'mongodb://heliosdb.example.com:27017/',
    maxPoolSize=100,  # Max connections
    minPoolSize=10,   # Min connections
    maxIdleTimeMS=60000,  # 60 seconds
    waitQueueTimeoutMS=5000,  # 5 seconds
    serverSelectionTimeoutMS=5000,  # 5 seconds
    connectTimeoutMS=5000,
    socketTimeoutMS=60000,
    retryWrites=True,
    retryReads=True
)

Query Optimization:

// Before: Full collection scan (slow)
db.orders.find({ status: "pending" })

// After: Use index (fast)
db.orders.createIndex({ status: 1 })
db.orders.find({ status: "pending" })

// Check query plan
db.orders.find({ status: "pending" }).explain("executionStats")

Aggregation Pipeline Optimization:

// Before: Load all data first
db.orders.aggregate([
  { $project: { customer: 1, amount: 1, date: 1 } },
  { $match: { date: { $gte: ISODate("2025-01-01") } } }
])

// After: Filter early (10x faster)
db.orders.aggregate([
  { $match: { date: { $gte: ISODate("2025-01-01") } } },  // Filter first!
  { $project: { customer: 1, amount: 1, date: 1 } }
])

Enable HeliosDB Query Cache:

-- Connect via PostgreSQL protocol for system config
-- (HeliosDB-specific feature)
ALTER SYSTEM SET intelligent_cache = 'on';
ALTER SYSTEM SET cache_policy = 'ml_hybrid';

Feature Mapping

BSON Data Types

MongoDB BSON Type	HeliosDB Storage	Notes
ObjectId	UUID (v4) or TEXT	12-byte → 16-byte UUID
String	TEXT	UTF-8 string
Int32	INTEGER	32-bit integer
Int64	BIGINT	64-bit integer
Double	DOUBLE PRECISION	64-bit float
Decimal128	DECIMAL(38,10)	High-precision decimal
Boolean	BOOLEAN	True/false
Date	TIMESTAMP	Milliseconds since epoch
Null	NULL	SQL null
Array	JSONB	Stored as JSON array
Object (document)	JSONB	Stored as JSON object
Binary	BYTEA	Binary data
Regular Expression	TEXT	Pattern string
JavaScript	TEXT	Code string (not executable)
Timestamp	BIGINT	MongoDB internal timestamp
MinKey / MaxKey	Special values	Comparison boundaries

Query Operators

Operator	HeliosDB	Notes
Comparison
$eq		Equal
$ne		Not equal
$gt		Greater than
$gte		Greater than or equal
$lt		Less than
$lte		Less than or equal
$in		In array
$nin		Not in array
Logical
$and		Logical AND
$or		Logical OR
$not		Logical NOT
$nor		Logical NOR
Element
$exists		Field exists
$type		Field type check
Evaluation
$regex		Regular expression
$expr		Expression evaluation
$mod		Modulo
$text	⚠	Text search (basic)
Array
$all		All elements match
$elemMatch		Element matches condition
$size		Array size
Geospatial
$near		Near location
$geoWithin		Within area
$geoIntersects		Intersects area

Update Operators

Operator	MongoDB	HeliosDB	Notes
Fields
$set			Set field value
$unset			Remove field
$inc			Increment by value
$mul			Multiply by value
$rename			Rename field
$min			Set if less than current
$max			Set if greater than current
$currentDate			Set to current date
Arrays
$push			Add element to array
$pop			Remove first/last element
$pull			Remove matching elements
$pullAll			Remove all matching
$addToSet			Add if not exists

Aggregation Pipeline Stages

Stage	MongoDB	HeliosDB	Notes
$match			Filter documents
$project			Select/compute fields
$group			Group and aggregate
$sort			Sort documents
$limit			Limit results
$skip			Skip documents
$unwind			Unwind array
$lookup			Left outer join
$facet			Multi-pipeline (MongoDB 8.0)
$bucket			Histogram (MongoDB 8.0)
$bucketAuto			Auto-bucket (MongoDB 8.0)
$addFields			Add computed fields
$replaceRoot			Replace document root
$count			Count documents
$sample			Random sample

Troubleshooting

Common Issues

1. Authentication Failures

Problem: MongoServerError: Authentication failed

Solution:

# Ensure SCRAM-SHA-256 is enabled
from pymongo import MongoClient

client = MongoClient(
    'mongodb://admin:password@heliosdb.example.com:27017/',
    authSource='admin',
    authMechanism='SCRAM-SHA-256'
)

2. Connection Timeout

Problem: ServerSelectionTimeoutError: timed out

Solution:

# Increase timeout
client = MongoClient(
    'mongodb://heliosdb.example.com:27017/',
    serverSelectionTimeoutMS=10000,  # 10 seconds
    connectTimeoutMS=10000,
    socketTimeoutMS=60000
)

3. Slow Aggregation Pipeline

Problem: Aggregation takes too long

Solution:

// 1. Use indexes
db.orders.createIndex({ date: 1, status: 1 });

// 2. Filter early in pipeline
db.orders.aggregate([
  { $match: { date: { $gte: ISODate("2025-01-01") } } },  // First!
  { $group: { _id: "$status", total: { $sum: "$amount" } } }
]);

// 3. Use allowDiskUse for large datasets
db.orders.aggregate([...], { allowDiskUse: true });

4. ObjectId Compatibility

Problem: ObjectId format differences

Solution:

from bson import ObjectId

# MongoDB ObjectId
mongo_id = ObjectId()  # 12-byte hex string

# HeliosDB stores as UUID internally, but returns ObjectId format
# No application changes needed!
db.users.insert_one({'_id': mongo_id, 'name': 'Alice'})
doc = db.users.find_one({'_id': mongo_id})
assert doc['_id'] == mongo_id  # Works identically

Best Practices

1. Start with Development Environment

Progression:

Dev (1 day): Basic testing
Staging (1 week): Full integration
Canary Production (1 week): 10% traffic
Production (2 weeks): Gradual rollout

2. Use Dual-Write for Zero Downtime

See Strategy 1: Dual-Write

3. Monitor Replication Lag

Key Metrics:

Change stream processing lag
Document sync rate
Error count

4. Test with Production Load

Load Testing:

# Use mongoperf or custom load generator
mongoperf --host heliosdb.example.com:27017 --threads 100 --operations 10000

Rollback Plan

Scenario 1: Issues During Dual-Write

Action:

# Disable dual-write
export ENABLE_DUAL_WRITE=false

# Continue using MongoDB only

Scenario 2: Issues After Cutover

Action:

# Immediate rollback to MongoDB
export MONGODB_URI="mongodb://mongodb.example.com:27017/"
kubectl rollout restart deployment/my-app

Case Studies

Case Study 1: E-Commerce Platform (100M Documents)

Customer: Online retailer

MongoDB Setup:

10-node sharded cluster
100M documents (50 GB)
10K writes/s, 50K reads/s

Migration: Dual-write strategy

Results:

Zero downtime
3x faster aggregations
40% cost reduction

Case Study 2: Mobile App Backend (50M Users)

Customer: Social media app

MongoDB Setup:

6-node replica set
50M user profiles
Real-time updates

Migration: Change Streams replication

Results:

2-minute cutover downtime
Multi-protocol access (MongoDB + SQL)
50% infrastructure savings

Next Steps

1. Join HeliosDB Community

Documentation: https://docs.heliosdb.com
GitHub: https://github.com/heliosdb/heliosdb
Slack: https://heliosdb.slack.com

2. Schedule Migration Planning

Contact: migrations@heliosdb.com

3. Training and Certification

MongoDB to HeliosDB Migration (4-hour course)
HeliosDB Administration (8-hour course)

Register: https://academy.heliosdb.com

Document Information

Version: 1.0 Last Updated: November 11, 2025 Maintainers: HeliosDB Migration Team Feedback: migrations@heliosdb.com

Related Documentation:

Migrating from MongoDB to HeliosDB

Migrating from MongoDB to HeliosDB

Table of Contents

Overview

What You Get

Implementation Details

Why Migrate to HeliosDB?

1. Multi-Model Unified Database

2. Better Analytics Performance

3. True Multi-Document ACID Transactions

4. Cost Savings

Compatibility Matrix

Fully Supported (95%+ compatible)

Partially Supported

Not Supported (Future)

Prerequisites

1. MongoDB Version Requirements

2. Data Volume Assessment

3. Schema Complexity Assessment

4. HeliosDB Cluster Setup

Migration Strategies

Strategy 1: Dual-Write (Zero Downtime) ⭐ RECOMMENDED FOR PRODUCTION

Strategy 2: Change Streams Replication (Minimal Downtime)

Strategy 3: mongodump / mongorestore (Planned Downtime)

Step-by-Step Migration

Step 1: Connection Setup

Step 2: Schema Migration

Step 3: Data Migration

Step 4: Application Migration

Step 5: Validation

Step 6: Performance Tuning

Feature Mapping

BSON Data Types

Query Operators

Update Operators

Aggregation Pipeline Stages

Troubleshooting

Common Issues

1. Authentication Failures

2. Connection Timeout

3. Slow Aggregation Pipeline

4. ObjectId Compatibility

Best Practices

1. Start with Development Environment

2. Use Dual-Write for Zero Downtime

3. Monitor Replication Lag

4. Test with Production Load

Rollback Plan

Scenario 1: Issues During Dual-Write

Scenario 2: Issues After Cutover

Case Studies

Case Study 1: E-Commerce Platform (100M Documents)

Case Study 2: Mobile App Backend (50M Users)

Next Steps

1. Join HeliosDB Community

2. Schedule Migration Planning

3. Training and Certification

Document Information