85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
<!-- file: docs/guides/POSTGRES_STORAGE.md -->
|
||
<!-- version: 5 -->
|
||
|
||
# Guide PostgreSQL et contrats de stockage
|
||
|
||
## Objectif
|
||
|
||
`ks-store` porte la frontière de stockage généraliste. PostgreSQL reste le backend opérationnel actif, mais il est encapsulé derrière la façade publique backend-agnostique `Store`.
|
||
|
||
## Connexion
|
||
|
||
Les consommateurs ne construisent plus `PostgresStore`, `PostgresStoreOptions` ni un pool SQLx. Ils transmettent le backend sélectionné et ses options résolues à `StoreOpenOptions`; `ks-store` valide et interprète ensuite les paramètres PostgreSQL.
|
||
|
||
```rust
|
||
let options = match ks_store::StoreOpenOptions::new(
|
||
true,
|
||
"postgres",
|
||
serde_json::json!({
|
||
"url": database_url,
|
||
"max_connections": 10,
|
||
"connect_timeout_ms": 10_000,
|
||
"auto_initialize_schema": true
|
||
}),
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
let store = match ks_store::Store::open(options).await {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
```
|
||
|
||
Le descripteur public éventuellement affiché provient du résumé runtime et est déjà masqué par `ks-store`. Le DSN brut et les options backend ne doivent jamais être propagés dans les DTO, erreurs applicatives ou logs normaux.
|
||
|
||
## 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
|
||
|
||
`0.5.3-pre.002` conserve temporairement le schéma PostgreSQL historique `kb_sol_*` et son mécanisme d'initialisation afin de réaliser d'abord la rupture d'API backend. `pre.003` reconstruit le baseline sous `k_sol_*`, range les ressources sous `ks-store/migrations/postgres/` et impose une instruction SQL par fichier exécutée par les fonctions privées du backend.
|
||
|
||
Les bases Devnet/Mainnet/test `0.5.2` sont reconstructibles : aucune compatibilité in-place n'est requise pour ce changement de baseline.
|
||
|
||
## 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 et la façade `Store` décrivent des opérations fonctionnelles indépendantes du moteur. PostgreSQL implémente ces contrats à l’intérieur de `ks-store`; aucune crate consommatrice ne reçoit `PgPool`, un type SQLx ou une requête concrète. Les opérations de lecture utilisent des filtres et paginations bornés.
|
||
|
||
## Diagnostics
|
||
|
||
La surface publique expose :
|
||
|
||
- health snapshot ;
|
||
- migration snapshot ;
|
||
- backend descriptor masqué ;
|
||
- résumé de configuration sanitisé ;
|
||
- résumé d'initialisation/vérification par modèle logique ;
|
||
- diagnostics de ressources raw/Core/decode/materialization sans nom physique d'objet.
|
||
|
||
Les noms de tables, index, contraintes et le SQL restent des détails backend-internes. Les traces PostgreSQL utilisent l’unique `target: crate::TRACING_TARGET` (`ks-store`) avec les champs structurés `backend="postgres"`, `domain="ks-store.pg"` et un `action` précis (`connection`, `migration`, `query`, `health`, `replay`, etc.).
|
||
|
||
## 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 détails PostgreSQL utiles au diagnostic restent backend-internes ; les erreurs traversant la façade publique ne doivent jamais divulguer DSN, password ou options sensibles.
|
||
|
||
## Références
|
||
|
||
- `docs/architecture/STORAGE_ARCHITECTURE.md` ;
|
||
- `ks-store/USAGE.md` ;
|
||
- `ks-store/README.md`.
|