Guide de dépannage des paquets ServBay MariaDB/MySQL

Vue d’ensemble

MariaDB et MySQL sont des systèmes de gestion de base de données relationnelles open source leader, largement utilisés dans divers scénarios web et métiers. ServBay intègre plusieurs versions des paquets MariaDB/MySQL sous macOS, offrant aux développeurs un environnement de base de données local pratique et efficace. Bien qu’elles soient réputées pour leur stabilité, il peut toujours arriver que les paquets ne démarrent pas, que la connexion échoue ou que les performances diminuent lors du développement ou de l’exécution.

Ce guide vise à aider les utilisateurs de ServBay à diagnostiquer et résoudre les problèmes courants liés aux paquets MariaDB/MySQL. Nous couvrons les problèmes typiques, les étapes de diagnostic et les solutions concrètes, avec des chemins et commandes spécifiques à l’environnement ServBay.

Remarques importantes :

Avant d’effectuer toute opération susceptible de modifier la configuration ou les données, pensez impérativement à sauvegarder votre base de données ! ServBay propose une fonction de sauvegarde intégrée que nous recommandons d’utiliser régulièrement.
Les exemples de commandes et de chemins contiennent des numéros de version spécifiques (comme 11.3 ou 11.5). Merci de remplacer ces numéros par la version exacte de MariaDB/MySQL que vous utilisez dans ServBay. Vous pouvez consulter les versions installées et activées via l’interface de l’application ServBay.
Dans les exemples de commandes, <username>, <database>, <your_backup.sql>, etc. sont des espaces réservés à remplacer par votre nom d’utilisateur, nom de base de données, nom du fichier de sauvegarde, etc.
Ce guide se base sur macOS pour l’ensemble de ses explications.

Étapes générales de diagnostic préliminaire

Avant d’entrer dans un diagnostic poussé, il est recommandé de vérifier les éléments suivants :

Vérifiez l’état du paquet ServBay : Ouvrez l’interface de ServBay et assurez-vous que la version de MariaDB/MySQL concernée est activée et bien “En cours d’exécution”. Vous pouvez aussi vérifier en ligne de commande :
bash
```
servbayctl status mariadb <version>
# Exemple : statut de MariaDB 11.3
servbayctl status mariadb 11.3
```
1
2
3
Consultez les journaux de l’application ServBay : Parfois, ServBay enregistre les erreurs lors du démarrage ou de la gestion des paquets. Consultez la section journal de l’interface ou le fichier de log principal de ServBay.
Consultez le journal d’erreurs MariaDB/MySQL : C’est l’étape la plus cruciale pour diagnostiquer les problèmes de démarrage ou d’exécution. Le fichier log se trouve généralement à :
bash
```
/Applications/ServBay/logs/mariadb/<version>/<version>.err
# Exemple : consulter les 50 dernières lignes du journal d’erreurs MariaDB 11.3
tail -n 50 /Applications/ServBay/logs/mariadb/11.3/11.3.err
```
1
2
3
Analysez attentivement le bas du fichier : les messages d’erreur y indiquent souvent directement la cause du problème.

Problèmes courants & solutions

1. Erreur de connexion : `SQLSTATE[HY000] [2002] No such file or directory`

Cette erreur signifie généralement que le client ne parvient pas à se connecter au serveur MariaDB/MySQL via le fichier Unix socket. Sous macOS, le socket Unix est un mécanisme de communication inter-processus local, souvent privilégié pour ses performances. Lorsque l’outil ou l’application ne trouve pas le fichier socket attendu, l’erreur apparaît.

Causes possibles & solutions :

Le paquet MariaDB/MySQL n’est pas lancé :
- Vérifiez via l’interface ServBay ou la commande servbayctl status mariadb <version>.
- Si besoin, démarrez le paquet : servbayctl start mariadb <version>, puis consultez le log d’erreurs (.err) pour comprendre la raison d’un éventuel échec.
Chemin du fichier socket incorrect :
- Le chemin utilisé par le client diffère de celui défini côté serveur dans le fichier de configuration (my.cnf).
- Vérifiez l’option socket dans /Applications/ServBay/etc/mariadb/<version>/my.cnf.
- Assurez-vous que l’application ou le client utilisent ce même chemin, ou bien que le chemin par défaut de ServBay est utilisé. Par défaut, il se trouve dans /Applications/ServBay/tmp/ ou /tmp/, par exemple /Applications/ServBay/tmp/mysql.sock ou /tmp/mysql.sock.
Problème avec les réglages par défaut de ServBay :
- Dans “Paramètres” > “SQL par défaut” de ServBay, vérifiez que la bonne version MariaDB/MySQL est sélectionnée. Certains clients (comme l’outil en ligne de commande mysql lorsqu’aucune option -S ou -h n’est précisée) chercheront le socket par défaut.
Problèmes de droits d’accès :
- L’utilisateur du processus MariaDB/MySQL ou du client n’a pas les droits en lecture/écriture suffisants sur le dossier du socket. ServBay gère normalement ces droits, mais si les permissions de /Applications/ServBay/tmp/ ou /tmp/ ont été modifiées manuellement, cela peut poser problème.

Solution alternative (forcer l’utilisation du réseau) :

Essayez de vous connecter à l’adresse IP 127.0.0.1 plutôt que localhost : cela force l’usage de TCP/IP, pas du socket Unix. Si cela fonctionne, le problème est bien lié au socket.
bash
```
mysql -u <username> -p -h 127.0.0.1 -P 3306
```
1

2. Erreurs de connexion via le réseau (`Connection refused`, `Can't connect to MySQL server`)

Ces erreurs indiquent généralement que le client ne peut pas accéder au serveur MariaDB/MySQL via le protocole TCP/IP.

Causes possibles & solutions :

Le paquet MariaDB/MySQL n’est pas lancé : (voir plus haut : statut du paquet, journal .err)
Port occupé par un autre processus :
- Vérifiez que le port d’écoute (par défaut 3306) n’est pas utilisé par un autre logiciel.
- Vérifiez l’occupation du port :
  bash
```
lsof -i :3306
# ou
netstat -anv | grep LISTEN | grep 3306
```
  1
  2
  3
- Si le port est pris, arrêtez le processus concerné ou modifiez le port dans le fichier /Applications/ServBay/etc/mariadb/<version>/my.cnf, puis redémarrez MariaDB/MySQL.
Pare-feu bloquant la connexion :
- Le pare-feu macOS (ou un pare-feu tiers) peut bloquer le port 3306.
- Consultez Préférences Système > Réseau > Pare-feu.
- Pour autoriser le processus mysqld à passer au travers du pare-feu : (chemin à adapter à votre installation ServBay)
  bash
```
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/ServBay/bin/mariadb/<version>/bin/mysqld
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/ServBay/bin/mariadb/<version>/bin/mysqld
```
  1
  2
Mauvaise configuration (bind-address) :
- Vérifiez l’option bind-address dans my.cnf. Si 127.0.0.1 ou localhost est configuré, seules les connexions locales sont autorisées. Pour permettre des accès distants, configurez 0.0.0.0 (toutes les adresses) ou une IP spécifique et ouvrez le port dans le pare-feu.
Problème de résolution localhost :
- Assurez-vous que localhost est bien résolu vers 127.0.0.1 (IPv4) et ::1 (IPv6).
- Testez avec ping localhost dans le terminal.
- Vérifiez que votre fichier /etc/hosts n’a pas été modifié et contient bien une entrée localhost.
- Certains logiciels de proxy peuvent interférer avec le trafic local : essayez de désactiver temporairement tout proxy.

3. Le paquet MariaDB/MySQL ne démarre pas

Causes possibles & solutions :

Consultez le journal d’erreurs (le plus important !) : Comme vu plus haut, consultez /Applications/ServBay/logs/mariadb/<version>/<version>.err pour identifier le motif précis du blocage au démarrage.
Erreur dans le fichier de configuration :
- /Applications/ServBay/etc/mariadb/<version>/my.cnf contient éventuellement des erreurs de syntaxe ou des paramètres incorrects.
- Vérifiez le fichier de configuration : (adaptez le chemin de mysqld selon votre version)
  bash
```
# Exemple de commande
/Applications/ServBay/bin/mariadb/<version>/bin/mysqld --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf --validate-config
```
  1
  2
Port occupé : (voir ci-dessus)
Espace disque insuffisant : La partition contenant /Applications/ServBay/db/mariadb/<version>/ ou /Applications/ServBay/logs/mariadb/<version>/ doit avoir assez d’espace libre.
Problème de droits d’accès :
- L’utilisateur du processus (souvent un utilisateur système ServBay, comme _mysql) n’a pas suffisamment de droits. Cela peut arriver si vous avez modifié manuellement les permissions dans /Applications/ServBay.
- Vérifiez les permissions :
  bash
```
ls -ld /Applications/ServBay/db/mariadb/<version>
ls -l /Applications/ServBay/etc/mariadb/<version>/my.cnf
ls -ld /Applications/ServBay/logs/mariadb/<version>
```
  1
  2
  3
  L’utilisateur MariaDB/MySQL doit avoir lecture, écriture et exécution nécessaires.
Fichiers de données corrompus : (voir plus bas la partie “Crash base de données ou corruption des données”)

Après correction :

Redémarrez le paquet : servbayctl restart mariadb <version>

4. Problème de droits ou d’authentification

Après une connexion au serveur de base de données, vous pouvez rencontrer des erreurs dues à un identifiant, un mot de passe ou des droits inadéquats (Access denied).

Causes possibles & solutions :

Nom d’utilisateur ou mot de passe incorrect : Vérifiez soigneusement les identifiants utilisés. ServBay permet de réinitialiser facilement le mot de passe root si besoin.
Restriction d’hôte : Certains comptes sont restreints à un hôte précis ('<username>'@'localhost'). Une tentative avec '<username>'@'127.0.0.1' échouera, et inversement. % autorise la connexion depuis n’importe quel hôte.
Droits insuffisants : L’utilisateur n’a peut-être pas les droits nécessaires sur la base ou les opérations (SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, etc.).
Vérifiez les privilèges :
- Connectez-vous en root :
  bash
```
mysql -u root -p
```
  1
- Affichez les droits d’un utilisateur :
  sql
```
SHOW GRANTS FOR '<username>'@'<hostname>';
-- Exemple : droits de 'webapp' sur 'localhost'
SHOW GRANTS FOR 'webapp'@'localhost';
-- Droits de 'admin' depuis n’importe où :
SHOW GRANTS FOR 'admin'@'%';
```
  1
  2
  3
  4
  5
- Utilisez les commandes GRANT et REVOKE pour modifier les droits, ou créez un nouvel utilisateur avec les autorisations nécessaires.

5. Problèmes de performances

La baisse de performances peut impacter significativement la réactivité de vos applications.

Causes possibles & solutions :

Requêtes lentes : Requêtes inefficaces, index manquants, mauvais plan d’exécution.
- Activer le journal des requêtes lentes : Configurez slow_query_log = 1, long_query_time = 1 et le chemin de slow_query_log_file dans my.cnf. Analysez ensuite le fichier généré après redémarrage.
- Utilisez EXPLAIN : Ajoutez EXPLAIN devant vos requêtes soupçonnées d’être lentes pour comprendre leur plan d’exécution.
  sql
```
EXPLAIN SELECT * FROM your_table_name WHERE column_name = 'value';
```
  1
- Optimisez vos requêtes : Réécrivez-les, évitez SELECT *, privilégiez les indexables dans WHERE et JOIN.
Index manquants ou mal conçus : Les colonnes utilisées pour WHERE, ORDER BY ou GROUP BY doivent être indexées si nécessaire.
- Analysez la structure des tables et requêtes courantes.
- Créez les index appropriés :
  sql
```
CREATE INDEX idx_column_name ON your_table_name(column_name);
```
  1
  Attention : créer des index augmente l’occupation disque et impacte les insertions.
Paramétrage du cache inadéquat : Valeurs inadaptées pour innodb_buffer_pool_size, key_buffer_size (MyISAM).
- Ajustez my.cnf selon les besoins : Pour un usage majoritairement InnoDB, réservez 50-70% de la RAM de la machine à innodb_buffer_pool_size (à ajuster selon utilisation).
  ini
```
[mysqld]
# Exemple : à ajuster, unités = K, M, G ou octets
innodb_buffer_pool_size = 2G
# Si vous utilisez beaucoup MyISAM :
# key_buffer_size = 256M
```
  1
  2
  3
  4
  5
Limites matérielles : Surveillance de la charge CPU, RAM, E/S disque : utilisez l’"Activity Monitor" (Moniteur d’activité) de macOS ou top/htop en terminal.

6. Crash base de données ou corruption des données

Serveur qui ne démarre plus, crash répétitifs ou anomalies d’accès, souvent lié à la corruption de fichiers de données.

Causes possibles & solutions :

Consultez impérativement le log d’erreurs : /Applications/ServBay/logs/mariadb/<version>/<version>.err livre souvent la cause (erreurs InnoDB, disque, mémoire, etc.).
Défaut matériel : Erreurs disque, mémoire, etc. Utilisez les outils Apple de diagnostic matériel.
Bug logiciel ou conflit : Certaines versions spécifiques peuvent comporter des bugs ou conflit avec d’autres logiciels présents.
Erreur de configuration : Un mauvais paramètre dans my.cnf peut causer de grossiers dysfonctionnements.
Arrêts forcés : Fermeture brutale de MariaDB/MySQL ou de ServBay : fichiers potentiellement dans un état incohérent.

Procédure de récupération :

Tentez un redémarrage en douceur : Via l’interface ou servbayctl restart mariadb <version>. Parfois, la base arrive à s’auto-réparer.

Utilisez mysqlcheck pour vérifier et réparer les tables : Outil efficace pour les tables MyISAM.

bash

# Vérification de toutes les tables
mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --check --all-databases
# Réparation automatique si besoin (MyISAM)
# mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --auto-repair --check --all-databases

Remarque : --auto-repair fonctionne essentiellement sur MyISAM. InnoDB nécessite souvent des opérations manuelles détaillées (voir ci-après "récupération forcée").

Forcer la récupération InnoDB (innodb_force_recovery) :
1. Sauvegardez impérativement les fichiers du répertoire de données avant tout ! Copiez /Applications/ServBay/db/mariadb/<version>/ ailleurs.
2. Éditez /Applications/ServBay/etc/mariadb/<version>/my.cnf.
3. Dans la section [mysqld], ajoutez : innodb_force_recovery = N (N démarrant à 1, puis jusqu’à 6 au besoin ; augmentez le niveau prudemment).
4. Redémarrez MariaDB/MySQL : servbayctl start mariadb <version>.
5. Si le serveur démarre (en lecture seule ou limité), sauvegardez tout de suite avec mysqldump :
  bash
```
mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --all-databases --routines --triggers --events > /path/to/your_emergency_backup.sql
```
  1
  Vérifiez bien que le fichier de sauvegarde est lisible et complet.
6. Coupez le serveur : servbayctl stop mariadb <version>
7. Éditez my.cnf pour retirer ou commenter innodb_force_recovery
8. Procédez à une réinitialisation ou un import : Recréez un répertoire de données vierge (en renommant ou supprimant l’ancienne base corrompue) et importez la sauvegarde fraîchement réalisée.

Restauration depuis une sauvegarde antérieure : Si la base reste irrécupérable ou incohérente, restaurez depuis une sauvegarde fiable (habituellement dans /Applications/ServBay/backup/mariadb/<version>/ si via la fonction interne de ServBay).

Exemple d’import :

bash

# Assurez-vous que la base <target_database_name> existe
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"

# Importez la sauvegarde
mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

Remarque : <version> à remplacer par le bon numéro de version.

7. Problèmes de sauvegarde et de restauration

Lors de la sauvegarde via l’outil interne de ServBay ou avec mysqldump, ou lors de la restauration, il peut y avoir des problèmes.

Causes possibles & solutions :

Fichier de sauvegarde incomplet ou corrompu :
- Vérifiez la taille (ls -lh /path/to/your_backup.sql) et ouvrez le fichier dans un éditeur ou avec less pour contrôler sa validité.
- En cas de backup manuel via mysqldump, surveillez les messages d’erreur. Pour les sauvegardes via ServBay, consultez les logs intégrés.
Commande de restauration incorrecte :
- Utilisation d’un mauvais nom d’utilisateur, mot de passe ou base cible.
- Droits insuffisants.
- Problème de syntaxe SQL (dû à des différences de version ou d’édition, ex : migration MySQL vers MariaDB).
Problèmes de contraintes de clés étrangères : Lors de l’import, l’ordre de création des tables peut provoquer l’échec de contraintes. On peut temporairement désactiver les vérifications avant et les réactiver après :
sql
```
-- Avant l’import
SET foreign_key_checks = 0;
-- Import du fichier
source /path/to/your_backup.sql; -- depuis le client mysql
-- ou : mysql ... < /path/to/your_backup.sql

-- Après import
SET foreign_key_checks = 1;
```
1
2
3
4
5
6
7
8
Attention : désactiver les checks peut entraîner des incohérences : à utiliser lors de l’import uniquement.
Problèmes d'encodage ou de collation : Le jeu de caractères ou la collation définis dans le fichier de sauvegarde peuvent ne pas correspondre à ceux de la base de destination, causant des erreurs ou des caractères illisibles. Vérifiez que les paramètres (utf8mb4 par exemple) coïncident.

Exemple de restauration correcte (ligne de commande) :

bash

# Si la sauvegarde concerne une base précise
# Assurez-vous que la base <target_database_name> existe
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"

# Import avec les bons paramètres
mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

# Si la sauvegarde couvre toutes les bases (--all-databases), inutile de préciser le nom de base
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

Remarque : Remplacez <version> par la version appropriée. Les sauvegardes générées par ServBay sont généralement prêtes à être restaurées sans manipulation supplémentaire.

8. Bug spécifique : Échec de démarrage d’InnoDB sous MariaDB 11.5.1 (`ib_logfile0 was not found` / `Missing FILE_CHECKPOINT`)

Ce bug majeur touche MariaDB 11.5.1 et peut empêcher le moteur InnoDB de s’initialiser ou de restaurer ses fichiers de journal, bloquant le démarrage de la base.

Messages courants du journal d’erreur :

Dans /Applications/ServBay/logs/mariadb/11.5/11.5.err on trouve typiquement :

[ERROR] InnoDB: File /Applications/ServBay/db/mariadb/11.5/ib_logfile0 was not found
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB

ou :

[ERROR] InnoDB: Missing FILE_CHECKPOINT(xxxxx) at xxxxx
[ERROR] InnoDB: Log scan aborted at LSN xxxxx
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB

Ils indiquent qu’InnoDB ne trouve pas ou ne parvient pas à traiter ses journaux, donc il échoue à s’initialiser.

Procédure de récupération (sauvegarde/ exportation obligatoires) :

Bug reconnu et difficile à corriger : la méthode recommandée est de forcer le démarrage pour exporter vos données, puis de migrer vers une version stable.

Tentez une récupération forcée pour sauvegarder (manœuvre à risque !) :
- Ouvrez /Applications/ServBay/etc/mariadb/11.5/my.cnf.
- Ajoutez sous [mysqld] : innodb_force_recovery = 6
- Essayez de démarrer MariaDB 11.5 par ServBay ou en ligne de commande : servbayctl start mariadb 11.5
- Si le serveur démarre (même en mode dégradé), faites aussitôt un dump complet !
  bash
```
mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/11.5/my.cnf -u root -p --all-databases --routines --triggers --events > /Applications/ServBay/backup/mariadb/11.5/mariadb_11.5_emergency_backup.sql
```
  1
  Vérifiez bien la génération et la taille du fichier !
**Arrêtez MariaDB 11.5 et gérez le répertoire de données :
- Stoppez le paquet : servbayctl stop mariadb 11.5
- Éditez le fichier my.cnf et supprimez ou commentez la ligne innodb_force_recovery...

Guide de dépannage des paquets ServBay MariaDB/MySQL ​

Vue d’ensemble ​

Étapes générales de diagnostic préliminaire ​

Problèmes courants & solutions ​

1. Erreur de connexion : SQLSTATE[HY000] [2002] No such file or directory ​

2. Erreurs de connexion via le réseau (Connection refused, Can't connect to MySQL server) ​

3. Le paquet MariaDB/MySQL ne démarre pas ​

4. Problème de droits ou d’authentification ​

5. Problèmes de performances ​

6. Crash base de données ou corruption des données ​

7. Problèmes de sauvegarde et de restauration ​

8. Bug spécifique : Échec de démarrage d’InnoDB sous MariaDB 11.5.1 (ib_logfile0 was not found / Missing FILE_CHECKPOINT) ​

Guide de dépannage des paquets ServBay MariaDB/MySQL

Vue d’ensemble

Étapes générales de diagnostic préliminaire

Problèmes courants & solutions

1. Erreur de connexion : `SQLSTATE[HY000] [2002] No such file or directory`

2. Erreurs de connexion via le réseau (`Connection refused`, `Can't connect to MySQL server`)

3. Le paquet MariaDB/MySQL ne démarre pas

4. Problème de droits ou d’authentification

5. Problèmes de performances

6. Crash base de données ou corruption des données

7. Problèmes de sauvegarde et de restauration

8. Bug spécifique : Échec de démarrage d’InnoDB sous MariaDB 11.5.1 (`ib_logfile0 was not found` / `Missing FILE_CHECKPOINT`)