67 lines
1.9 KiB
Markdown
67 lines
1.9 KiB
Markdown
<!-- file: docs/guides/POSTGRES_STORAGE.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# 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.
|
||
|
||
## 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`.
|