Bonnes pratiques base de données

Migrations et schéma

• Modifier le schéma uniquement dans apps/server/src/db/schema/*.ts, puis générer la migration avec bun run db:generate.
• Relire le SQL généré dans apps/server/drizzle/ avant de le committer.
• Committer la migration avec le code qui en dépend.
• Appliquer les migrations avant de déployer ce code (bun run db:migrate). En Helm, c'est fait par l'initContainer du serveur.
• Ne pas exécuter de DDL à la main en production : le journal Drizzle ne le verrait pas.
• db:push pousse le schéma sans migration : réservé au développement local.

Accès et sécurité

• Utiliser un utilisateur PostgreSQL dédié à l'application. Le serveur doit pouvoir lire et écrire les tables ; le DDL passe par l'utilisateur de migration.
• Ne jamais mettre DATABASE_URL ou CHAINLIT_DATABASE_URL dans le code ou dans une image Docker. Utiliser les secrets du cluster.
• Limiter les connexions aux services autorisés : le serveur, document-processor et rag-agent.
• Activer SSL pour les connexions en production.

Données sensibles

• La base contient les documents importés et leurs catégories : les copies de la base (sauvegardes, environnements de test) héritent de cette sensibilité.
• Les noms et e-mails des utilisateurs sont dans user. Aucun mécanisme d'anonymisation n'est en place dans le code actuel : ne pas copier une base de production vers un environnement moins protégé sans l'accord du responsable.

Index et performances

Les index présents dans le schéma couvrent les accès fréquents (voir Schéma). Ajouter un index seulement si une requête lente apparaît, après analyse avec EXPLAIN ANALYZE.

Embeddings

• chunks.embedding et qa_pair.embedding stockent un vecteur float32 (4 octets par dimension) sous forme de bytea.
• Les embeddings sont calculés par rag-agent via LiteLLM, lors de la régénération des index. Seuls les éléments sans embedding sont calculés.
• Les index ne reflètent un import ou une modification qu'après une régénération : lancer regenerateIndex après chaque changement.

Index FAISS (indexes)

• Chaque régénération crée un index par rôle. L'index précédent du rôle passe à is_active = false.
• rag-agent ne conserve que les 3 derniers index par rôle et supprime le reste, avec leurs liens index_chunks. Aucun nettoyage manuel n'est nécessaire.

Sauvegardes

• Configurer des sauvegardes automatiques (pg_dump ou archivage WAL) avec une rétention adaptée.
• Tester les restaurations régulièrement.
• En Kubernetes, utiliser un opérateur PostgreSQL pour les sauvegardes continues.

Surveillance

• Activer pg_stat_statements pour repérer les requêtes lentes.
• Suivre la taille des tables avec pg_total_relation_size. Les tables chunks, qa_pair et indexes sont les plus volumineuses.