|
| 1 | +{-# LANGUAGE DerivingStrategies #-} |
| 2 | +{-# LANGUAGE GeneralisedNewtypeDeriving #-} |
| 3 | + |
| 4 | +{-# OPTIONS_GHC -Wno-orphans #-} |
| 5 | + |
| 6 | +module Cardano.Node.Configuration.LedgerDB ( |
| 7 | + LedgerDbSelectorFlag(..) |
| 8 | + , Gigabytes |
| 9 | + , toBytes |
| 10 | + , defaultLMDBLimits |
| 11 | + , selectorToArgs |
| 12 | + ) where |
| 13 | + |
| 14 | +import Ouroboros.Consensus.Storage.LedgerDB.Impl.Args |
| 15 | +import qualified Ouroboros.Consensus.Storage.LedgerDB.V1.Args as V1 |
| 16 | +import Ouroboros.Consensus.Storage.LedgerDB.V1.BackingStore.Impl.LMDB (LMDBLimits (..)) |
| 17 | +import qualified Ouroboros.Consensus.Storage.LedgerDB.V2.Args as V2 |
| 18 | +import Ouroboros.Consensus.Util.Args |
| 19 | + |
| 20 | +import qualified Data.Aeson.Types as Aeson (FromJSON) |
| 21 | +import Data.SOP.Dict |
| 22 | + |
| 23 | +-- | Choose the LedgerDB Backend |
| 24 | +-- |
| 25 | +-- As of UTxO-HD, the LedgerDB now uses either an in-memory backend or LMDB to |
| 26 | +-- keep track of differences in the UTxO set. |
| 27 | +-- |
| 28 | +-- - 'InMemory': uses more memory than the minimum requirements but is somewhat |
| 29 | +-- faster. |
| 30 | +-- - 'LMDB': uses less memory but is somewhat slower. |
| 31 | +-- |
| 32 | +-- See 'Ouroboros.Consnesus.Storage.LedgerDB.OnDisk.BackingStoreSelector'. |
| 33 | +data LedgerDbSelectorFlag = |
| 34 | + V1LMDB (Maybe Gigabytes) -- ^ A map size can be specified, this is the maximum |
| 35 | + -- disk space the LMDB database can fill. If not |
| 36 | + -- provided, the default of 16GB will be used. |
| 37 | + | V1InMemory |
| 38 | + | V2InMemory |
| 39 | + deriving (Eq, Show) |
| 40 | + |
| 41 | +-- | A number of gigabytes. |
| 42 | +newtype Gigabytes = Gigabytes Int |
| 43 | + deriving stock (Eq, Show) |
| 44 | + deriving newtype (Read, Aeson.FromJSON) |
| 45 | + |
| 46 | +-- | Convert a number of Gigabytes to the equivalent number of bytes. |
| 47 | +toBytes :: Gigabytes -> Int |
| 48 | +toBytes (Gigabytes x) = x * 1024 * 1024 * 1024 |
| 49 | + |
| 50 | +-- | Recommended settings for the LMDB backing store. |
| 51 | +-- |
| 52 | +-- === @'lmdbMapSize'@ |
| 53 | +-- The default @'LMDBLimits'@ uses an @'lmdbMapSize'@ of @1024 * 1024 * 1024 * 16@ |
| 54 | +-- bytes, or 16 Gigabytes. @'lmdbMapSize'@ sets the size of the memory map |
| 55 | +-- that is used internally by the LMDB backing store, and is also the |
| 56 | +-- maximum size of the on-disk database. 16 GB should be sufficient for the |
| 57 | +-- medium term, i.e., it is sufficient until a more performant alternative to |
| 58 | +-- the LMDB backing store is implemented, which will probably replace the LMDB |
| 59 | +-- backing store altogether. |
| 60 | +-- |
| 61 | +-- Note(jdral): It is recommended not to set the @'lmdbMapSize'@ to a value |
| 62 | +-- that is much smaller than 16 GB through manual configuration: the node will |
| 63 | +-- die with a fatal error as soon as the database size exceeds the |
| 64 | +-- @'lmdbMapSize'@. If this fatal error were to occur, we would expect that |
| 65 | +-- the node can continue normal operation if it is restarted with a higher |
| 66 | +-- @'lmdbMapSize'@ configured. Nonetheless, this situation should be avoided. |
| 67 | +-- |
| 68 | +-- === @'lmdbMaxDatabases'@ |
| 69 | +-- The @'lmdbMaxDatabases'@ is set to 10, which means that the LMDB backing |
| 70 | +-- store will allow up @<= 10@ internal databases. We say /internal/ |
| 71 | +-- databases, since they are not exposed outside the backing store interface, |
| 72 | +-- such that from the outside view there is just one /logical/ database. |
| 73 | +-- Two of these internal databases are reserved for normal operation of the |
| 74 | +-- backing store, while the remaining databases will be used to store ledger |
| 75 | +-- tables. At the moment, there is at most one ledger table that will be |
| 76 | +-- stored in an internal database: the UTxO. Nonetheless, we set |
| 77 | +-- @'lmdbMaxDatabases'@ to @10@ in order to future-proof these limits. |
| 78 | +-- |
| 79 | +-- === @'lmdbMaxReaders'@ |
| 80 | +-- The @'lmdbMaxReaders'@ limit sets the maximum number of threads that can |
| 81 | +-- read from the LMDB database. Currently, there should only be a single reader |
| 82 | +-- active. Again, we set @'lmdbMaxReaders'@ to @16@ in order to future-proof |
| 83 | +-- these limits. |
| 84 | +-- |
| 85 | +-- === References |
| 86 | +-- For more information about LMDB limits, one should inspect: |
| 87 | +-- * The @lmdb-simple@ and @haskell-lmdb@ forked repositories. |
| 88 | +-- * The official LMDB API documentation at |
| 89 | +-- <http://www.lmdb.tech/doc/group__mdb.html>. |
| 90 | +defaultLMDBLimits :: LMDBLimits |
| 91 | +defaultLMDBLimits = LMDBLimits { |
| 92 | + lmdbMapSize = 16 * 1024 * 1024 * 1024 |
| 93 | + , lmdbMaxDatabases = 10 |
| 94 | + , lmdbMaxReaders = 16 |
| 95 | + } |
| 96 | + |
| 97 | +selectorToArgs :: LedgerDbSelectorFlag -> V1.FlushFrequency -> V1.QueryBatchSize -> Complete LedgerDbFlavorArgs IO |
| 98 | +selectorToArgs V1InMemory a b = LedgerDbFlavorArgsV1 $ V1.V1Args a b V1.InMemoryBackingStoreArgs |
| 99 | +selectorToArgs V2InMemory _ _ = LedgerDbFlavorArgsV2 $ V2.V2Args V2.InMemoryHandleArgs |
| 100 | +selectorToArgs (V1LMDB l) a b= |
| 101 | + LedgerDbFlavorArgsV1 |
| 102 | + $ V1.V1Args a b |
| 103 | + $ V1.LMDBBackingStoreArgs (maybe id (\ll lim -> lim { lmdbMapSize = toBytes ll }) l defaultLMDBLimits) Dict |
0 commit comments