fixes

Author: Cmdv

cardano-db-sync/cardano-db-sync.cabal

@@ -187,7 +187,6 @@ library
                       , lifted-base
                       , memory
                       , microlens
-                      -- , monad-control
                       , network-mux
                       , ouroboros-consensus
                       , ouroboros-consensus-cardano

cardano-db-sync/src/Cardano/DbSync.hs

@@ -246,24 +246,21 @@ runSyncNode metricsSetters trce iomgr dbConnSetting runNearTipMigrationFnc syncN
           -- communication channel between datalayer thread and chainsync-client thread
           threadChannels <- liftIO newThreadChannels
           liftIO $
-            race_
-              -- We split the main thread into two parts to allow for graceful shutdown of the main App db thread.
-              (runDbThread syncEnv threadChannels)
-              ( mapConcurrently_
-                  id
-                  [ runSyncNodeClient metricsSetters syncEnv iomgr trce threadChannels (enpSocketPath syncNodeParams)
-                  , runFetchOffChainPoolThread syncEnv syncNodeConfigFromFile
-                  , runFetchOffChainVoteThread syncEnv syncNodeConfigFromFile
-                  , runLedgerStateWriteThread (getTrace syncEnv) (envLedgerEnv syncEnv)
-                  ]
-              )
+            mapConcurrently_
+              id
+              [ runDbThread syncEnv threadChannels
+              , runSyncNodeClient metricsSetters syncEnv iomgr trce threadChannels (enpSocketPath syncNodeParams)
+              , runFetchOffChainPoolThread syncEnv syncNodeConfigFromFile
+              , runFetchOffChainVoteThread syncEnv syncNodeConfigFromFile
+              , runLedgerStateWriteThread (getTrace syncEnv) (envLedgerEnv syncEnv)
+              ]
     )
   where
     useShelleyInit :: SyncNodeConfig -> Bool
     useShelleyInit cfg =
       case dncShelleyHardFork cfg of
         CardanoTriggerHardForkAtEpoch (EpochNo 0) -> True
-        _other -> False
+        _ -> False
 
     removeJsonbFromSchemaConfig = ioRemoveJsonbFromSchema $ soptInsertOptions syncOptions
     maybeLedgerDir = enpMaybeLedgerStateDir syncNodeParams

cardano-db-sync/src/Cardano/DbSync/Api.hs

@@ -213,7 +213,7 @@ generateNewEpochEvents env details = do
         Strict.Just oldEpoch
           | currentEpochNo == EpochNo (1 + unEpochNo oldEpoch) ->
               Just $ LedgerNewEpoch currentEpochNo (getSyncStatus details)
-        _otherwise -> Nothing
+        _ -> Nothing
 
     newCurrentEpochNo :: CurrentEpochNo
     newCurrentEpochNo =
@@ -456,7 +456,7 @@ verifySnapshotPoint env snapPoints =
       let valid = find (\(_, h) -> lsfHash lsf == hashToAnnotation h) hashes
       case valid of
         Just (slot, hash) | slot == lsfSlotNo lsf -> pure $ convertToDiskPoint slot hash
-        _otherwise -> pure Nothing
+        _ -> pure Nothing
     validLedgerFileToPoint (InMemory pnt) = do
       case pnt of
         GenesisPoint -> pure Nothing
@@ -465,7 +465,7 @@ verifySnapshotPoint env snapPoints =
           let valid = find (\(_, dbHash) -> getHeaderHash hsh == dbHash) hashes
           case valid of
             Just (dbSlotNo, _) | slotNo == dbSlotNo -> pure $ Just (pnt, True)
-            _otherwise -> pure Nothing
+            _ -> pure Nothing
 
 convertToDiskPoint :: SlotNo -> ByteString -> Maybe (CardanoPoint, Bool)
 convertToDiskPoint slot hashBlob = (,False) <$> convertToPoint slot hashBlob

cardano-db-sync/src/Cardano/DbSync/Api/Ledger.hs

@@ -16,7 +16,7 @@ import Cardano.Ledger.Core (Value)
 import Cardano.Ledger.Mary.Value
 import Cardano.Ledger.Shelley.LedgerState
 import Cardano.Ledger.TxIn
-import Cardano.Prelude (ExceptT, lift, textShow, throwIO)
+import Cardano.Prelude (ExceptT, lift, textShow)
 import Control.Concurrent.Class.MonadSTM.Strict (atomically, readTVarIO, writeTVar)
 import Control.Monad.Extra
 import Control.Monad.IO.Class (liftIO)
@@ -34,12 +34,13 @@ import qualified Cardano.Db as DB
 import Cardano.DbSync.Api
 import Cardano.DbSync.Api.Types
 import Cardano.DbSync.Cache (queryTxIdWithCache)
+import Cardano.DbSync.DbEvent (liftDbLookupEither)
 import Cardano.DbSync.Era.Shelley.Generic.Tx.Babbage (fromTxOut)
 import Cardano.DbSync.Era.Shelley.Generic.Tx.Types (DBPlutusScript)
 import qualified Cardano.DbSync.Era.Shelley.Generic.Util as Generic
 import Cardano.DbSync.Era.Universal.Insert.Grouped
 import Cardano.DbSync.Era.Universal.Insert.Tx (insertTxOut)
-import Cardano.DbSync.Error (SyncNodeError)
+import Cardano.DbSync.Error (SyncNodeError, mkSyncNodeCallStack)
 import Cardano.DbSync.Ledger.State
 import Cardano.DbSync.Types
 import Cardano.DbSync.Util (maxBulkSize)
@@ -150,10 +151,7 @@ prepareTxOut ::
 prepareTxOut syncEnv (TxIn txIntxId (TxIx index), txOut) = do
   let txHashByteString = Generic.safeHashToByteString $ unTxId txIntxId
   let genTxOut = fromTxOut (fromIntegral index) txOut
-  eTxId <- queryTxIdWithCache syncEnv txIntxId
-  txId <- case eTxId of
-    Left err -> liftIO $ throwIO err
-    Right tid -> pure tid
+  txId <- liftDbLookupEither mkSyncNodeCallStack $ queryTxIdWithCache syncEnv txIntxId
   insertTxOut syncEnv iopts (txId, txHashByteString) genTxOut
   where
     iopts = soptInsertOptions $ envOptions syncEnv

cardano-db-sync/src/Cardano/DbSync/Cache.hs

@@ -51,7 +51,7 @@ import Cardano.DbSync.Cache.Epoch (rollbackMapEpochInCache)
 import qualified Cardano.DbSync.Cache.FIFO as FIFO
 import qualified Cardano.DbSync.Cache.LRU as LRU
 import Cardano.DbSync.Cache.Types (CacheAction (..), CacheInternal (..), CacheStatistics (..), CacheStatus (..), StakeCache (..), shouldCache)
-import Cardano.DbSync.DbEvent (liftDbLookup)
+import Cardano.DbSync.DbEvent (liftDbLookup, liftDbLookupMaybe)
 import qualified Cardano.DbSync.Era.Shelley.Generic.Util as Generic
 import Cardano.DbSync.Era.Shelley.Query
 import Cardano.DbSync.Error (SyncNodeError (..), mkSyncNodeCallStack)
@@ -218,14 +218,11 @@ queryPoolKeyWithCache ::
   SyncEnv ->
   CacheAction ->
   PoolKeyHash ->
-  ExceptT SyncNodeError DB.DbM (Either DB.DbSessionError DB.PoolHashId)
+  ExceptT SyncNodeError DB.DbM (Either DB.DbLookupError DB.PoolHashId)
 queryPoolKeyWithCache syncEnv cacheUA hsh =
   case envCache syncEnv of
     NoCache -> do
-      mPhId <- lift $ DB.queryPoolHashId (Generic.unKeyHashRaw hsh)
-      case mPhId of
-        Nothing -> pure $ Left $ DB.DbSessionError DB.mkDbCallStack "queryPoolKeyWithCache: NoCache queryPoolHashId"
-        Just phId -> pure $ Right phId
+      liftDbLookupMaybe DB.mkDbCallStack "NoCache queryPoolHashId" $ DB.queryPoolHashId (Generic.unKeyHashRaw hsh)
     ActiveCache ci -> do
       mp <- liftIO $ readTVarIO (cPools ci)
       case Map.lookup hsh mp of
@@ -240,10 +237,10 @@ queryPoolKeyWithCache syncEnv cacheUA hsh =
           pure $ Right phId
         Nothing -> do
           liftIO $ missPools syncEnv
-          mPhId <- lift $ DB.queryPoolHashId (Generic.unKeyHashRaw hsh)
-          case mPhId of
-            Nothing -> pure $ Left $ DB.DbSessionError DB.mkDbCallStack "queryPoolKeyWithCache: ActiveCache queryPoolHashId"
-            Just phId -> do
+          ePhId <- liftDbLookupMaybe DB.mkDbCallStack "ActiveCache queryPoolHashId" $ DB.queryPoolHashId (Generic.unKeyHashRaw hsh)
+          case ePhId of
+            Left err -> pure $ Left err
+            Right phId -> do
               -- missed so we can't evict even with 'EvictAndReturn'
               when (shouldCache cacheUA) $
                 liftIO $

cardano-db-sync/src/Cardano/DbSync/DbEvent.hs

@@ -7,6 +7,7 @@ module Cardano.DbSync.DbEvent (
   ThreadChannels (..),
   liftDbSession,
   liftDbLookup,
+  liftDbLookupMaybe,
   liftDbSessionEither,
   liftDbLookupEither,
   liftSessionIO,
@@ -217,6 +218,17 @@ liftDbLookupEither cs mResult = do
       Left dbErr -> throwError $ SNErrDbLookupError cs dbErr
       Right val -> pure val
 
+-- | Lift a Maybe-returning database operation to Either DbLookupError
+--
+-- Converts DbM (Maybe a) to ExceptT SyncNodeError DB.DbM (Either DB.DbLookupError a).
+-- Common pattern for database lookups that may not find results.
+liftDbLookupMaybe :: DB.DbCallStack -> Text -> DB.DbM (Maybe a) -> ExceptT SyncNodeError DB.DbM (Either DB.DbLookupError a)
+liftDbLookupMaybe cs errMsg dbAction = do
+  result <- lift dbAction
+  pure $ case result of
+    Nothing -> Left $ DB.DbLookupError cs errMsg
+    Just value -> Right value
+
 liftSessionIO :: SyncNodeCallStack -> ExceptT DB.DbSessionError IO a -> ExceptT SyncNodeError IO a
 liftSessionIO cs dbAction = do
   result <- liftIO $ runExceptT dbAction

cardano-db/src/Cardano/Db/Run.hs

@@ -154,6 +154,11 @@ runDbDirectSilent dbEnv action = do
         Left err -> throwIO err
         Right value -> pure value
 
+-- | Connection pool-based transaction runner
+--
+-- Uses a connection from the pool rather than the main DbEnv connection.
+-- Wraps operations in a transaction with logging. Designed for concurrent operations
+-- where multiple threads need independent database connections.
 runDbPoolTransLogged ::
   MonadUnliftIO m =>
   Trace IO Text ->
@@ -231,6 +236,11 @@ runDbStandaloneTransSilent source action = do
         runDbTransSilent dbEnv action
     )
 
+-- | Standalone runner without transaction management
+--
+-- Self-contained runner that creates its own connection but doesn't wrap operations
+-- in transactions. Uses auto-commit mode. Perfect for simple operations that don't
+-- need ACID guarantees or tools that manage their own transaction boundaries.
 runDbStandaloneDirectSilent :: PGPassSource -> DbM a -> IO a
 runDbStandaloneDirectSilent source action = do
   pgconfig <- runOrThrowIO (readPGPass source)

doc/database-encode-decode.md

@@ -14,6 +14,69 @@ data DbEnv = DbEnv
   }
 ```
 
+## Database Execution Functions
+
+Different `runDb*` functions provide various execution patterns for different use cases:
+
+### Transaction-Based Runners
+
+**`runDbTransLogged`** - Main synchronisation runner
+- Full ACID transaction guarantees with BEGIN/COMMIT/ROLLBACK
+- Comprehensive logging for debugging and monitoring
+- Primary runner for cardano-db-sync block processing
+- Automatically handles all transaction management
+
+**`runDbTransSilent`** - Performance-focused transaction runner  
+- Same transaction guarantees as logged version
+- No logging overhead for performance-critical operations
+- Ideal for testing scenarios or high-throughput operations
+
+**`runDbPoolTransLogged`** - Concurrent transaction runner
+- Uses connection pool instead of main connection
+- Full transaction management with logging
+- Designed for concurrent operations where multiple threads need independent connections
+- Requires DbEnv with connection pool configured
+
+### Direct Runners (No Transaction Management)
+
+**`runDbDirectLogged`** - Auto-commit with logging
+- No explicit transaction management (auto-commit mode)
+- Each statement commits immediately
+- Includes logging for debugging
+- Use when operations manage their own transactions
+
+**`runDbDirectSilent`** - Auto-commit without logging
+- No transaction management or logging overhead
+- Maximum performance for simple operations
+- Use for operations that don't need ACID guarantees
+
+### Standalone Runners
+
+**`runDbStandaloneSilent`** - Simple script runner
+- Self-contained with automatic connection management
+- Creates temporary connection from environment variables
+- Perfect for simple scripts and testing
+- Includes transaction management
+
+**`runDbStandaloneTransSilent`** - Configurable standalone runner
+- Custom connection configuration support
+- Full transaction management
+- Automatic resource cleanup
+- Good for applications needing custom connection settings
+
+**`runDbStandaloneDirectSilent`** - Script runner without transactions
+- Self-contained connection management
+- Auto-commit mode (no transactions)
+- Use for simple operations or tools that manage their own transaction boundaries
+
+### Pool-Based Runners
+
+**`runDbWithPool`** - External service runner
+- Designed for external services (like SMASH server)
+- Returns Either for explicit error handling (no exceptions)
+- Uses provided connection pool
+- Creates temporary DbEnv from pool connection
+
 ### Basic Usage
 
 ```haskell