db-analyser: make it clear that DB validation is not ledger-related

This has caused a lot of confusion in the past.

Author: amesgen

ouroboros-consensus-cardano/README.md

@@ -91,12 +91,12 @@ User should run this if they are dealing with a `cardano` chain.
 
 The user can limit the maximum number of blocks that db-analyser will process.
 
-### Database validation
+### Database validation, via --db-validation
 
 The tool provides two database validation policies:
 
 - `validate-all-blocks`, which will cause the tool to validate all chunks on the
-  immutable and volatile databases.
+  immutable database.
 - `minimum-block-validation`, which will cause the tool to validate only the
   most recent chunk in the immutable database.
 

ouroboros-consensus-cardano/app/DBAnalyser/Parsers.hs

@@ -1,5 +1,6 @@
 {-# LANGUAGE ApplicativeDo #-}
 {-# LANGUAGE CPP           #-}
+{-# LANGUAGE LambdaCase    #-}
 
 module DBAnalyser.Parsers (
     BlockType (..)
@@ -55,16 +56,18 @@ parseSelectDB =
 
 
 parseValidationPolicy :: Parser (Maybe ValidateBlocks)
-parseValidationPolicy = optional $ asum [
-      flag' ValidateAllBlocks $ mconcat [
-          long "validate-all-blocks"
-        , help "Validate all blocks of the Immutable DB"
-        ]
-    , flag' MinimumBlockValidation $ mconcat [
-          long "minimum-block-validation"
-        , help "Validate a minimum part of the Immutable DB"
-        ]
-    ]
+parseValidationPolicy =
+    optional $ option reader $ mconcat [
+        long "db-validation"
+      , help $ "The extent of the ChainDB on-disk files validation. This is "
+            <> "completely unrelated to validation of the ledger rules. "
+            <> "Possible values: validate-all-blocks, minimum-block-validation."
+      ]
+  where
+    reader = maybeReader $ \case
+        "validate-all-blocks"      -> Just ValidateAllBlocks
+        "minimum-block-validation" -> Just MinimumBlockValidation
+        _                          -> Nothing
 
 parseAnalysis :: Parser AnalysisName
 parseAnalysis = asum [

ouroboros-consensus-cardano/app/db-analyser.hs

@@ -4,8 +4,8 @@
 
 -- | Database analysis tool.
 --
--- Usage: db-analyser --db PATH [--analyse-from SLOT_NUMBER]
---                    [--validate-all-blocks | --minimum-block-validation]
+-- Usage: db-analyser --db PATH [--verbose] [--analyse-from SLOT_NUMBER]
+--                    [--db-validation ARG]
 --                    [--show-slot-block-no | --count-tx-outputs |
 --                      --show-block-header-size | --show-block-txs-size |
 --                      --show-ebbs | --store-ledger SLOT_NUMBER | --count-blocks |

ouroboros-consensus-cardano/src/unstable-cardano-tools/Cardano/Tools/DBAnalyser/Types.hs

@@ -20,4 +20,6 @@ data DBAnalyserConfig = DBAnalyserConfig {
   , confLimit  :: Limit
   }
 
+-- | Whether to validate the on-disk files of the ChainDB. This is completely
+-- unrelated to validation of the ledger rules.
 data ValidateBlocks = ValidateAllBlocks | MinimumBlockValidation