pg-instance-handler/README.md

pg-instance-handler

Reconcilie des bases PostgreSQL à partir d’un fichier YAML et gère leur cycle de vie (bases, utilisateurs, droits CONNECT, ownership).

Sommaire

• Aperçu rapide
• Démarrage rapide (Docker Compose)
• Spécification YAML
• Variables d’environnement
• Build local et exécution
• Opérations et sécurité
• Dépannage

Aperçu rapide

• Crée les bases manquantes et supprime celles non listées (sauf postgres).
• Crée/actualise un utilisateur par base, lui donne l’accès et l’ownership de la base.
• Définition de l’état désiré via un YAML monté dans le conteneur.

Code pertinent:

• Reconciliation: src/app/database/database_service.rs
• Spéc YAML / lecture état désiré: src/actors/driven/database_file_retriever.rs
• Accès Postgres (sqlx): src/actors/driven/sqlx_handler.rs
• Entrée: src/main.rs
• Conteneurs: Dockerfile, docker-compose.yml

Démarrage rapide (Docker Compose)

1. Préparez votre fichier YAML (exemple ci-dessous) à la racine du projet sous database.yaml.
2. Lancez:

docker compose up --build

Le service va:

• se connecter à PostgreSQL via DATABASE_URL (admin),
• réconcilier les bases selon database.yaml,
• créer/mettre à jour les utilisateurs et donner l’ownership,

Spécification YAML

Exemple minimal: database.yaml

databases:
  - name: hello
    user: hello_user
    password: hello_password

• name: nom de la base à gérer
• user: utilisateur propriétaire/consommateur de la base
• password: mot de passe de cet utilisateur

Notes:

• Les noms (name, user) sont validés (lettres, chiffres, underscore; commencent par lettre/underscore).
• Le programme ne supprime jamais la base postgres.

Variables d’environnement

• DATABASE_URL: URL admin PostgreSQL pour l’orchestrateur (ex: postgres://postgres:postgres@postgres:5432/postgres).

Les exemples d’ENV sont indiqués dans docker-compose.yml.

Build local et exécution

cargo build

Exécution locale (besoin d’un Postgres accessible et d’un database.yaml):

export DATABASE_URL="postgres://postgres:postgres@localhost:5432/postgres"

cargo run

Opérations et sécurité

• Suppression: par défaut, toute base non listée est supprimée (sauf postgres). Pour un MVP, gardez le YAML strict et versionné. On pourra ajouter un mode « dry-run » et/ou restreindre la gestion à un préfixe (ex: managed_).
• Permissions: l’utilisateur est LOGIN PASSWORD, reçoit CONNECT et devient owner de sa base.
• Droits DB: DATABASE_URL doit pointer une base admin avec droits de création/suppression et gestion des rôles.

Dépannage

• DROP DATABASE échoue: des connexions actives empêchent la suppression. Le programme essaie de terminer les sessions avant DROP; réessayez.

---

Contributions bienvenues. Pour toute évolution (dry-run, périmètre géré, migrations), ouvrez une issue/PR.