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.

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.

4.4 KiB Raw Blame History Unescape Escape