BLOG POSTS

MangoHost Blog / How to Use Transactions in MongoDB

How to Use Transactions in MongoDB

MongoDB’s transaction support brings ACID guarantees to document databases, enabling atomic operations across multiple documents and collections. Understanding how to properly implement transactions is crucial for maintaining data consistency in applications that require strict data integrity. This guide will walk you through MongoDB transactions from basic concepts to advanced implementations, including real-world scenarios and performance considerations.

How MongoDB Transactions Work

MongoDB transactions operate using a multi-version concurrency control (MVCC) system that ensures snapshot isolation. When a transaction begins, MongoDB creates a snapshot of the database state and maintains it throughout the transaction lifecycle. This approach allows multiple transactions to run concurrently without interfering with each other.

Transactions in MongoDB work at the session level and support both single-document and multi-document operations. They’re available in replica sets and sharded clusters but require MongoDB 4.0 or later for replica sets and 4.2 for sharded clusters.

The transaction lifecycle follows these states:

Starting – Transaction begins with startTransaction()
InProgress – Operations are performed within the transaction context
Committed – All operations are applied atomically
Aborted – Transaction is rolled back, no changes are applied

Step-by-Step Implementation Guide

Let’s start with a basic transaction implementation using the MongoDB Node.js driver:

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

async function performTransaction() {
  const client = new MongoClient('mongodb://localhost:27017');
  await client.connect();
  
  const session = client.startSession();
  
  try {
    await session.withTransaction(async () => {
      const db = client.db('ecommerce');
      const ordersCollection = db.collection('orders');
      const inventoryCollection = db.collection('inventory');
      
      // Decrease inventory
      await inventoryCollection.updateOne(
        { productId: 'PROD123' },
        { $inc: { quantity: -1 } },
        { session }
      );
      
      // Create order
      await ordersCollection.insertOne({
        orderId: 'ORDER456',
        productId: 'PROD123',
        quantity: 1,
        status: 'confirmed'
      }, { session });
      
    });
    
    console.log('Transaction completed successfully');
  } catch (error) {
    console.error('Transaction failed:', error);
  } finally {
    await session.endSession();
    await client.close();
  }
}

For Python developers using PyMongo, here’s the equivalent implementation:

from pymongo import MongoClient
from pymongo.errors import ConnectionFailure, OperationFailure

client = MongoClient('mongodb://localhost:27017')
db = client.ecommerce

def update_inventory_and_create_order():
    with client.start_session() as session:
        with session.start_transaction():
            try:
                # Update inventory
                db.inventory.update_one(
                    {'productId': 'PROD123'},
                    {'$inc': {'quantity': -1}},
                    session=session
                )
                
                # Create order
                db.orders.insert_one({
                    'orderId': 'ORDER456',
                    'productId': 'PROD123',
                    'quantity': 1,
                    'status': 'confirmed'
                }, session=session)
                
                session.commit_transaction()
                print("Transaction completed successfully")
                
            except Exception as e:
                session.abort_transaction()
                print(f"Transaction failed: {e}")
                raise

When working with manual transaction control, you have more granular control over the transaction lifecycle:

async function manualTransactionControl() {
  const session = client.startSession();
  
  try {
    session.startTransaction({
      readConcern: { level: 'snapshot' },
      writeConcern: { w: 'majority' }
    });
    
    // Perform operations
    await db.collection('accounts').updateOne(
      { accountId: 'ACC001' },
      { $inc: { balance: -100 } },
      { session }
    );
    
    await db.collection('accounts').updateOne(
      { accountId: 'ACC002' },
      { $inc: { balance: 100 } },
      { session }
    );
    
    // Check business logic constraints
    const senderAccount = await db.collection('accounts').findOne(
      { accountId: 'ACC001' },
      { session }
    );
    
    if (senderAccount.balance < 0) {
      throw new Error('Insufficient funds');
    }
    
    await session.commitTransaction();
    
  } catch (error) {
    await session.abortTransaction();
    throw error;
  } finally {
    await session.endSession();
  }
}

Real-World Examples and Use Cases

E-commerce platforms frequently use transactions for order processing. Here's a comprehensive example that handles inventory management, payment processing, and order fulfillment:

async function processEcommerceOrder(orderData) {
  const session = client.startSession();
  
  try {
    await session.withTransaction(async () => {
      const { productId, quantity, customerId, paymentAmount } = orderData;
      
      // Check and reserve inventory
      const inventoryResult = await db.collection('inventory').findOneAndUpdate(
        { 
          productId: productId,
          availableQuantity: { $gte: quantity }
        },
        { 
          $inc: { 
            availableQuantity: -quantity,
            reservedQuantity: quantity
          }
        },
        { session, returnDocument: 'after' }
      );
      
      if (!inventoryResult.value) {
        throw new Error('Insufficient inventory');
      }
      
      // Process payment
      await db.collection('payments').insertOne({
        customerId: customerId,
        amount: paymentAmount,
        status: 'processed',
        timestamp: new Date()
      }, { session });
      
      // Update customer account
      await db.collection('customers').updateOne(
        { customerId: customerId },
        { 
          $inc: { totalSpent: paymentAmount },
          $push: { 
            orderHistory: {
              orderId: new ObjectId(),
              productId: productId,
              quantity: quantity,
              amount: paymentAmount,
              date: new Date()
            }
          }
        },
        { session }
      );
      
      // Create order record
      const orderResult = await db.collection('orders').insertOne({
        customerId: customerId,
        productId: productId,
        quantity: quantity,
        totalAmount: paymentAmount,
        status: 'confirmed',
        createdAt: new Date()
      }, { session });
      
      return orderResult.insertedId;
    });
  } catch (error) {
    console.error('Order processing failed:', error.message);
    throw error;
  } finally {
    await session.endSession();
  }
}

Financial applications often require complex multi-step transactions. Here's an example of a banking transfer system:

async function bankTransfer(fromAccount, toAccount, amount) {
  const session = client.startSession();
  
  try {
    await session.withTransaction(async () => {
      // Validate sender account
      const sender = await db.collection('accounts').findOne(
        { accountNumber: fromAccount },
        { session }
      );
      
      if (!sender || sender.balance < amount) {
        throw new Error('Insufficient funds or invalid account');
      }
      
      // Validate receiver account
      const receiver = await db.collection('accounts').findOne(
        { accountNumber: toAccount },
        { session }
      );
      
      if (!receiver) {
        throw new Error('Recipient account not found');
      }
      
      // Perform transfer
      await db.collection('accounts').updateOne(
        { accountNumber: fromAccount },
        { 
          $inc: { balance: -amount },
          $push: { 
            transactions: {
              type: 'debit',
              amount: amount,
              to: toAccount,
              timestamp: new Date(),
              transactionId: new ObjectId()
            }
          }
        },
        { session }
      );
      
      await db.collection('accounts').updateOne(
        { accountNumber: toAccount },
        { 
          $inc: { balance: amount },
          $push: { 
            transactions: {
              type: 'credit',
              amount: amount,
              from: fromAccount,
              timestamp: new Date(),
              transactionId: new ObjectId()
            }
          }
        },
        { session }
      );
      
      // Log transaction for audit
      await db.collection('auditLog').insertOne({
        type: 'transfer',
        from: fromAccount,
        to: toAccount,
        amount: amount,
        timestamp: new Date(),
        status: 'completed'
      }, { session });
      
    }, {
      readConcern: { level: 'snapshot' },
      writeConcern: { w: 'majority', j: true },
      maxTimeMS: 30000
    });
    
    return { success: true, message: 'Transfer completed successfully' };
    
  } catch (error) {
    await db.collection('auditLog').insertOne({
      type: 'transfer',
      from: fromAccount,
      to: toAccount,
      amount: amount,
      timestamp: new Date(),
      status: 'failed',
      error: error.message
    });
    
    throw error;
  } finally {
    await session.endSession();
  }
}

Performance Considerations and Comparisons

Transaction performance in MongoDB varies significantly based on several factors. Here's a comparison of different transaction scenarios:

Transaction Type	Average Latency	Throughput (ops/sec)	Resource Usage	Best Use Case
Single Document	1-2ms	10,000-50,000	Low	Simple updates
Multi-Document (same collection)	5-10ms	2,000-5,000	Medium	Batch operations
Multi-Collection	10-25ms	500-2,000	High	Complex workflows
Cross-Shard	50-100ms	100-500	Very High	Distributed operations

MongoDB transactions compared to traditional RDBMS transactions show interesting trade-offs:

Feature	MongoDB	PostgreSQL	MySQL
Isolation Level	Snapshot	Configurable (RC, RR, S)	Configurable (RC, RR, S)
Lock Granularity	Document-level	Row-level	Row/Table-level
Distributed Transactions	Yes (4.2+)	Limited	Limited
Schema Flexibility	High	Medium	Low
Complex Queries	Good	Excellent	Excellent

Best Practices and Common Pitfalls

Effective transaction management requires following established best practices. Keep transactions short and focused to minimize lock contention and resource usage:

// Good: Short, focused transaction
async function efficientTransaction() {
  await session.withTransaction(async () => {
    // Only essential operations
    await collection.updateOne({_id: id}, {$set: data}, {session});
    await logCollection.insertOne({action: 'update', id}, {session});
  });
}

// Avoid: Long-running transaction with external calls
async function inefficientTransaction() {
  await session.withTransaction(async () => {
    // Bad: External API call within transaction
    const externalData = await fetch('https://api.example.com/data');
    
    // Bad: Complex computation
    const result = performHeavyCalculation(data);
    
    // Bad: Multiple unrelated operations
    await collection1.updateMany({}, {$set: result}, {session});
    await collection2.insertMany(largeArray, {session});
  });
}

Implement proper error handling and retry logic for transient errors:

async function robustTransaction(operation, maxRetries = 3) {
  let attempt = 0;
  
  while (attempt < maxRetries) {
    const session = client.startSession();
    
    try {
      await session.withTransaction(async () => {
        await operation(session);
      }, {
        readConcern: { level: 'snapshot' },
        writeConcern: { w: 'majority' },
        maxTimeMS: 30000
      });
      
      return; // Success, exit retry loop
      
    } catch (error) {
      if (error.errorLabels && 
          error.errorLabels.includes('TransientTransactionError')) {
        attempt++;
        console.log(`Retrying transaction, attempt ${attempt}`);
        await new Promise(resolve => setTimeout(resolve, 100 * attempt));
      } else {
        throw error; // Non-transient error, don't retry
      }
    } finally {
      await session.endSession();
    }
  }
  
  throw new Error(`Transaction failed after ${maxRetries} attempts`);
}

Monitor transaction performance and set appropriate timeouts:

// Configure transaction options based on your use case
const transactionOptions = {
  readConcern: { level: 'snapshot' },
  writeConcern: { 
    w: 'majority', 
    j: true,
    wtimeout: 5000 
  },
  maxTimeMS: 30000, // 30 second timeout
  maxCommitTimeMS: 10000 // 10 second commit timeout
};

await session.withTransaction(async () => {
  // Your transaction operations
}, transactionOptions);

Common pitfalls to avoid include:

Not handling TransientTransactionError and UnknownTransactionCommitResult errors
Performing I/O operations or long computations within transactions
Creating transactions with too many operations or large document modifications
Forgetting to pass the session object to all operations within the transaction
Not implementing proper timeout and retry mechanisms
Using transactions for operations that don't require ACID guarantees

For applications running on managed infrastructure, consider hosting your MongoDB instances on reliable platforms. Services like VPS solutions provide the consistent performance needed for transaction-heavy workloads, while dedicated servers offer optimal performance for mission-critical applications requiring high transaction throughput.

Optimize your transaction design by batching related operations and using appropriate read and write concerns. Consider using change streams for reactive programming patterns that can reduce the need for complex transactions in certain scenarios.

For comprehensive documentation on MongoDB transactions, refer to the official MongoDB transactions guide, which provides detailed information on transaction semantics and advanced configuration options.

This article incorporates information and material from various online sources. We acknowledge and appreciate the work of all original authors, publishers, and websites. While every effort has been made to appropriately credit the source material, any unintentional oversight or omission does not constitute a copyright infringement. All trademarks, logos, and images mentioned are the property of their respective owners. If you believe that any content used in this article infringes upon your copyright, please contact us immediately for review and prompt action.

This article is intended for informational and educational purposes only and does not infringe on the rights of the copyright owners. If any copyrighted material has been used without proper credit or in violation of copyright laws, it is unintentional and we will rectify it promptly upon notification. Please note that the republishing, redistribution, or reproduction of part or all of the contents in any form is prohibited without express written permission from the author and website owner. For permissions or further inquiries, please contact us.