Importations CSV volumineuses en production sans planter l'application

Pourquoi les gros imports CSV échouent en production

Un import CSV peut sembler correct avec un petit fichier de test, puis se casser la première fois qu'un client réel télécharge 300 000 lignes. La production a des réseaux plus lents, des limites de temps plus strictes et des données désordonnées. Si l'import a été bâti vite, il suppose souvent que tout est propre et petit.

La panne la plus courante est la mémoire. Beaucoup d'importations lisent le fichier entier en RAM, puis le transforment en objets, le valident, et conservent tout dans des tableaux jusqu'à la fin. Un fichier qui paraît "pas si gros" peut néanmoins exploser la mémoire une fois transformé en structures applicatives. Ajoutez quelques uploads concurrents et le serveur commence à swapper, à ralentir ou à redémarrer.

La deuxième grosse panne est le temps. Les requêtes web et les jobs serverless ont souvent des limites d'exécution strictes. Même si un import finirait en 10 minutes, il peut être tué après 60 secondes et vous laisser avec des données partiellement écrites.

Autres points de rupture courants :

• Pics de mémoire dus au chargement du fichier entier ou au buffering excessif
• Timeouts causés par la validation et les écritures en base dans la requête
• Une ligne erronée qui fait planter tout l'import
• Doublons dus aux retries, double-clics ou réuploads du même fichier
• Écritures partielles qui laissent les données incohérentes

Pour l'utilisateur, l'expérience est simple : la page se fige, le spinner tourne sans fin, ou un message vague « Import failed » apparaît sans indication pour corriger. Pire : des lignes manquantes ne sont parfois remarquées que des jours plus tard.

Ce dont votre équipe a besoin, c'est du contraire : des résultats prévisibles et des preuves. Vous voulez savoir combien de lignes ont été acceptées, rejetées et ignorées, et pourquoi exactement. Cette clarté transforme une opération effrayante en une tâche routinière.

Un petit exemple : un client importe une liste de ventes avec une colonne email vide à la ligne 18 237. Si votre importeur lève une exception et s'arrête, vous perdez des heures et de la confiance. S'il enregistre l'erreur de la ligne et continue, vous terminez le travail et retournez un rapport exploitables.

Que signifie « sûr » pour votre import CSV

Un import CSV est sûr lorsqu'il se termine sans faire tomber votre application et que le résultat est prévisible. La plupart des pannes en production surviennent parce que l'import essaie d'en faire trop d'un coup ou parce que les règles sont floues.

Commencez par décider ce que « succès » signifie pour vos utilisateurs :

• Tout-ou-rien : si une ligne est erronée, rien n'est sauvegardé.
• Succès partiel : les bonnes lignes sont importées, les mauvaises sont rejetées avec des raisons claires.

Le succès partiel est généralement plus tolérant pour les utilisateurs, mais il demande une conception minutieuse pour ne pas aboutir à des données à moitié créées qui cassent d'autres parties de l'app.

Fixez les attentes dès le départ. Une bonne fonctionnalité d'import n'est pas illimitée. Mettez des limites claires sur la taille du fichier et le nombre de lignes, et soyez strict sur les colonnes obligatoires. Si une colonne est requise (comme email, SKU ou user_id), échouez rapidement avant d'effectuer des opérations lourdes. Si un champ est optionnel, traitez les valeurs manquantes comme normales et documentez la valeur par défaut que vous appliquez.

Règles strictes vs flexibles

Soyez strict sur la structure, flexible sur le contenu.

• Structure : entêtes obligatoires, types de données indispensables, relations dont dépend votre application.
• Contenu : colonnes supplémentaires ignorées, champs optionnels, petits écarts de format que vous pouvez normaliser (comme trim des espaces).

Une façon simple de définir la sécurité est de répondre à :

• Quelles limites allez-vous appliquer (lignes, taille, entêtes obligatoires) ?
• Quelles erreurs stoppent tout l'import, et lesquelles ne rejettent qu'une ligne ?
• Que loggez-vous pour le support et que montrez-vous à l'utilisateur ?
• Comment empêcherez-vous le même fichier d'être importé deux fois ?

Le dernier point, c'est l'idempotence. Donnez à chaque import une clé stable (par exemple le checksum du fichier plus l'utilisateur et une fenêtre temporelle) et rendez les soumissions répétées sûres.

Parser en streaming plutôt que charger le fichier entier

Charger un CSV entier en mémoire fonctionne dans les démos, puis s'effondre en production. Un fichier client peut faire des centaines de Mo. Si votre application le lit en une fois, la mémoire explose, les requêtes expirent et le serveur peut redémarrer.

Le streaming maintient la mémoire plate. Au lieu de construire une énorme chaîne ou un grand tableau, vous lisez un petit morceau, parsez quelques lignes, les traitez, puis continuez. Bien fait, le streaming est la base d'importations fiables car il limite les dégâts qu'un mauvais fichier peut causer.

À quoi ressemble le streaming en pratique

Un parseur en streaming lit des octets de l'upload par petits morceaux, puis émet des lignes complètes dès qu'il le peut. Votre code d'import traite les lignes une par une ou en petits lots, de sorte que le travail progresse même quand le fichier est énorme.

C'est aussi là que les bizarreries réelles des CSV apparaissent :

• Encodage : imposez UTF-8 (ou détectez-le) et échouez vite si le décodage est impossible.
• Délimiteurs : supportez la virgule vs le point-virgule quand c'est pertinent, mais n'essayez pas de deviner indéfiniment.
• Champs cités : utilisez un vrai parseur CSV pour que les virgules dans des guillemets ne séparant pas les colonnes.
• Sauts de ligne : acceptez les fins de ligne Windows et Unix sans fausser le comptage des lignes.

Avant de traiter des milliers de lignes, détectez tôt les problèmes fatals au niveau fichier. Si les entêtes manquent ou si les colonnes ne correspondent pas à ce que vous attendez, continuer ne fait que créer du bruit.

Un garde-fou simple :

• Le fichier n'est pas vide et a une ligne d'entêtes
• Les colonnes requises existent
• Le délimiteur et les règles de citation analysent proprement les N premières lignes
• Le nombre de colonnes est dans un max raisonnable (protège contre un quoting cassé)

Validation au niveau ligne pour détecter tôt les problèmes

Considérez la validation comme un entonnoir : vérifiez le fichier une fois, puis chaque ligne au fur et à mesure qu'elle arrive.

Les vérifications au niveau fichier répondent à « est-ce le bon fichier ? » avant de toucher la base. Confirmez les noms d'entêtes, l'encodage, le délimiteur et les limites de taille approximatives. Si l'entête est incorrect, arrêtez tôt avec un message clair.

Les vérifications au niveau ligne répondent à « cette ligne est-elle exploitable ? » et doivent s'exécuter indépendamment pour chaque ligne. Une mauvaise ligne ne devrait pas faire planter l'import ni empoisonner tout le lot.

Un validateur de ligne pratique couvre :

• Champs obligatoires (email manquant, SKU vide)
• Types et plages (quantités non négatives, prix dans des limites sensées)
• Dates et formats (dates invalides comme 2025-02-30)
• Valeurs autorisées (status doit être active, paused ou archived)
• Règles métiers (clés uniques, relations valides comme customer_id existant)

Normalisez les entrées avant validation pour ne pas rejeter des données essentiellement correctes. Supprimez les espaces, standardisez la casse quand c'est utile (comme pour les emails), et traitez les nulls courants ("N/A", "null", "-") comme vides. Appliquez la même normalisation partout pour que des doublons ne passent pas comme "ACME" vs "acme ".

Gardez les messages de validation courts et exploitables. Un bon modèle : numéro de ligne, colonne, problème et un indice.

Exemple : “Ligne 128, start_date : date invalide. Utilisez YYYY-MM-DD.”

Idempotence et protection contre les doublons

Un import CSV paraît simple jusqu'à ce que quelqu'un clique « Import » deux fois, que le navigateur réessaie ou que deux collègues uploadent le même fichier en même temps. Sans idempotence, vous n'obtenez pas seulement des doublons : vous pouvez aussi avoir des mises à jour conflictuelles et des totaux erronés.

Commencez par décider comment le système reconnaîtra « cette même ligne ». Les numéros de ligne ne sont pas stables si les utilisateurs trient ou modifient le fichier, alors associez-les à des champs clés décrivant l'enregistrement.

Approches courantes :

• Clés naturelles (email pour un utilisateur, SKU pour un produit)
• IDs externes (un ID du système source)
• Clé composite (organization_id + invoice_number)
• Clé d'import au niveau fichier plus empreinte par ligne (hash des champs clés)

Les retries doivent être sûrs par conception. Créez un enregistrement de « session d'import » au démarrage de l'upload, puis enregistrez le résultat de chaque ligne contre cette session. Ajoutez une clé d'idempotence par ligne et appliquez-la via une contrainte d'unicité en base. Si la même ligne arrive de nouveau, ignorez-la ou transformez-la en mise à jour selon vos règles.

Les conditions de concurrence apparaissent lorsque deux imports touchent les mêmes enregistrements. Utilisez des contraintes en base comme garde-fou final et contrôlez la concurrence. Par exemple, traitez les imports pour le même tenant un par un, ou lockez par clé naturelle lors des écritures.

Échecs partiels sans corrompre les données

Les échecs partiels sont normaux avec des fichiers clients. Le risque n'est pas que quelques lignes soient erronées, mais d'aboutir à des données à moitié écrites qui cassent le reste de l'app.

Votre objectif doit être simple : l'import se termine dans un état connu-valide, ou il ne laisse pas la base modifiée.

Choisir une politique de défaillance claire

Choisissez une politique et affichez-la dans l'UI :

• Tout-ou-rien : toute ligne invalide rejette l'import.
• Acceptation partielle : les lignes valides sont sauvegardées, les lignes invalides sont rapportées.
• Seuil : n'acceptez que si les échecs restent sous une limite fixée (par ex. 2 %)

Quelle que soit l'option, ajoutez une étape de staging. Parsez et validez dans une table de staging (ou stockage temporaire) d'abord. N'écrivez les enregistrements finaux qu'après que le lot ait passé les contrôles. Si vous autorisez l'acceptation partielle, stagez quand même, puis validez et committez uniquement les bonnes lignes en transactions contrôlées par batch.

Suivez le résultat par ligne pour pouvoir expliquer ce qui s'est passé sans deviner. Un petit ensemble de statuts suffit : success, failed, skipped (duplicate/empty), updated (enregistrement existant mis à jour).

Gérer soigneusement les lignes dépendantes

Les dépendances sont où les imports partiels deviennent dangereux.

Exemple : un CSV contient Clients et Commandes. Sauver une Commande sans son Client crée des données cassées.

Choisissez une règle et respectez-la :

• Exiger les parents en premier (échouer les lignes enfants si le parent manque)
• Import en deux passes (charger les parents puis les enfants)
• Quarantaine des dépendants (retenir les lignes enfants jusqu'à création du parent)

Quand vous reportez un « succès partiel », utilisez un langage simple : combien de lignes ont été sauvegardées, combien ne l'ont pas été, et si quelque chose a été ignoré ou mis à jour.

Rapports d'erreurs conviviaux et exploitables

Un import CSV peut être techniquement correct et pourtant sembler cassé si le rapport d'erreur est confus. Le but est de dire aux gens ce qui s'est passé, quoi corriger et comment retenter sans deviner.

Commencez par un résumé clair en haut : total de lignes, importées, ignorées, échouées. Si vous supportez les succès partiels, dites clairement que certaines lignes ont été sauvegardées.

Ensuite, affichez des détails ligne par ligne pointant vers le problème exact :

• Numéro de ligne (tel que l'utilisateur le voit dans le CSV)
• Nom de la colonne
• La valeur reçue
• Ce qui était attendu (format ou règle)
• Un court message actionnable

Rendez les messages spécifiques. « Valeur invalide » frustre. « La date doit être YYYY-MM-DD, reçu 3/7/24 » est corrigeable. Si un champ doit être l'une de quelques options, listez-les.

Évitez de divulguer des informations sensibles. Ne montrez pas de stack traces, d'erreurs SQL, d'IDs internes ou quoi que ce soit qui laisse voir l'implémentation. Mappez les échecs internes en messages sûrs comme : « Nous n'avons pas pu sauvegarder cette ligne. Réessayez, ou contactez le support si le problème persiste. »

Facilitez la ré‑importation. Conservez le même mapping de colonnes choisi initialement et proposez un fichier d'erreurs que l'utilisateur peut éditer et ré‑uploader (souvent les mêmes lignes originales plus une colonne « erreur »).

Étape par étape : un workflow d'import prêt pour la production

Un workflow qui tient face à de vraies données part du principe que quelque chose va mal : une date erronée, un champ requis manquant, une clé dupliquée ou un fichier plus grand que prévu.

Le workflow

1. Créer d'abord une session d'import. Quand l'utilisateur upload, créez un enregistrement de session d'import avec qui l'a uploadé, quand, le schéma/version attendu et un statut (queued/running/complete). Stockez le fichier brut dans un stockage durable et conservez son checksum pour pouvoir prouver ce qui a été traité.

2. Parser en streaming et stagez par lots. Parsez le CSV en streaming et écrivez les lignes dans une table de staging (ou un stockage temporaire) en petits lots (par ex. 500–2 000 lignes). Cela maintient la mémoire stable et fournit des points de contrôle sûrs.

3. Validez par ligne, enregistrez les erreurs, continuez. Pour chaque ligne, normalisez les valeurs (trim, parse des dates, mapping des enums), puis exécutez les règles ligne par ligne. Au lieu de lever une exception, créez un enregistrement d'erreur structuré lié à la session d'import et au numéro de ligne (champ, message, valeur originale).

4. Commettez seulement les lignes valides avec des upserts sûrs. Déplacez les lignes valides du staging vers les tables finales dans des transactions contrôlées. Utilisez des clés uniques et des upserts pour que les doublons n'engendrent pas d'enregistrements supplémentaires.

5. Générez un résumé utilisateur. Conservez les totaux : lignes traitées, importées, échouées, et les types d'erreurs les plus fréquents. Produisez un rapport d'erreurs filtrable et éditable.

Exemple : si un utilisateur importe 50 000 clients et que 312 lignes ont des emails invalides, vous importez quand même les 49 688 autres et retournez un rapport indiquant les numéros de ligne exacts et les corrections à faire.

Relancer sans ré‑uploader

Supportez le retry via la même session d'import : conservez le fichier original, appliquez les mêmes règles de validation et relancez après correction. Pour que cela soit fiable, la voie de retry doit utiliser les mêmes règles d'idempotence que la première exécution.

Garde-fous de performance et de fiabilité

Un import CSV est une tâche longue. Traitez-la comme telle. Si elle tourne dans une requête web normale, vous prenez le risque de timeouts, d'écrans gelés et d'écritures incomplètes. Placez les imports dans un job en arrière-plan et laissez l'UI interroger la progression pour garder l'app réactive.

Les mises à jour de progression doivent être réelles, pas « toujours en cours ». Suivez les étapes (upload, parse, validate, write, finalize) et incluez des compteurs comme lignes lues, acceptées, rejetées et temps passé.

Fixez des limites pour qu'un mauvais fichier ne monopolisent pas votre système :

• Durée maximale par import (échouez avec un message clair et isolez le travail partiel)
• Taille de batch limite (des batches plus petits réduisent les durées de lock et les pics mémoire)
• Nombre maximal d'erreurs avant arrêt (par ex. arrêter après 200 lignes erronées)
• Taille maximale de fichier et nombre maximal de colonnes (rejetez tôt)
• Concurrence maximale d'imports par workspace/compte

Le backpressure compte quand la base est plus lente que la lecture du fichier. Si les écritures prennent du retard, ralentissez le lecteur ou mettez le parsing en pause. Sinon la mémoire grimpe jusqu'au crash du worker et vous perdez l'état.

Rendez tout observable. Loggez l'ID d'import, qui l'a démarré, les métadonnées du fichier et les timings par étape. Ajoutez des métriques simples comme lignes par seconde et temps d'écriture en base. Quand quelqu'un dit « les imports ne fonctionnent pas », vous voulez des réponses rapides.

Prévoyez l'annulation. Si quelqu'un a uploadé le mauvais fichier, il doit pouvoir l'arrêter en sécurité. Faites des écritures en petites transactions et stagez les lignes entrantes. En cas d'annulation ou d'échec, supprimez les données de staging et marquez la session comme canceled pour qu'un retry démarre proprement.

Erreurs courantes qui causent des plantages ou des imports incorrects

La plupart des échecs en production ne viennent pas du « big data ». Ce sont de petites hypothèses qui ne tiennent que quand de vrais clients uploadent de vrais fichiers.

Une erreur fréquente est de faire confiance à la ligne d'entêtes. Les gens renommant des colonnes, ajoutent des espaces ou exportent depuis un autre système. Si vous ne vérifiez pas les colonnes requises et ne mappez pas explicitement, les valeurs peuvent glisser dans les mauvais champs et vous ne le remarquerez pas avant longtemps.

Les exports Excel ajoutent leurs propres pièges. Les zéros en tête d'IDs disparaissent, les grands nombres deviennent de la notation scientifique, et les dates peuvent arriver sous forme de texte, de numéros sériels ou de formats mixtes dans la même colonne. Si votre importeur devine les types, vous obtenez de la corruption silencieuse au lieu d'un message clair « Ligne 42 : date invalide ».

La variation de format de fichier est une autre source fréquente d'échecs : UTF-16, BOM, point-virgule au lieu de virgule, ou champs cités avec des sauts de ligne intégrés. Si votre parseur attend un format parfait, un fichier étrange peut bloquer le processus ou mélanger les lignes.

Quelques patterns qui causent systématiquement des plantages ou des imports incorrects :

• Une transaction géante pour des centaines de milliers de lignes (locks trop longs, timeouts, pics de ressources)
• Traiter chaque vide comme invalide alors que des champs sont optionnels
• Écrire directement sans checks d'idempotence (les retries créent des doublons)
• Retourner une erreur générique « Import failed » sans numéros de lignes ni noms de colonnes
• Mélanger validation et écritures si bien que les échecs partiels sont difficiles à récupérer

Exemple : un utilisateur importe 200k contacts, mais 50 lignes ont des dates erronées. Si votre code rollback tout et affiche une erreur vague, il va retenter, créer des doublons ou abandonner.

Liste de vérification rapide et prochaines étapes

Si vous voulez des imports qui ne plantent pas l'app, visez quelque chose de prévisible qui ne laisse jamais la base à moitié incorrecte.

Une checklist de production simple :

• Fixer des limites claires (max lignes, taille max, entêtes requises)
• Parser en streaming, pas en chargeant tout le fichier en mémoire
• Valider chaque ligne tôt (types, champs obligatoires, plages, vérifications de relations)
• Rendre idempotent (détection des doublons et retries sûrs)
• Stagez et commitez par petits lots pour contrôler ce qui est écrit

Décidez votre politique d'échecs partiels à l'avance et soyez cohérent. Beaucoup d'équipes choisissent « accepter les lignes valides, rejeter les lignes invalides », mais seulement si le résumé est clair et que les écritures sont sûres.

Un court plan de tests avant le déploiement :

• Un petit fichier propre
• Un fichier avec des lignes connues incorrectes (valeurs manquantes, dates erronées)
• Un gros fichier proche de vos limites max
• Un upload en double (même fichier deux fois)
• Un retry après interruption (arrêter en cours, puis reprendre)

Si vous avez hérité d'un importeur généré par IA qui plante sous charge ou produit des doublons, c'est souvent réparable sans réécrire toute l'application. FixMyMess (fixmymess.ai) se concentre sur diagnostiquer et réparer des bases de code générées par IA, y compris des flux d'import qui ont besoin de staging, d'idempotence et d'une validation plus sûre pour fonctionner en production.