---
title: "Migrating from MongoDB to HeliosDB"
---

# Migrating from MongoDB to HeliosDB

:::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. Until
storage-backed MongoDB reads and writes are available, reach migrated data over the
PostgreSQL listener. GridFS and capped collections are not supported; they are
planned.
:::

**Target Audience**: Database Administrators, DevOps Engineers, Architects
**Estimated Migration Time**: 1-3 weeks depending on strategy
**Difficulty**: Intermediate

---

## Table of Contents

1. [Overview](#overview)
2. [Why Migrate to HeliosDB?](#why-migrate-to-heliosdb)
3. [Compatibility Matrix](#compatibility-matrix)
4. [Prerequisites](#prerequisites)
5. [Migration Strategies](#migration-strategies)
6. [Step-by-Step Migration](#step-by-step-migration)
7. [Feature Mapping](#feature-mapping)
8. [Troubleshooting](#troubleshooting)
9. [Best Practices](#best-practices)
10. [Rollback Plan](#rollback-plan)
11. [Case Studies](#case-studies)
12. [Next Steps](#next-steps)

---

## Overview

HeliosDB Full implements the MongoDB wire protocol (OP_MSG) with support for core CRUD commands, aggregation pipelines, indexes, cursors, SCRAM-SHA-256 authentication and transactions. Applications connect by pointing the driver at HeliosDB; test your workload against the [compatibility notes](#compatibility-notes), which include a current limitation on driver writes. This guide provides comprehensive strategies and step-by-step procedures for migrating your MongoDB workloads to HeliosDB.

### What You Get

- **Native MongoDB Protocol**: Connect with standard MongoDB drivers (pymongo, motor, mongo-go-driver) by changing the connection string
- **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

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

```python
# 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; measured on representative fixtures, reproduce on your own hardware):
```javascript
// 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.

```javascript
// 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. Infrastructure Efficiency

- **Intelligent tiering**: Hot/warm/cold storage tiers (NVMe → SSD → S3) move infrequently accessed data to lower-cost storage
- **Scale-to-zero**: Compute can scale down for intermittent workloads
- **Consolidation**: Document, relational and wide-column workloads in one deployment

HeliosDB Full is commercially licensed (source-available under SSPL-1.0); contact [sales@heliosdb.com](mailto:sales@heliosdb.com) for pricing.

---

## Compatibility Matrix

### Supported

| 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, count, distinct | Most | `findAndModify` is not yet supported |
| **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, listCollections | Most | `renameCollection` is not yet supported |

### Partially Supported

| Feature | Result | Notes |
|---------|--------|-------|
| GridFS | Not supported | Planned |
| GeoJSON Queries | Planned | Geospatial functions and indexes are planned |
| Text Search | Partial (80%) | Basic text search |
| Capped Collections | Not supported | Planned |

### Not Supported (Future)

| Feature | Result | Timeline |
|---------|--------|----------|
| Map-Reduce | No (deprecated) | Use aggregation pipeline |
| Server-Side JavaScript | Not planned | Use aggregation expressions |
| Legacy OP_QUERY (MongoDB <3.6) | Not supported | Upgrade to OP_MSG |


### Compatibility notes

- The MongoDB listener is opt-in: start HeliosDB Full with `--enable-mongodb` (port 27017 by default; set `--mongodb-port` or `HELIOSDB_MONGODB_PORT` to change it).
- Authentication uses SCRAM-SHA-256. Add `authMechanism=SCRAM-SHA-256` to the connection string (or the driver options); without it, drivers such as pymongo try SCRAM-SHA-1, which the listener refuses.
- **Current limitation:** drivers that send write commands as OP_MSG document sequences, such as pymongo 4.x, get `Missing or invalid field: documents` (or `updates`, `deletes`) from `insert_one`, `insert_many`, `update_one` and `delete_one`. Reads (`find`, `count_documents`, `aggregate`) return no documents, because reading and writing HeliosDB tables through the MongoDB listener is planned and not in the current release.
- Supported commands include `find`, `insert`, `update`, `delete`, `aggregate`, `count`, `distinct`, `getMore`, `killCursors`, `create`, `drop`, `listDatabases`, `listCollections`, `createIndexes`, `dropIndexes`, the transaction commands, and diagnostics such as `ping`, `hello`, `buildInfo`, `serverStatus`, `dbStats` and `collStats`. Other commands return `CommandNotFound`; for example `findAndModify` (used by helpers such as `find_one_and_update`) and `renameCollection` are not yet supported.
- Run your application's test suite against HeliosDB before cutover.

---

## 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**:
```javascript
db.version()  // Example output: "6.0.12"
```

---

### 2. Data Volume Assessment

**Calculate Database Size**:
```javascript
// 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**:
```javascript
// 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**:
```bash
# Install HeliosDB Full from the packages provided during onboarding
# (contact sales@heliosdb.com for access)

# 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**:
1. Set up HeliosDB cluster
2. Configure application for dual-write
3. Backfill historical data
4. Validate consistency (100% match)
5. Gradually switch reads (10% → 100%)
6. Decommission MongoDB

**Implementation**:
```python
# 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**:
```python
#!/usr/bin/env python3
# backfill_mongodb.py

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**:
1. Set up HeliosDB cluster
2. Use MongoDB Change Streams to replicate changes
3. Initial full sync
4. Monitor replication lag (target: <1s)
5. Cutover window (2-5 minutes)

**Implementation** (using Change Streams):
```python
#!/usr/bin/env python3
# replicate_mongodb.py

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**:
1. Schedule maintenance window
2. Stop writes to MongoDB
3. Run mongodump
4. Restore to HeliosDB using mongorestore
5. Validate
6. Switch application

**Implementation**:
```bash
#!/bin/bash
# migrate_mongodump.sh

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**:
```javascript
// MongoDB Shell
mongosh "mongodb://mongodb.example.com:27017/myapp"
```

**HeliosDB Connection** (identical):
```javascript
// MongoDB Shell (same syntax!)
mongosh "mongodb://heliosdb.example.com:27017/myapp"
```

**Python (pymongo)** - change the connection URI:
```python
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)** - change the connection URI:
```javascript
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**:
```javascript
// 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**:
```javascript
// 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**:
```python
#!/usr/bin/env python3
# migrate_indexes.py

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**:
```bash
# 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):
```python
#!/usr/bin/env python3
# migrate_data.py

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

**Start with the connection string.** Point the URI at HeliosDB (with `authMechanism=SCRAM-SHA-256`), run your test suite and check the [compatibility notes](#compatibility-notes) for the commands your code relies on.

**Before (MongoDB)**:
```python
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:
```python
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):
```python
# config.py
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**:
```bash
# 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**:
```javascript
// Run on both MongoDB and HeliosDB
db.users.countDocuments({})
db.orders.countDocuments({})
db.products.countDocuments({})
```

**Sample Data Validation**:
```javascript
// Compare first 100 documents
db.users.find().limit(100).toArray()
```

**Automated Validation Script**:
```python
#!/usr/bin/env python3
# validate_migration.py

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**:
```python
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**:
```javascript
// 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**:
```javascript
// 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**:
```sql
-- 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 | MongoDB | 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 | | Partial | 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**:
```python
# 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**:
```python
# 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**:
```javascript
// 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**:
```python
from bson import ObjectId

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

# HeliosDB stores as UUID internally, but returns ObjectId format
# ObjectId values are returned in ObjectId format
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**:
1. Dev (1 day): Basic testing
2. Staging (1 week): Full integration
3. Canary Production (1 week): 10% traffic
4. Production (2 weeks): Gradual rollout

---

### 2. Use Dual-Write for Zero Downtime

See [Strategy 1: Dual-Write](#strategy-1-dual-write-zero-downtime--recommended-for-production)

---

### 3. Monitor Replication Lag

**Key Metrics**:
- Change stream processing lag
- Document sync rate
- Error count

---

### 4. Test with Production Load

**Load Testing**:
```bash
# 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**:
```python
# Disable dual-write
export ENABLE_DUAL_WRITE=false

# Continue using MongoDB only
```

---

### Scenario 2: Issues After Cutover

**Action**:
```bash
# 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

---

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

---

## Next Steps

### 1. Join HeliosDB Community

- Documentation: https://www.heliosdb.com/docs/full/
- Support: [support@heliosdb.com](mailto:support@heliosdb.com)

---

### 2. Schedule Migration Planning

**Contact**: support@heliosdb.com

---

### 3. Training and Certification

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

**Enquiries**: [sales@heliosdb.com](mailto:sales@heliosdb.com)

---

## Document Information

**Version**: 1.0
**Maintainers**: HeliosDB Migration Team
**Feedback**: support@heliosdb.com

**Related Documentation**:
- [Cassandra Migration Guide](https://www.heliosdb.com/docs/full/reference/guides/cassandra_migration/)
- [Oracle Migration Guide](https://www.heliosdb.com/docs/full/reference/guides/oracle_migration/)