Checklist de refonte de base de données pour passer un prototype en production

Pourquoi les bases de prototype échouent en production

Les bases de prototype sont conçues pour prouver qu'une fonctionnalité fonctionne une fois, pas pour se comporter de la même façon tous les jours sous une charge réelle. Quand de vrais utilisateurs arrivent, la base de données est l'endroit où de petits raccourcis deviennent de grosses pannes.

Ce qui casse généralement en premier, c'est la prévisibilité. Des colonnes acceptent des valeurs inattendues. Le même enregistrement peut exister deux fois. Une relation « manquante » (comme une commande sans client) s'immisce parce que rien ne l'impose. Plus tard, l'application plante de manière confuse et le débogage devient de la conjecture.

La performance est la surprise suivante. Un prototype fonctionne sur des tables minimes, donc les requêtes lentes passent inaperçues. En production, un écran populaire peut déclencher des scans sur des milliers ou millions de lignes, et les temps de réponse explosent.

Les builds de hackathon et les applications générées par IA (avec des outils comme Lovable, Bolt, v0, Cursor ou Replit) rencontrent souvent ces problèmes rapidement. Elles sont livrées vite, mais la couche base de données est généralement « suffisante » jusqu'à ce que ce ne soit plus le cas.

Le but ici est simple : comportement prévisible, changements sûrs et débogage plus facile quand quelque chose casse.

Une attente à poser tôt : faites cela par petites étapes, pas une grosse réécriture. Au lieu de renommer toutes les tables d'un coup, commencez par empêcher l'apparition de nouvelles mauvaises données (contraintes), puis backfillez les anciennes lignes, ensuite changez le code applicatif, et seulement ensuite nettoyez les colonnes héritées. Chaque étape doit être facile à tester et à annuler.

Avant de changer quoi que ce soit : prenez l'inventaire et fixez le périmètre

Les refontes de base de données tournent mal quand des gens commencent à « nettoyer » sans savoir ce qui existe et de quoi l'app dépend. Avant de toucher une colonne, établissez un inventaire et mettez-vous d'accord sur ce que « fini » signifie.

Listez chaque objet de base de données dont votre appli pourrait dépendre, pas seulement les tables. Les prototypes cachent souvent de la logique dans des endroits étranges.

Notez :

• Tables et colonnes clés (en particulier les IDs, timestamps et champs de statut)
• Vues, triggers, fonctions/procédures stockées
• Historique des migrations (ce qui a été exécuté, ce qui a échoué, ce qui a été édité à la main)
• Jobs et scripts qui écrivent des données (imports, tâches cron, workers en arrière-plan)
• Environnements et copies (dev, staging, snapshots prod)

Ensuite, clarifiez la propriété et les promesses. Qui est responsable des données (engineering, ops, un client) ? Qu'est-ce que le produit promet aux utilisateurs : peuvent-ils supprimer des comptes, exporter des données ou changer d'email ? Ces promesses déterminent ce que vous pouvez renommer, fusionner ou supprimer en toute sécurité.

Capturez les points de douleur d'aujourd'hui en langage clair, puis reliez-les à des preuves : « la connexion est lente » (quelle requête ?), « nous voyons des doublons » (quelles tables/champs ?), « des relations sont implicites » (où des clés étrangères manquantes causent des lignes orphelines ?). Si vous corrigez une app générée par IA, attendez-vous à des migrations à moitié finies et à des hypothèses cachées.

Enfin, définissez le périmètre avec une base ennuyeuse : nombre de lignes, plus grosses tables, et 3–5 flux utilisateurs critiques qui doivent rester opérationnels (inscription, paiement, recherche, reporting admin). Décidez ce que vous corrigerez maintenant vs plus tard. Par exemple : contraintes et index clés maintenant, vues de reporting et polissage des noms plus tard.

Un rapide bilan vaut mieux qu'une refonte intelligente qui casse la production.

Nettoyage des noms et de la structure qui rapporte vite

Les schémas prototype grandissent souvent par accident. Une table utilise camelCase, une autre snake_case, les IDs ont des noms différents, et personne n'est sûr de quelles colonnes il est sûr de toucher. Nettoyer cela tôt facilite chaque changement ultérieur, des contraintes au débogage d'incident.

Commencez par choisir un style de nommage et utilisez-le partout.

Un jeu simple de conventions :

• Un pattern pour les tables (singulier ou pluriel) et pour les colonnes (snake_case est courant)
• Une convention pour la clé primaire (par exemple, chaque table a une colonne id)
• Une convention pour les clés étrangères (par exemple user_id pointe toujours vers users.id)
• Un schéma de nommage pour les index (pour repérer rapidement les doublons)

Renommez les champs qui invitent aux bugs. createdAt et created_at dans différentes tables entraînent des jointures erronées et des mappings ORM cassés. Il en va de même pour id qui signifie des choses différentes selon les tables. Si une colonne stocke une référence utilisateur, nommez-la comme une référence utilisateur.

Puis traitez le poids mort. Les schémas itérés rapidement gardent souvent d'anciennes colonnes que l'app ne lit plus. Si vous n'êtes pas prêt à supprimer une colonne, marquez-la comme dépréciée dans un commentaire et cessez d'y écrire.

Ajoutez de courts commentaires quand le sens n'est pas évident, en particulier pour :

• Valeurs autorisées spéciales (même si elles ne sont pas encore appliquées)
• Unités ou formats mixtes (cents vs dollars, UTC vs heure locale)
• Champs faciles à mal utiliser (flags de soft delete, champs de statut)

Contraintes : rendre difficile l'insertion de mauvaises données

Les contraintes sont le moyen le plus rapide pour transformer des données prototype « ça marche » en quelque chose de fiable.

Commencez par les clés primaires. Chaque table devrait en avoir une, et votre appli devrait vraiment l'utiliser. Si une table s'appuie sur le « nom » ou created_at comme identifiant, vous aurez des collisions, des mises à jour cassées et des jointures confuses.

Ajoutez NOT NULL là où votre appli attend une valeur à chaque fois. Si un utilisateur doit avoir un email, exigez-le. Si une commande doit avoir un statut, exigez-le. Avant d'activer NOT NULL, backfillez les lignes existantes pour que la migration ne plante pas en cours.

Ajoutez des contraintes UNIQUE pour arrêter les doublons que vous nettoieriez sans cesse : emails, IDs externes, codes d'invitation, slugs et « un profil par utilisateur ». Si des doublons existent déjà, décidez quel enregistrement garder, fusionnez prudemment, puis imposez UNIQUE.

Utilisez des contraintes CHECK pour des règles de sanity simples qui ne devraient jamais être violées. Gardez-les claires et prévisibles.

Liste rapide de vérification des contraintes

Pour chaque table :

• Une clé primaire existe
• Les champs requis sont NOT NULL (après backfill)
• Les identifiants naturels sont UNIQUE (email, external_id, slug)
• Les règles de sanity de base sont CHECKées (amount >= 0, rating entre 1 et 5)
• Les valeurs par défaut correspondent à la réalité (status par défaut pending, timestamps auto-remplis)

Décidez ce qui vit dans la base vs dans l'application, puis soyez cohérent. Les règles métier qui changent souvent peuvent rester dans le code, mais l'identité, l'unicité et la sanity de base appartiennent à la base.

Exemple : un prototype peut permettre plusieurs utilisateurs avec le même email et des mots de passe nuls. En production, cela entraîne des logins cassés et un risque d'usurpation de compte. Une première étape pratique est de nettoyer les lignes existantes, puis d'ajouter UNIQUE(email) et NOT NULL pour empêcher que de mauvaises données réapparaissent.

Clés étrangères et relations : transformer les hypothèses en règles

Beaucoup de prototypes comptent sur « on gère ça dans le code ». En production, cela se transforme en lignes orphelines, cas limites et débogage compliqué.

Commencez par trouver les relations qui existent dans l'app mais pas dans la base. Si votre code utilise userId, team_id ou order_id, traitez cela comme une vraie relation même si rien ne l'impose encore.

Une méthode pratique pour cartographier ce qui est réel :

• Scannez les tables pour les colonnes *_id et confirmez ce qu'elles pointent dans le code
• Cherchez des jobs de nettoyage ou des corrections qui mentionnent « parent manquant » ou « introuvable »
• Comptez les orphelins probables (lignes enfants sans parent correspondant) avant d'ajouter des règles
• Ajoutez des clés étrangères uniquement pour les relations dont vous dépendez vraiment
• Ajoutez un index sur la colonne de clé étrangère quand vous faites des jointures ou filtres dessus

Quand vous ajoutez une clé étrangère, décidez de l'effet sur suppression selon les règles produit :

• RESTRICT : bloquer la suppression si des enfants existent (bon pour factures, logs d'audit)
• CASCADE : supprimer automatiquement les enfants (bon pour les données temporaires ou dérivées)
• SET NULL : garder les enfants mais les détacher (bon pour une propriété optionnelle)
• Soft delete plutôt que suppression dure quand l'historique compte

Les relations circulaires peuvent mordre pendant les migrations. Si users référence teams et teams référence users (propriétaire), mettez un côté nullable d'abord, backfillez par lots, puis renforcez les contraintes une fois que les données sont cohérentes.

Les clés étrangères améliorent la cohérence, mais elles ne rendent pas automatiquement les requêtes rapides. Si vous joignez orders.customer_id à customers.id constamment, indexer orders.customer_id fait souvent la différence entre « OK en staging » et « problématique en production ».

Types de données et valeurs par défaut : réduire les surprises

Les schémas prototype utilisent souvent text pour tout parce que « ça marche ». Les problèmes en production apparaissent plus tard : le tri casse, les rapports mentent, et de petites erreurs d'entrée deviennent du nettoyage.

Remplacez les types vagues par ceux qui correspondent au sens. Les dates doivent être des dates, les flags des booleans, et les compteurs des entiers.

L'argent et les mesures demandent une attention particulière. Évitez les flottants pour la monnaie. Utilisez des nombres à précision fixe (par exemple numeric(12,2)) pour que les totaux s'additionnent de la même manière à chaque fois. Faites de même pour poids, distances et pourcentages : choisissez une précision et tenez-vous-y.

Les fuseaux horaires sont une autre source courante de bugs. Une valeur pratique par défaut est de stocker les timestamps en UTC dans la base, puis de les formater pour les utilisateurs dans l'app.

Les valeurs par défaut retirent des « valeurs magiques » du code applicatif. Au lieu de compter sur le frontend pour tout remplir, donnez des valeurs par défaut claires comme created_at = now() et un status avec un petit ensemble de valeurs autorisées.

Avant d'appliquer de nouveaux types, planifiez le nettoyage et le backfill. Un schéma sûr :

• Ajoutez une nouvelle colonne avec le bon type
• Backfillez-la depuis l'ancienne colonne (en traitant les valeurs incorrectes)
• Validez avec des comptes et des vérifications ponctuelles
• Basculez l'app pour écrire dans la nouvelle colonne
• Supprimez ou verrouillez l'ancienne colonne

Exemple : si users.is_active est actuellement text avec des valeurs comme "yes", "Y", "1" et des vides, définissez un mapping, backfillez vers un boolean, puis ajoutez NOT NULL et un défaut après validation.

Indexes : accélérer les requêtes réelles sans en faire trop

Les index peuvent faire paraître un prototype prêt pour la production, mais ils peuvent aussi ralentir les écritures si vous les ajoutez aveuglément. Commencez par ce que font réellement les utilisateurs.

Travaillez à partir des actions utilisateur les plus lentes et retrouvez les requêtes qui les causent. Un écran de connexion qui bloque, un tableau de bord qui met 5 secondes à charger, ou une page « commandes » qui timeoute se traduisent souvent par un petit ensemble de requêtes à corriger en priorité.

Créez des index qui correspondent aux filtres et jointures réels. Si votre appli exécute souvent « trouver les factures pour le compte X dans les 30 derniers jours », un index sur created_at seul peut ne pas aider. Un index composite sur (account_id, created_at) correspond souvent mieux à la manière dont la requête restreint les résultats.

Évitez d'indexer tout. Chaque index supplémentaire ajoute un coût aux inserts, updates et deletes. Ce compromis est acceptable pour les tables majoritairement lues, mais pénalisant pour les tables très écrites comme les logs d'événements.

Un passage rapide pour les index :

• Capturez les requêtes exactes derrière les 5 écrans ou appels API les plus lents
• Indexez les colonnes utilisées dans les filtres WHERE et les clés de JOIN (surtout les colonnes de FK)
• Ajoutez des index composites quand les requêtes filtrent par deux colonnes ensemble
• Évitez les index qui se chevauchent (les nouveaux rendant les anciens inutiles)
• Prévoyez une passe de suivi pour supprimer les index jamais utilisés

Gardez une note de rollback pour chaque changement d'index. Supprimer un nouvel index est facile, mais reconstruire un index supprimé pendant une panne peut prendre du temps sur de grandes tables.

Vérifications de sécurité et de confidentialité pour un schéma production

Les prototypes font souvent confiance : ils supposent des entrées propres, un accès correct et des logs inoffensifs. La production est l'inverse. Décidez ce qui doit être protégé, puis faites en sorte que la base de données le supporte.

Commencez par nommer vos données sensibles : hash de mot de passe, tokens de réinitialisation, tokens de session, clés API, emails, numéros de téléphone, adresses, et tout ce qui identifie un utilisateur. Si vous n'avez pas besoin de stocker quelque chose, ne le stockez pas.

Stockage, logs et contrôle d'accès

Assurez-vous que les secrets ne sont pas dans des colonnes en clair, des messages d'erreur ou des tables de debug. Les tokens doivent être hashés quand c'est possible, et de courte durée.

Vérifiez aussi les logs. Beaucoup de prototypes loguent le corps des requêtes, ce qui peut capturer en coulisse des mots de passe ou des PII.

Définissez des rôles de base de données afin que le compte applicatif ne puisse faire que ce dont il a besoin. En règle générale, le rôle applicatif ne devrait pas pouvoir dropper des tables ou accéder aux données admin.

Une configuration de rôles simple :

• Rôle app : lecture/écriture uniquement sur les tables nécessaires
• Rôle admin : migrations, backfills, corrections ponctuelles
• Rôle lecture seule : vues analytics ou support (si nécessaire)
• Identifiants séparés par environnement (dev, staging, prod)

Injection et décisions de rétention

Même avec un schéma « sûr », des requêtes dangereuses peuvent tout casser. Cherchez du SQL dynamique construit à partir de chaînes (en particulier pour des filtres, champs de tri et recherche).

Enfin, décidez des règles de rétention et de suppression. Exemples : « Supprimer les comptes inactifs après 24 mois » ou « Supprimer définitivement les pièces jointes support après 30 jours ». Notez-le, puis concevez pour ça (timestamps, flags de soft-delete, jobs de purge si nécessaire).

Étape par étape : un ordre sûr pour les changements de schéma

Les refontes de schéma échouent quand vous changez trop de choses d'un coup sans moyen simple de revenir en arrière. Le but n'est pas un design parfait. Ce sont des changements réversibles.

Commencez par prouver que vous pouvez récupérer. Prenez une sauvegarde fraîche, restaurez-la dans un environnement séparé et exécutez un smoke test. Si vous ne pouvez pas restaurer rapidement, vous n'avez pas de plan de rollback.

Un ordre sûr que la plupart des équipes peuvent suivre :

1. Ajouter avant de supprimer. Créez nouvelles tables, colonnes et contraintes sans casser. Gardez les anciennes parties pour l'instant.
2. Backfill par petits lots. Déplacez les données par paquets pour surveiller erreurs, temps de verrou et performance. Vérifiez les comptes et faites des contrôles ponctuels après chaque lot.
3. Écrire dans les deux emplacements (temporairement). Mettez à jour l'app pour que les nouvelles écritures aillent vers le nouveau schéma (et éventuellement miroir vers l'ancien) pendant que les lectures peuvent retomber en arrière si nécessaire.
4. Basculer les lectures vers le nouveau schéma. Changez les requêtes, rapports et jobs en arrière-plan. Surveillez les requêtes lentes et les cas limites manquants.
5. Supprimer les anciennes parties en dernier. Après une période stable, supprimez les anciennes colonnes, tables et chemins de code temporaires.

Exemple : remplacez users.phone (texte libre) par user_phones (une ligne par numéro, validé). Ajoutez la nouvelle table, backfillez, mettez l'app à lire depuis user_phones, puis plus tard retirez users.phone.

Documentez chaque changement avec un déclencheur de rollback : « si le taux d'erreur dépasse X », « si la latence du checkout augmente de Y », ou « si le backfill crée plus de N lignes invalides ».

Pièges communs que les équipes rencontrent pendant les refontes

La plupart des refontes de base de données échouent pour les mêmes raisons : trop de changements d'un coup, pas assez de preuves que les données sont propres, et pas assez de respect pour ce qui tourne déjà.

Pièges qui causent pannes (ou rollbacks lents)

Regrouper plusieurs changements cassants dans une seule migration est une erreur classique. Gardez les changements petits, et sachez toujours à quoi ressemble « revenir à la normale » avant de déployer.

Problèmes courants :

• Renforcer des règles avant de corriger les lignes existantes. Les nouvelles NOT NULL, UNIQUE ou CHECK échoueront si les anciennes données les violent.
• Index manquants sur colonnes de relation et filtres courants (comme status, user_id, created_at).
• Renommages de colonnes sans traquer toutes les dépendances : jobs en arrière-plan, scripts, dashboards, extractions ETL et rapports ponctuels.
• Migrations qui verrouillent les tables plus longtemps que prévu. Les gros backfills, contraintes et constructions d'index peuvent bloquer les écritures.
• Pas de plan de rollback clair. Si vous ne pouvez pas revenir vite, vous finissez par corriger en avant sous pression.

Exemple : un prototype a une table orders où certaines lignes ont user_id à null, et status est du texte libre. Si vous ajoutez une clé étrangère et un CHECK d'un coup, la migration échoue et le déploiement bloque. Un chemin plus sûr : backfiller user_id quand c'est possible, mettre les autres en quarantaine, normaliser status, puis ajouter les contraintes.

Exemple de checklist : du prototype désordonné à prêt pour la production

Une histoire commune : un prototype généré par IA livre vite des tables comme users, orders et payments. Ça marche en démo, puis la production arrive et des bugs étranges apparaissent.

Une équipe remarque que des clients se connectent parfois sur le mauvais compte. La cause est simple : users.email n'est pas unique, donc des doublons existent (comme [email protected] et [email protected]). Un autre bug : une commande apparaît sans utilisateur car orders.user_id n'est qu'un entier, pas une relation réelle. Le support voit aussi des paiements qui ne correspondent à aucune commande parce que payments.order_id est manquant ou pointe vers une ligne supprimée.

Une checklist qui corrige les plus gros problèmes sans tout redesigner :

• Normaliser et faire respecter l'unicité des emails (en minuscules), puis ajouter une contrainte UNIQUE.
• Ajouter des clés étrangères : orders.user_id référence users.id et payments.order_id référence orders.id. Utilisez des règles de suppression claires (souvent RESTRICT pour les paiements).
• Corriger les types qui causent des bugs silencieux : nombres à précision fixe pour la monnaie, timestamps appropriés et éviter les IDs en texte libre.
• Ajouter quelques index à forte valeur : orders(user_id, created_at) pour les pages de compte, et payments(order_id) pour les requêtes de rapprochement.

Prévoyez un moment de rollback : vous ajoutez la contrainte d'email unique et elle échoue à cause des doublons. Faites-le en phases : ajoutez une colonne normalisée et backfillez-la, dédupliquez (gardez l'utilisateur actif le plus récent, fusionnez les commandes liées), puis ajoutez la contrainte. Si vous devez revenir en arrière, vous pouvez supprimer la contrainte sans annuler le travail de nettoyage.

Étapes suivantes : lancez un court audit, puis changez par phases. Si vous héritez d'un prototype IA cassé, FixMyMess (fixmymess.ai) se concentre sur le diagnostic des problèmes de base de données et de code comme migrations fragiles, secrets exposés et authentification cassée, pour que vous puissiez corriger les parties à plus haut risque avant de toucher quoi que ce soit de cosmétique.