Resolving Disk Exhaustion in CouchDB caused by MVCC Revision Bloat

The Problem: Disk Growth Despite Low Document Counts

A common failure state in CouchDB occurs when disk usage spikes rapidly, eventually leading to disk_full errors or severe I/O latency, even when the number of active documents remains stable. This happens because CouchDB uses Multi-Version Concurrency Control (MVCC). Instead of overwriting a document during an update, CouchDB appends a new revision to the end of the database file. The old versions remain on disk until a process called Compaction removes them.

The takeaway: If your .couch files are significantly larger than your actual data set, you are suffering from revision bloat and must trigger a compaction cycle to reclaim space.

Diagnostic Matrix: Identifying the Cause

Symptom	Likely Cause	Diagnostic Indicator
Rapid disk growth during high update volume	MVCC Revision Accumulation	df -h shows high usage; /_database_info shows high doc_revs
Slow query performance + high disk usage	Fragmented Data Files	Increased seek time; large gap between data size and document count
Disk full despite recent deletions	Pending Compaction	.couch files do not shrink after DELETE requests

Step-by-Step Recovery Process

1. Verify the Bloat Level

Before applying fixes, determine if the disk usage is caused by the document store or the indexes. Run the following request against your CouchDB node (assuming version 3.x+):

# Run from a terminal with curl access to the node
curl -X GET http://admin:password@localhost:5984/your_database/_database_info

Check: Look for the doc_revs value. If the number of revisions is several multiples of the total document count, the database requires compaction.

2. Trigger Manual Compaction

If the disk is nearing capacity, do not wait for the automatic scheduler. Trigger a manual compaction for the specific bloated database. This process creates a new, condensed version of the database file and replaces the old one.

# Run as a user with cluster administrator permissions
curl -X POST http://admin:password@localhost:5984/your_database/_compact

Expected Result: An HTTP 201 Created response. This indicates the compaction job has been queued.

Risk: Compaction is I/O intensive. Running this during peak production traffic can increase request latency for other users.

3. Configure Automatic Compaction

To prevent recurrence, enable automatic compaction in the configuration file (typically local.ini). This ensures CouchDB cleans up old revisions in the background.

[compaction]
auto_compact = true

After updating the config, restart the node or update the setting via the /_node/_config endpoint.

Comparison: Manual vs. Automatic Compaction

Feature	Manual (_compact)	Automatic (auto_compact)
Trigger	On-demand API call	Background scheduler
Control	Precise timing by admin	Managed by CouchDB internals
Use Case	Emergency space recovery	Long-term maintenance
Impact	Immediate I/O spike	Distributed I/O load

Verification and Limitations

To verify the fix, run df -h on the host machine to confirm that disk space has been reclaimed. You can also re-run the /_database_info check to see a reduction in the total file size.

Important Limitations:

• Indexes: Compaction only affects the .couch document files. It does not shrink B-tree index files. If indexes are the cause of disk exhaustion, you must delete and recreate the design documents.
• Temporary Space: Compaction requires enough free disk space to hold a temporary copy of the compacted database before the original is deleted. If the disk is 100% full, compaction may fail.

Rollback and Escalation

Rollback: Compaction is a non-destructive operation that preserves the current state of all documents. There is no "rollback" because the data remains consistent. However, if a compaction process is interrupted by a crash, CouchDB typically cleans up the temporary files upon restart.

Escalation Criteria: If disk usage continues to climb despite frequent compaction and auto_compact = true, investigate the following:

• Check for "zombie" revisions caused by failing replication tasks.
• Verify if a specific application logic is creating thousands of revisions per second for a small set of documents.
• Audit the _compact logs to ensure the process is completing without errors.