mgopurge is tool which help recover Juju deployments affected by transaction related database corruption. It started as a thin wrapper around mgo/txn's PurgeMissing function but has recently grown the ability to fix a number of problems which we've seen in the field.

The specific problems addressed are:

• runaway transactions on documents
• references to transactions in txn-queue fields on documents which don't exist in the txns collection (this is what PurgeMissing does)
• huge txn-queue lists on machine documents referencing already completed transactions (due to a bad interaction between mgo/txn and historic Juju versions)
• build up of large amounts of historic transaction data
• excess disk space used by Juju's MongoDB instances which is never returned to the operating system

Please note that mgopurge must be used with care. Casual use is strongly discouraged. If you are unsure whether mgopurge will help in a given situation or if you're unsure of how to use it, please ask a Juju core developer.

As of today, the mgopurge can now be found at https://github.com/juju/mgopurge.

Releases for mgopurge can be found at https://github.com/juju/mgopurge/releases. This includes binary releases of the tool.

Running the tool

Mode details can be found by running help on mgopurge command itself. Here is the synopsis of most recently added operations:

Pruning

mgopurge -password "...." -yes -stages prune

• This can be run on live system. In fact, we'd recommend running this periodically as cron job. From 2.2, similar functionality will be run every couple of hours by Juju itself.
• In HA setup, this can be run on any node. It is most efficient to run this command on a primary node.

Compacting

mgopurge -password "...." -yes -stages compact

This will give space back to the operation system. However:

• It does lock database and takes time proportional to database size.
• It is best to shut the controllers prior to running this command.
• It requires ​free space equal to the current size of the database + another 2GB.
• In HA setup, you need to run this on each node.

Note that this functionality is compatible with Mongo 2.4 (for Juju 1.25x) and 3.2 (for Juju 2.0x and 2.1x).