diff --git a/ouroboros-consensus/src/ouroboros-consensus-lsm/Ouroboros/Consensus/Storage/LedgerDB/V2/LSM.hs b/ouroboros-consensus/src/ouroboros-consensus-lsm/Ouroboros/Consensus/Storage/LedgerDB/V2/LSM.hs index 3dd12867d2..fb32c422bd 100644 --- a/ouroboros-consensus/src/ouroboros-consensus-lsm/Ouroboros/Consensus/Storage/LedgerDB/V2/LSM.hs +++ b/ouroboros-consensus/src/ouroboros-consensus-lsm/Ouroboros/Consensus/Storage/LedgerDB/V2/LSM.hs @@ -322,6 +322,25 @@ implTakeHandleSnapshot t _ snapshotName = do SnapshotManager -------------------------------------------------------------------------------} +-- | Snapshots in LSM trees are split in two parts for now: +-- +-- - The @state@ and @meta@ files in the usual location (@./ledger/@ in +-- the ChainDB). +-- +-- - The ledger tables, which are stored in the LSM-trees session directory, +-- under a @./lsm/snapshots/@ directory. +-- +-- Note that the name of the folder in which the @state@ file is and the name of +-- the snapshot in the LSM-trees directory have to match. This means that if the +-- user adds a suffix to the snapshot renaming the directory +-- @./ledger/@, they will also have to rename the directory +-- @./lsm/snapshots/@. Otherwise the initialization logic will exit with +-- failure saying that the snapshot was not found. +-- +-- There is [an issue open in +-- LSM-trees](https://github.com/IntersectMBO/lsm-tree/issues/272) such that the +-- ledger tables part of the snapshot could also be stored in the +-- @./ledger/@ directory, but it is not implemented yet. snapshotManager :: ( IOLike m , LedgerDbSerialiseConstraints blk diff --git a/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Storage/LedgerDB/Snapshots.hs b/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Storage/LedgerDB/Snapshots.hs index 095dd2130e..1b5826e2f3 100644 --- a/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Storage/LedgerDB/Snapshots.hs +++ b/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Storage/LedgerDB/Snapshots.hs @@ -11,12 +11,34 @@ {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeApplications #-} --- | Common logic and types for LedgerDB Snapshots. +-- | Snapshots -- --- Snapshots are saved copies of Ledger states in the chain which can be used to --- restart the node without having to replay the whole chain. Regardless of the --- actual LedgerDB implementation chosen, the general management of snapshots is --- common to all implementations. +-- Snapshotting a ledger state means saving a copy of the state to disk, so that +-- a later start of a cardano-node can use such a snapshot as a starting point +-- instead of having to replay from Genesis. +-- +-- A snapshot is identified by the slot number of the ledger state it contains +-- and possibly has a suffix in the name. The consensus logic will not delete a +-- snapshot if it has a suffix. This can be used to store important +-- snapshots. The suffix can be manually added to the snapshot by renaming the +-- folder (see the caveats in 'snapshotManager' for the LSM backend). It will +-- also be added automatically by some tools such as db-analyser. +-- +-- In general snapshots will be stored in the @./ledger@ directory inside the +-- ChainDB directory, but each LedgerDB backend is free to store it somewhere +-- else. Management of snapshots is done through the 'SnapshotManager' +-- record (see the 'snapshotManager' functions on each backend). +-- +-- Snapshots cosists of two parts: +-- +-- - the ledger state tables: location and format differs among backends, +-- +-- - the rest of the ledger state: a CBOR serialization of an @ExtLedgerState +-- blk EmptyMK@, stored in the @./state@ file in the snapshot directory. +-- +-- V2 backends will provide means of loading a snapshot via the method +-- 'newHandleFromSnapshot'. V1 backends load the snapshot directly in +-- 'initFromSnapshot'. module Ouroboros.Consensus.Storage.LedgerDB.Snapshots ( -- * Snapshots CRCError (..)