autoCompact (original) (raw)

autoCompact

New in version 8.0.

Enables or disables background compaction. When enabled, autoCompact periodically iterates through all available files and continuously runs compaction if there is enough free storage space available.

Before you enable autoCompact, run the dbStats command to see if you have enough available storage space for compaction to proceed. If the amount of available space returned by dbStats is less thanfreeSpaceTargetMB, background compaction has no effect.

The command has the following syntax:


db.runCommand(

   {

     autoCompact: <boolean>,

     freeSpaceTargetMB: <int>, // Optional

     runOnce: <boolean>, // Optional

   }

)

This command is available in deployments hosted in the following environments:

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Note

This command is currently not supported in MongoDB Atlas clusters.

The command can take the following optional fields:

Field	Type	Description
freeSpaceTargetMB	Integer	Optional. Specifies the minimum amount of storage space, in megabytes, that must be recoverable for compaction to proceed.Default: 20
runOnce	boolean	Optional. If runOnce is set to true, background compaction runs only once through every collection on the node.If runOnce is set to false, background compaction runs continuously on all collections in the database. If a collection fails to compact while runOnce is false, MongoDB temporarily skips that collection and continues compacting the remaining collections. MongoDB attempts to compact the failed collection again after approximately one day.

For clusters enforcing authentication, you must authenticate as a user with the compact privilege action on the cluster. The hostManager role provides the required privileges for running autoCompact.

Although the autoCompact command itself doesn't block reads and writes, background compaction applies the same blocking behavior as the compact command.

Additionally, MongoDB returns an error if you call autoCompact while background compaction is active. If you need to restart autoCompact or run it again with different options, you must first stop the current background compaction operation:


db.runCommand( { autoCompact: false } )

Once the current background compaction is disabled, you can restart autoCompactwith the new configuration.

If an oplog exists, MongoDB excludes it from background compaction.

We recommend running autoCompact during periods of low traffic.

Compaction regularly checkpoints the database, which can lead to synchronization overhead. On high-traffic databases, this can potentially delay or prevent operational tasks such as taking backups. To avoid unexpected disruptions, disable compaction before taking a backup.

You can run background compaction on collections and indexes that are stored in a replica set. However, note the following considerations:

The primary node does not replicate the autoCompact command to the secondary nodes.
A secondary node can replicate data while background compaction is running.
Reads and writes are permitted while background compaction is running.

autoCompact only applies to mongod instances. In a sharded environment, run autoCompact on each shard separately.

You cannot run autoCompact against a mongos instance.

compact