Compacting Channel DB
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).
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_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.
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.