# wp-cli qui se fige sans message pendant l’import d’une base volumineuse

> La commande reste immobile, le curseur clignote, aucun message d'erreur n'apparaît. Diagnostic d'un import de base volumineux qui semble bloqué sans jamais échouer franchement.

- Auteur : WordPress Développement
- Publié le : 2022-11-09
- Mis à jour le : 2022-11-09
- Catégorie : Outils & workflow
- URL : https://www.wpmoderne.fr/outils/wp-cli-fige-sans-message-import-base-volumineuse/

## L’essentiel

- Un blocage silencieux cache souvent un délai réseau ou un swap saturé
- Le découpage du fichier SQL permet d'isoler la ligne réellement fautive
- Surveiller la mémoire pendant l'import évite de conclure trop vite à un bogue

Le terminal reste figé. La commande `wp db import sauvegarde-production.sql` tourne depuis plus de vingt minutes, sans le moindre message, sans barre de progression, sans code de sortie. Sur un poste de développement standard, une base de cette taille s'importe habituellement en quelques minutes. Ce silence prolongé, sans échec ni succès, est plus inquiétant qu'une erreur franche : impossible de savoir si la commande travaille encore ou si elle a réellement cessé de progresser.

Cet article se concentre sur le diagnostic de ce blocage précis, au moment de l'import lui-même. Il ne traite pas de l'optimisation des requêtes une fois la base importée, sujet distinct qui suppose que l'import se termine avec succès.

## Symptôme : aucun message, aucune erreur, juste le silence

La commande `wp db import` délègue en réalité l'exécution du fichier SQL au client MySQL installé sur la machine, généralement via un appel système à `mysql`. Quand l'import se bloque sans message, la cause se situe rarement dans WP-CLI lui-même, mais plutôt dans la couche réseau entre le client et le serveur de base de données, ou dans les ressources système disponibles pendant l'opération.

## Diagnostic : isoler la cause réelle du blocage

Trois pistes doivent être vérifiées dans l'ordre, chacune éliminant ou confirmant une hypothèse avant de passer à la suivante.

### Première piste : le délai réseau entre le client et le serveur

Si le serveur MySQL est distant, un délai réseau anormalement élevé peut ralentir chaque requête d'insertion sans jamais provoquer d'erreur de coupure explicite. La commande suivante, exécutée en parallèle dans un autre terminal, permet de vérifier si des connexions restent bloquées côté serveur :

```
mysqladmin -u root -p processlist
```

> L'essentiel à retenir : Un blocage silencieux cache souvent un délai réseau ou un swap saturé ; Le découpage du fichier SQL permet d'isoler la ligne réellement fautive ; Surveiller la mémoire pendant l'import évite de conclure trop vite à un bogue

Une requête visible depuis plusieurs minutes dans l'état `Sending data` ou `Waiting for table metadata lock` confirme que l'import progresse, mais très lentement, plutôt qu'il ne soit réellement figé.

### Deuxième piste : le swap saturé sur la machine qui exécute l'import

Un fichier SQL volumineux, importé avec des réglages MySQL par défaut peu adaptés à ce volume, peut saturer la mémoire disponible et forcer le système à utiliser massivement le swap sur disque, ce qui ralentit chaque opération d'un facteur considérable sans jamais provoquer de plantage. La commande suivante affiche l'utilisation mémoire en temps réel pendant l'import :

```
watch -n 2 free -h
```

Une utilisation du swap qui grimpe continuellement pendant l'import, alors que la mémoire vive est déjà saturée, confirme cette seconde hypothèse.

### Troisième piste : une ligne SQL particulièrement volumineuse qui bloque le traitement

Certaines exportations contiennent des lignes d'insertion contenant des centaines de milliers de caractères, en particulier pour des tables stockant du contenu sérialisé volumineux. Si la limite `max_allowed_packet` du serveur MySQL est proche de cette taille sans être dépassée franchement, le traitement peut ralentir considérablement sans provoquer d'erreur immédiate.

## Correctif : ajuster les réglages et découper l'import

Une fois la cause identifiée, plusieurs ajustements permettent de débloquer la situation :

1. Augmenter explicitement `max_allowed_packet` dans la configuration MySQL, en particulier au-delà de la valeur par défaut souvent insuffisante pour des exports contenant du contenu sérialisé volumineux.
2. Découper le fichier SQL en plusieurs morceaux plus petits, à l'aide d'un outil dédié, pour importer table par table plutôt qu'en un seul bloc monolithique.
3. Exécuter l'import directement sur la machine hébergeant le serveur MySQL plutôt que depuis un poste distant, pour éliminer toute latence réseau du chemin critique.
4. Vérifier la mémoire disponible avant de lancer l'import, et fermer les processus non essentiels si le swap approche de la saturation.

```
wp db import --dbuser=root --dbpass=motdepasse \
  --dbname=production_locale sauvegarde-production.sql
```

## Prévention pour les prochains imports volumineux

Pour éviter de reproduire ce blocage silencieux sur un futur projet, il est utile de systématiser une vérification préalable de la taille du fichier à importer par rapport à la mémoire disponible, et d'ajuster `max_allowed_packet` par défaut dans les environnements de développement plutôt que de le découvrir au moment critique.

| Cause suspectée | Commande de vérification |
| --- | --- |
| Délai réseau | mysqladmin processlist |
| Swap saturé | watch free -h |
| Ligne SQL trop volumineuse | Vérification de max_allowed_packet |

> Le réflexe que nous appliquons désormais avant tout import volumineux : ouvrir un second terminal pour surveiller la mémoire et les connexions actives, plutôt que d'attendre passivement devant un curseur figé.

## En résumé

Un import `wp-cli` qui se fige sans message n'est presque jamais un bogue de l'outil lui-même : c'est un symptôme de ressources insuffisantes, réseau ou mémoire, face au volume traité. Surveiller ces ressources pendant l'opération, plutôt que d'attendre un message d'erreur qui ne viendra pas forcément, transforme un blocage angoissant en un diagnostic précis et rapide à corriger.