add documentation and changelogs

Author: Cmdv

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Revision history for cardano-db-sync
 
+## 13.7.0.0
+
+### Summary
+- Complete migration from Persistent ORM to Hasql for direct PostgreSQL access.
+
+### Performance Improvements
+- 3-4x faster epoch processing: ~30min → ~8min per epoch
+- Improved cache efficiency: Stake address hit rates increased from 57-79% to 89-99%
+- Reduced memory overhead: Eliminated ORM abstraction layer
+
+### Compatibility
+- PostgreSQL schema remains unchanged
+- Existing database instances compatible without migration
+
 ## 13.6.0.5
 - Fix offchain data so it supports files up to 3MB [#1928]
 - Upgrade to PostgreSQL 17

doc/Readme.md

@@ -24,6 +24,8 @@ This directory contains various documentation files for setting up, configuring,
 
 10. [Migrations](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/migrations.md) - Details on database migrations for different versions of Cardano DB Sync, including instructions on applying migrations, handling schema changes, and ensuring data integrity during upgrades.
 
+11. [Developer Hasql Instructions](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/hasql.md) - Guide for developers working with the new Hasql implementation, covering the DbAction monad, statement construction patterns, type-safe schema operations, and migration strategies from the previous Persistent ORM to ensure efficient and maintainable database interactions.
+
 11. [Schema](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/schema.md) - Overview of the database schema used by the Cardano DB Sync Node, providing a detailed description of the tables, relationships, and data types used in the database.
 
 12. [Schema Management](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/schema-management.md) - Instructions on managing the database schema and creating migrations, covering tools and techniques for making schema changes and ensuring they are applied correctly.

doc/hasql.md

@@ -0,0 +1,95 @@
+# Developer Guide: Working with Hasql Implementation
+
+## Core Concepts
+
+### DbAction Monad
+All database operations now use `DbAction m` instead of `ReaderT SqlBackend m`:
+
+```haskell
+-- Old (Persistent)
+insertBlock :: MonadIO m => Block -> ReaderT SqlBackend m BlockId
+
+-- New (Hasql)
+insertBlock :: MonadIO m => Block -> DbAction m BlockId
+```
+
+### Statement Construction
+Database operations built using Hasql's encoder/decoder pattern:
+
+```haskell
+insertBlockStmt :: HsqlStmt.Statement Block BlockId
+insertBlockStmt = 
+  insert 
+    blockEncoder 
+    (WithResult $ HsqlD.singleRow $ idDecoder BlockId)
+```
+
+## Module Structure
+
+- `Cardano.Db.Schema.*` - Type-safe schema definitions
+- `Cardano.Db.Statement.*` - Database operations organized by domain
+- `Cardano.Db.Statement.Function.*` - Core statement building utilities
+
+## Key Operations
+
+### Inserts
+```haskell
+-- Simple insert
+insert :: HsqlE.Params a -> ResultType r r -> HsqlS.Statement a r
+
+-- Bulk insert
+insertBulk :: [a] -> DbAction m [r]
+
+-- Conditional insert
+insertIfUnique :: HsqlE.Params a -> ResultType r r -> HsqlS.Statement a r
+```
+
+### Queries
+```haskell
+-- Count operations
+countAll :: HsqlStmt.Statement () Word64
+countWhere :: Text -> Text -> HsqlStmt.Statement () Word64
+
+-- Existence checks
+existsById :: Key a -> DbAction m Bool
+existsWhereByColumn :: Text -> p -> DbAction m Bool
+```
+
+### Execution Pattern
+```haskell
+runOperation :: MonadIO m => SomeRecord -> DbAction m SomeId
+runOperation record = 
+  runDbSession (mkDbCallStack "runOperation") $
+    HsqlSes.statement record someStmt
+```
+
+## Type Safety
+
+### Column Validation
+All column references validated at compile time:
+```haskell
+validateColumn @Block "epoch_no"  -- Compile-time check
+```
+
+### Schema Correspondence
+Each table has corresponding encoder/decoder pairs ensuring type safety.
+
+## Migration Notes
+
+### Database Functions
+- Replace `rawSql` calls with typed statements
+- Use `HsqlStmt.Statement` construction pattern
+- Wrap operations in `runDbSession` with call stack
+
+### Error Handling
+```haskell
+-- Handle Maybe results
+case result of
+  Just value -> pure value
+  Nothing -> throwError $ DbError callStack errorMsg Nothing
+```
+
+### Testing
+- Test database roundtrips with property-based testing
+- Use `runDbLovelaceRoundtrip` style functions for validation
+- Test encoders/decoders separately from business logic