Compaction

Overview

Compaction rewrites the database file, removing outdated document revisions and deleted documents. It is available in builds of CouchDB built from SVN after 2008-04-07, and in official release since version 0.8-incubating.

Compaction is manually triggered per database. Support for queued compaction of multiple databases is planned.

Example

Compaction is triggered by an HTTP post request to the _compact sub-resource of your database. On success, HTTP status 202 is returned.

    # POST http://localhost/my_db/_compact via curl
    curl -X POST http://localhost/my_db/_compact
    #=> {"ok":true}

GET requesting your database base url ( http://localhost/my_db ) gives a hash of statuses that look like this:

    curl http://localhost/my_db
    #=> {"db_name":"my_db","doc_count":0,"doc_del_count":1,"update_seq":3,"compact_running":false,"disk_size":14341}

The compact_running key will be set to true during compaction.

Compaction of write-heavy databases

Note, it is not a good idea to attempt compaction on a database node that is near full capacity for its write load. The problem is the compaction process may never catch up with the writes if they never let up, and eventually it will run out of disk space.

Compaction should be attempted when the write load is less than full capacity. Read load won't affect its ability to complete however. CouchDB works like this to have the least impact possible on clients, the database remains online and fully functional to readers and writers. It is a design limitation that database compaction can't complete when at capacity for write load. It may be reasonable to schedule compactions during off-peak hours.

In a clustered environment the write load can be switched off for any node before compaction and brought back up to date with replication once complete.

In the future, a single CouchDB node can be changed to stop or fail other updates if the write load is too heavy for it to complete in a reasonable time.