What is database compaction in CouchDB and when should you run it?

Database compaction rewrites a CouchDB database file from scratch, retaining only the current (winning) revision of each document and discarding all stale revisions and orphaned B-tree nodes. Because CouchDB uses an append-only storage engine, every update grows the file. A database with millions of updates can be orders of magnitude larger than the size of its live data. Compaction reclaims that space.

When to run compaction:

• After a bulk data migration or large import that produced deep revision chains.
• When disk usage grows significantly faster than the document count (high update churn).
• On a regular nightly schedule in write-heavy production systems.
• CouchDB 2.x+ supports automatic compaction triggers via smoosh (the built-in compaction daemon) which fires when the ratio of live data to total file size drops below a configurable threshold.

# Manually trigger compaction on a database
curl -X POST http://admin:pass@localhost:5984/mydb/_compact
# {"ok":true}

# Compact view indexes of a specific design document
curl -X POST http://admin:pass@localhost:5984/mydb/_compact/my_ddoc
# {"ok":true}

# Monitor progress
curl http://admin:pass@localhost:5984/_active_tasks
# Shows compaction tasks with "progress" percentage

During compaction the database stays fully online — CouchDB continues serving reads and writes from the old file and atomically switches to the new file when compaction finishes. View compaction is separate from document compaction; each design document's index has its own compaction command.