Compacting Channel DB

From PlebNet Wiki
Jump to navigation Jump to search

The BOLT db, or channel.db, stores payments sent by your LND node, including failed payments, failed htlcs from payments and payment probes. The database is located under ~/umbrel/lnd/data/graph/mainnet/channel.db> on Umbrel.

The file continuously grows and may eventually exceed the available disk space and/or slow things down. 1GB or 2GB size is reasonable, but your node may begin to slow down when the file reaches 6 - 8Gb.

Compact & prune channel.db periodically. Pruning refers to marking payment records for deletion. Compaction refers to removing the marked records from the database and thus reducing its size.


See configuration settings to enable compaction: enable compaction of channel.db.

Compaction makes a copy of channel.db during lnd restart, removes the marked records, and restores the file. Make sure to have enough disk space to support compaction, or lnd may fail to start.


Pruning can be automated and manual. Automated pruning can be configured via the lnd.conf. Compaction will then delete channel.db pruned records.

Manual pruning is needed in case automated pruning could not sufficiently reduce the size of channel.db. Node operators can do manual pruning in a few different ways: identify and reset channels with the biggest disk footprint; manually remove payments from the channel.db.

Node operators can identify channels with the biggest footprint through lncli listchannels, the num_updates filed will indicate the number of channel state updates a particular channel did. Node operators can also use bos <alias/pubkey> as part of BalanceOfSatoshis tool. Lightning Jet provides way to monitor channel.db and receive warnings via jet monitor (including telegram bot notications). jet list-channels lists top ten channels based on channel state updates.

Once a channel with the biggest footprint is identified, the node operator can re-establish it by closing the channel and creating a new one. Please note that there is a cost associated with closing and creating channels, so node operators should use this option carefully.

In addition, node operators can prune channel.db manually by calling the LND API DeleteAllPayments, with failed_payments_only and failed_htlcs_only set to true. Please note that the flags are supported in lnd13 and up, and are not supported in lnd12. Take extra caution before calling this method, as if called in lnd12 it'll remove all payments, including good ones.

lncli does not currently support the call so you will need to write a script (in say Python or JavaScript) to call this method. Example of a JavaScript code. There is also a hidden bos command bos delete-payments-history which will delete all payments, including successful ones. You can find the details here.

Manual pruning may take time to complete depending on the channel.db size. Make sure to wait until it completes and don't interrupt the process. Once pruning completes verify that the number of payments in the channel.db is zero by running lncli listpayments | jq '.payments' | jq length. Delete ~/umbrel/lnd/data/graph/mainnet/channel.db.last-compacted to trigger compaction on restart. Next restart you node: restart lnd cd ~/umbrel ; docker-compose restart lnd; docker-compose ps

Upcoming lnd release

The next major lnd14 release will introduce new ways to manage the channel.db size. It'll allow more granular deletion of records from the channel.db. BalanceOfSatoshis will automatically prune obsolete channel.db records generated as part of payment probes. In addition, bos clean-failed-payments will take over as a visible command (currently in dry run mode). Note that it'll be safe to use as it only cleans failed payments.