Document versioning: a practical MongoDB & NoSQL guide

Introduction

Audit trails and change history are non-negotiable in production systems—whether you're managing financial transactions, user profiles, or e-commerce inventory. Document versioning: a practical MongoDB & NoSQL guide walks you through the real-world strategies teams use to keep history of changes without sacrificing performance or storage efficiency. We'll explore two primary approaches: maintaining a separate history collection and embedding version data within documents themselves, both of which keep you in control of who changed what and when.

Why Document Versioning Matters

Without versioning, you lose visibility into how data evolved. A customer disputes a charge; your support team has no record of the order history. A colleague accidentally modifies a critical configuration; you can't trace when or why. In regulated industries—fintech, healthcare, e-commerce—audit logs aren't optional.

MongoDB's flexible schema makes versioning straightforward, but the approach matters. Store changes poorly and you'll find yourself querying a tangled mess. Store them well and you unlock compliance, debugging, and even time-travel analytics.

Approach 1: Separate History Collection

The cleanest pattern for high-volume data is a dedicated history collection. Every time the primary document changes, you write a complete or partial snapshot to a separate collection. This keeps your active data lean and your audit trail organized.

Here's the structure:

// Primary document
db.users.insertOne({
  _id: ObjectId("507f1f77bcf86cd799439011"),
  email: "alice@example.com",
  plan: "pro",
  updatedAt: ISODate("2025-01-15T10:00:00Z"),
  version: 3
});

// History collection
db.users_history.insertMany([
  {
    _id: ObjectId("507f1f77bcf86cd799439012"),
    documentId: ObjectId("507f1f77bcf86cd799439011"),
    version: 1,
    data: {
      email: "alice@example.com",
      plan: "free"
    },
    changedBy: "alice@example.com",
    changedAt: ISODate("2025-01-01T08:00:00Z"),
    changeType: "create"
  },
  {
    _id: ObjectId("507f1f77bcf86cd799439013"),
    documentId: ObjectId("507f1f77bcf86cd799439011"),
    version: 2,
    data: {
      email: "alice@example.com",
      plan: "pro"
    },
    changedBy: "admin@company.com",
    changedAt: ISODate("2025-01-10T14:30:00Z"),
    changeType: "update",
    diff: {
      plan: { old: "free", new: "pro" }
    }
  }
]);

When you update the primary document, wrap the operation in a transaction and insert a history record:

async function updateUserWithHistory(userId, updates, userId, changeReason) {
  const session = db.getMongo().startSession();
  session.startTransaction();

  try {
    // Fetch current state before update
    const currentDoc = db.users.findOne({ _id: userId });

    // Update primary document
    db.users.updateOne(
      { _id: userId },
      {
        $set: {
          ...updates,
          updatedAt: new Date(),
          version: currentDoc.version + 1
        }
      },
      { session }
    );

    // Record in history
    db.users_history.insertOne({
      documentId: userId,
      version: currentDoc.version + 1,
      data: { ...currentDoc, ...updates },
      changedBy: changeReason.userId,
      changedAt: new Date(),
      changeType: "update",
      diff: {
        // Compute only the fields that changed
        ...Object.keys(updates).reduce((acc, key) => {
          if (currentDoc[key] !== updates[key]) {
            acc[key] = { old: currentDoc[key], new: updates[key] };
          }
          return acc;
        }, {})
      }
    }, { session });

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

Querying history is straightforward:

// Get all changes for a user, newest first
db.users_history
  .find({ documentId: ObjectId("507f1f77bcf86cd799439011") })
  .sort({ version: -1 })
  .toArray();

// Find changes by a specific person
db.users_history
  .find({
    documentId: ObjectId("507f1f77bcf86cd799439011"),
    changedBy: "admin@company.com"
  })
  .toArray();

// Restore to a previous version
const targetVersion = db.users_history.findOne({
  documentId: ObjectId("507f1f77bcf86cd799439011"),
  version: 2
});

db.users.updateOne(
  { _id: ObjectId("507f1f77bcf86cd799439011") },
  { $set: targetVersion.data }
);

Pros: Clean separation; easy to query history without touching active data; scales well; works with time-series indexes.

Cons: Requires application-side transaction logic; two writes per change; history collection can grow large over time.

Approach 2: Embedded Version Array with Bounds

For smaller documents or lower-frequency changes, embed history directly as a bounded array. MongoDB's $push operator with a size limit keeps memory predictable.

db.settings.updateOne(
  { _id: "company_config" },
  {
    $push: {
      changelog: {
        $each: [
          {
            timestamp: ISODate("2025-01-15T10:00:00Z"),
            changedBy: "alice@example.com",
            field: "apiRateLimit",
            oldValue: 1000,
            newValue: 5000,
            reason: "increased for partner integration"
          }
        ],
        $slice: -50  // Keep only last 50 changes
      }
    },
    $set: {
      apiRateLimit: 5000,
      updatedAt: new Date()
    }
  }
);

// Retrieve full history
db.settings.findOne({ _id: "company_config" }, { changelog: 1 });

// Query a specific change
db.settings.findOne(
  { _id: "company_config", "changelog.changedBy": "alice@example.com" },
  { "changelog.$": 1 }
);

This approach works best when you have a natural size bound (like "keep the last 50 changes") and don't need unlimited historical access. Settings, feature flags, and configuration documents are ideal candidates.

Pros: Single write; self-contained document; no joins; faster queries for recent history.

Cons: Limited historical depth; array bloat if unbounded; not ideal for audit compliance requiring immutable records; harder to index specific historical fields.

Include Metadata: Who and When

Both approaches require the same metadata discipline. Never skip changedBy and changedAt. In production, add context:

const historyEntry = {
  documentId: userId,
  version: newVersion,
  data: updatedData,
  changedBy: currentUser.id,  // User ObjectId or email
  changedByName: currentUser.name,  // For readability in audit reports
  changedAt: new Date(),
  changeType: "update",  // "create", "update", "delete"
  source: "api",  // Or "admin-panel", "batch-job", etc.
  ipAddress: requestIp,  // For security audits
  userAgent: req.get("user-agent"),
  reason: changeReason,  // Why was this changed?
  diff: computedDiff,
  environment: process.env.NODE_ENV
};

This metadata transforms a history log into a compliance audit trail. When support asks "who changed this customer's billing address?", you have the answer in seconds.

Use Change Streams to Capture Versions Automatically

MongoDB Change Streams let you react to database changes in real time, enabling automatic versioning without embedding logic in every update function.

const changeStream = db.users.watch([
  {
    $match: {
      operationType: { $in: ["insert", "update", "replace"] }
    }
  }
]);

changeStream.on("change", async (change) => {
  const { operationType, fullDocument, documentKey, updateDescription } = change;

  // Extract metadata from change event
  const historyEntry = {
    documentId: documentKey._id,
    changeType: operationType,
    timestamp: new Date(),
    changeStream: {
      operationType,
      updateDescription,
      fullDocumentAfterChange: fullDocument
    }
  };

  // Write to history
  await db.users_history.insertOne(historyEntry);
});

Change Streams are particularly powerful in microservices architectures. A separate "history service" watches the main collection and writes to its own storage, decoupling versioning logic from business logic.

However, Change Streams have limitations: they don't capture why a change happened or who initiated it (unless you store that in the document itself). For compliance-critical systems, application-level versioning with explicit metadata is more reliable.

Common Mistakes

• No metadata: A history entry without changedBy or changedAt is useless. Always include context.
• Mixing approaches: Don't embed small histories in documents and maintain a separate collection. Pick one and own it.
• Unbounded embedded arrays: If you embed version history, always use $slice to cap size. Runaway arrays kill performance.
• Skipping the diff: Storing only the new state forces you to reconstruct what changed. Store the diff: { field: { old: ..., new: ... } }.
• Ignoring transactions: If you're updating the primary and writing history, use multi-document transactions. Otherwise a crash leaves you in an inconsistent state.
• Over-indexing history: Index by documentId, changedAt, and changedBy, but resist the urge to index every field. History collections are write-heavy and read-cold.

Key Takeaways

• Use a separate history collection for audit compliance and high-volume scenarios; use embedded bounded arrays for lightweight local history.
• Always record changedBy, changedAt, and preferably reason and source to transform logs into audit trails.
• Store the diff, not just the new state, so you can quickly see what actually changed without comparing full snapshots.
• Wrap primary updates and history writes in transactions to avoid inconsistent state.
• Consider Change Streams for decoupled versioning in microservices, but fall back to application-level logic for compliance-critical metadata.
• Cap embedded version arrays with $slice to prevent unbounded growth.