92 lines
3.9 KiB
Markdown
92 lines
3.9 KiB
Markdown
<!-- file: docs/POSTGRES_STORE.md -->
|
||
<!-- version: 10 -->
|
||
|
||
# Store PostgreSQL canonique
|
||
|
||
## Baseline active
|
||
|
||
PostgreSQL reste le backend principal. Le store utilise le schéma courant du profil, généralement `public`, et ne qualifie pas les tables par un schéma applicatif explicite.
|
||
|
||
La baseline active contient :
|
||
|
||
```text
|
||
kb_sol_raw_transactions
|
||
kb_sol_obs_transaction_observations
|
||
kb_sol_core_transactions
|
||
kb_sol_core_account_keys
|
||
kb_sol_core_instructions
|
||
kb_sol_core_inner_instructions
|
||
kb_sol_core_logs
|
||
kb_sol_core_balance_changes
|
||
kb_sol_ops_processing_ledger
|
||
kb_sol_decode_events
|
||
kb_sol_decode_coverage_declarations
|
||
kb_sol_decode_coverage_observations
|
||
kb_sol_mat_events
|
||
```
|
||
|
||
## Initialisation
|
||
|
||
Le projet utilise encore des DDL idempotents gérés par `kb_store_pg`. `_sqlx_migrations` n’est pas requis pour démarrer l’application.
|
||
|
||
Les fichiers SQL actifs sont conservés comme représentation lisible de la baseline :
|
||
|
||
```text
|
||
0001_canonical_transaction_store.sql
|
||
0002_core_store.sql
|
||
0003_processing_ledger.sql
|
||
0004_decode_materialization_store.sql
|
||
```
|
||
|
||
Au démarrage Tauri, `initialize_store_schema()` applique une seule fois, dans l’ordre, les DDL raw, core puis decode/mat. Les connexions ouvertes ensuite par les commandes de démo désactivent `auto_initialize_schema` et ne relancent plus les migrations. Les méthodes spécialisées restent disponibles pour les tests et outils qui demandent explicitement l’initialisation d’un sous-ensemble dépendant.
|
||
|
||
## Extraction canonique vers core
|
||
|
||
`CoreExtractionStore` sélectionne les lignes raw, vérifie le ledger puis persiste un `CoreExtractionBundle` dans une transaction PostgreSQL unique.
|
||
|
||
Le mode normal skippe la combinaison déjà réussie :
|
||
|
||
```text
|
||
processor version + signature + canonical hash
|
||
```
|
||
|
||
Le replay forcé remplace uniquement le graphe de la signature ciblée. Les autres signatures ne sont pas modifiées.
|
||
|
||
## Tests PostgreSQL
|
||
|
||
Les tests qui utilisent `KB_POSTGRES_TEST_URL` doivent être lancés sur une base dédiée ou suivis d’un nettoyage explicite.
|
||
|
||
Depuis `0.4.1-pre.021`, les tests optionnels qui partagent une base PostgreSQL réelle acquièrent un verrou process-local test-only. Ce verrou évite les interblocages intermittents entre campagnes de tests parallèles sans changer le code runtime ni le schéma SQL.
|
||
|
||
Les tests optionnels couvrent notamment le rollback atomique core/decode, la persistance réelle du ledger et la sémantique exacte des déclarations de couverture. `optional_postgres_core_extraction_rolls_back_partial_graph_from_env` :
|
||
|
||
1. insère une ligne raw isolée ;
|
||
2. tente de persister un bundle contenant deux account keys avec le même index ;
|
||
3. attend une violation de l’index unique après le début de la transaction ;
|
||
4. vérifie qu’aucune transaction core, account key ou entrée ledger n’a été conservée et que le raw reste `received` ;
|
||
5. rejoue un bundle corrigé ;
|
||
6. vérifie le passage à `core_extracted` et le ledger `succeeded` ;
|
||
7. nettoie ses lignes de test.
|
||
|
||
Commande de clôture :
|
||
|
||
```bash
|
||
KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
|
||
cargo test -p kb_store_pg -- --nocapture
|
||
```
|
||
|
||
Les contrôles réels déjà effectués sur la base principale ont confirmé :
|
||
|
||
- 70 transactions raw et core ;
|
||
- 70 entrées ledger `succeeded` ;
|
||
- 84 tentatives après un force replay de 14 signatures ;
|
||
- aucune duplication ni ligne fille orpheline ;
|
||
- cardinalité core inchangée après remplacement forcé.
|
||
|
||
|
||
## Couverture et skip decode
|
||
|
||
`persist_decode_coverage_declarations()` synchronise le snapshot déclaré d’un processor/version et retourne des compteurs exacts : insertion réelle, modification/suppression du snapshot ou déclaration inchangée.
|
||
|
||
Le test PostgreSQL `optional_postgres_same_version_and_hash_is_current_from_env` persiste un résultat `unsupported` puis vérifie que le même stage, processor, version, input key et input hash est reconnu comme courant par le ledger.
|