4.7 KiB
ksp-store-postgres-lib
ksp-store-postgres-lib est le backend PostgreSQL physique officiel du Store KSP.
La crate implémente la fondation connexion/pool/TLS/migrations/health derrière ksp-store-lib. Elle dépend directement de ksp-store-api mais ne dépend jamais de la façade ksp-store-lib.
Responsabilités
La crate possède seule pour PostgreSQL :
- le parsing et la normalisation de la configuration physique
tokio-postgres; - le pool borné
deadpool-postgres; - la policy TLS physique avec Rustls ;
- les roots système et le provider cryptographique AWS-LC ;
- le bootstrap/moteur de migrations privé KSP ;
- la table metadata
ksp_store_schema_migrations; - la migration logique V000 relocalisée sous
migrations/v000_bootstrap/et son checksum SHA-256 historique ; - l'advisory transaction lock borné des migrations ;
- les snapshots runtime/health sûrs destinés au bridge de façade ;
- la fermeture explicite du pool et son fallback
Dropbest-effort ; - la classification d'erreurs backend sans conserver le texte d'erreur PostgreSQL.
Frontière d'utilisation
Les applications, jobs et workers KSP ne dépendent normalement pas de cette crate :
consumer -> ksp-store-lib -> [feature postgres] ksp-store-postgres-lib
La surface publique de cette crate existe pour le bridge inter-crates et les tests d'intégration backend. Elle ne constitue pas une seconde façade Store.
ksp-store-postgres-lib ne réexporte pas tokio-postgres, Deadpool ou Rustls.
Connexion et pool
PostgresBackend::open :
- valide et normalise l'URI fournie explicitement ;
- impose la policy TLS typée ;
- construit un pool borné ;
- prouve une connexion physique ;
- vérifie/applique le bootstrap selon les settings ;
- ne retourne qu'après succès de cette fondation.
Le backend ne lit aucun environnement, .env, PG*, .pgpass ou fichier TLS implicite libpq.
TLS
Les modes sont exactement :
Disabled
VerifyFull
VerifyFull exige :
- TLS ;
- roots système ;
- certificat valide ;
- vérification de l'identité serveur ;
- aucune dégradation automatique en plaintext.
Les configurations ne permettant pas de vérifier une identité serveur, comme hostaddr seul, sont rejetées.
Migrations
La fondation historique V000 est embarquée sous :
migrations/v000_bootstrap/tables/001_ksp_store_schema_migrations.sql
La vertical slice V001 est ensuite répartie sous migrations/v001_raw_transaction/{tables,constraints,indexes}/ tout en restant une migration logique unique. V000 crée la metadata privée :
ksp_store_schema_migrations
Le moteur vérifie version, nom et checksum SHA-256, sérialise les runners par advisory transaction lock et refuse une history divergente ou plus récente que le runtime.
Aucune migration métier RAW n'appartient à cette fondation.
Health et erreurs
PostgresBackendRuntimeSnapshot et PostgresBackendHealthSnapshot ne contiennent que des compteurs et états sûrs destinés à la façade.
PostgresBackendError ne conserve que :
PostgresBackendErrorKind
phase statique
Le texte d'erreur PostgreSQL, l'URI, SQL et les valeurs bind ne traversent pas cette frontière.
Support PostgreSQL
La politique de support de 0.3.2 fixe PostgreSQL 15 comme major minimal. Le test live de fondation refuse explicitement un serveur plus ancien ; le backend ne fixe aucun plafond arbitraire de major PostgreSQL. La compatibilité de migration reste basée sur le schéma KSP.
La preuve opérateur réelle et le major effectivement exercé sont conservés dans la matrice de validation, pas dans cette documentation durable.
Hors périmètre actuel
La crate ne contient encore :
- aucune implémentation PostgreSQL des capabilities
RawTransaction*; - aucune implémentation PostgreSQL des capabilities
RawAccount*; - aucun repository métier RAW ;
- aucune table/index métier ;
- aucune orchestration worker/job ;
- aucun transport d'acquisition ou decoder Program.
Documentation
USAGE.md— bridge physique et lifecycle ;../ksp-store-lib/README.md— façade runtime destinée aux consumers ;../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md— architecture Store ;../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md— décisions pool/TLS/migrations ;../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md— preuves déterministes et PostgreSQL réel.