73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
<!-- file: docs/guides/POSTGRES_STORAGE.md -->
|
||
<!-- version: 3 -->
|
||
|
||
# Guide PostgreSQL et contrats de stockage
|
||
|
||
## Objectif
|
||
|
||
`ks-store` consolide les contrats de stockage Core, raw, decode et PostgreSQL de bot2 dans une crate unique.
|
||
|
||
## Connexion
|
||
|
||
```rust
|
||
let options = match ks_store::PostgresStoreOptions::new(
|
||
database_url,
|
||
10,
|
||
10_000,
|
||
true,
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
|
||
let store = match ks_store::PostgresStore::connect(options).await {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
```
|
||
|
||
Toujours utiliser `masked_dsn()` dans les diagnostics.
|
||
|
||
## Domaines
|
||
|
||
- raw : acquisitions et observations ;
|
||
- Core : transactions, instructions, comptes et contexte normalisés ;
|
||
- decode : ledger, observations décodées et matérialisations ;
|
||
- replay : candidats et résumés bornés.
|
||
|
||
## Migrations
|
||
|
||
Les migrations sont idempotentes et ordonnées. Une nouvelle migration ne doit pas modifier rétroactivement une migration déjà publiée.
|
||
|
||
## Compatibilité des identités de processeurs
|
||
|
||
Depuis `0.5.1-pre.003`, les identités techniques produites par `ks-lib` utilisent `ks-lib-decoder.*`, `ks-lib-executor.*` et `ks-lib-materializer.*`. Une base alimentée avant cette migration peut encore contenir des valeurs `kb-lib.*` dans les contrats de provenance/replay.
|
||
|
||
Aucune migration SQL automatique de ces valeurs n'est ajoutée en `0.5.1` : avant `0.6.x`, une base conservée doit soit être reconstruite proprement, soit faire l'objet d'une migration de données explicitement contrôlée avant reprise du replay. Il ne faut pas exploiter durablement un même corpus avec les anciennes et nouvelles identités mélangées. Les noms de tables `kb_sol_*` restent inchangés jusqu'au chantier `0.5.3`.
|
||
|
||
## Repositories
|
||
|
||
Les traits publics séparent le contrat de l’implémentation PostgreSQL. Les opérations de lecture utilisent des filtres et paginations bornés.
|
||
|
||
## Diagnostics
|
||
|
||
- health snapshot ;
|
||
- migration snapshot ;
|
||
- backend diagnostics ;
|
||
- diagnostics des tables raw, Core et decode ;
|
||
- validation des noms de tables.
|
||
|
||
## Invariants
|
||
|
||
- aucune donnée canonique ne doit être dupliquée sans justification ;
|
||
- les écritures rejouables doivent être idempotentes ;
|
||
- la progression de campagne doit rester cohérente avec les lignes effectivement traitées ;
|
||
- les requêtes dynamiques n’acceptent que des identifiants validés ;
|
||
- les erreurs PostgreSQL restent distinctes des erreurs de contrat.
|
||
|
||
## Références
|
||
|
||
- `docs/architecture/STORAGE_ARCHITECTURE.md` ;
|
||
- `ks-store/USAGE.md` ;
|
||
- `ks-store/README.md`.
|