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
ou11.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 à :bashAnalysez attentivement le bas du fichier : les messages d’erreur y indiquent souvent directement la cause du problème.
/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
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.
- Vérifiez via l’interface ServBay ou la commande
- 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
.
- Le chemin utilisé par le client diffère de celui défini côté serveur dans le fichier de configuration (
- 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.
- 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
- 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.
- 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
Solution alternative (forcer l’utilisation du réseau) :
- Essayez de vous connecter à l’adresse IP
127.0.0.1
plutôt quelocalhost
: cela force l’usage de TCP/IP, pas du socket Unix. Si cela fonctionne, le problème est bien lié au socket.bashmysql -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)bashsudo /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
dansmy.cnf
. Si127.0.0.1
oulocalhost
est configuré, seules les connexions locales sont autorisées. Pour permettre des accès distants, configurez0.0.0.0
(toutes les adresses) ou une IP spécifique et ouvrez le port dans le pare-feu.
- Vérifiez l’option
- Problème de résolution
localhost
:- Assurez-vous que
localhost
est bien résolu vers127.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éelocalhost
. - Certains logiciels de proxy peuvent interférer avec le trafic local : essayez de désactiver temporairement tout proxy.
- Assurez-vous que
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 :bashL’utilisateur MariaDB/MySQL doit avoir lecture, écriture et exécution nécessaires.
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 du processus (souvent un utilisateur système ServBay, comme
- 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
etREVOKE
pour modifier les droits, ou créez un nouvel utilisateur avec les autorisations nécessaires.
- Connectez-vous en root :
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 deslow_query_log_file
dansmy.cnf
. Analysez ensuite le fichier généré après redémarrage. - Utilisez
EXPLAIN
: AjoutezEXPLAIN
devant vos requêtes soupçonnées d’être lentes pour comprendre leur plan d’exécution.sqlEXPLAIN 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.
- Activer le journal des requêtes lentes : Configurez
- 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 :sqlAttention : créer des index augmente l’occupation disque et impacte les insertions.
CREATE INDEX idx_column_name ON your_table_name(column_name);
1
- 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
- Ajustez
- 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.bashRemarque :# 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
1
2
3
4--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
) :- Sauvegardez impérativement les fichiers du répertoire de données avant tout ! Copiez
/Applications/ServBay/db/mariadb/<version>/
ailleurs. - Éditez
/Applications/ServBay/etc/mariadb/<version>/my.cnf
. - Dans la section
[mysqld]
, ajoutez :innodb_force_recovery = N
(N démarrant à 1, puis jusqu’à 6 au besoin ; augmentez le niveau prudemment). - Redémarrez MariaDB/MySQL :
servbayctl start mariadb <version>
. - Si le serveur démarre (en lecture seule ou limité), sauvegardez tout de suite avec
mysqldump
:bashVérifiez bien que le fichier de sauvegarde est lisible et complet.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 - Coupez le serveur :
servbayctl stop mariadb <version>
- Éditez
my.cnf
pour retirer ou commenterinnodb_force_recovery
- 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.
- Sauvegardez impérativement les fichiers du répertoire de données avant tout ! Copiez
- 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 :bashRemarque :
# 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>
1
2
3
4
5<version>
à remplacer par le bon numéro de version.
- Exemple d’import :
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 avecless
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.
- Vérifiez la taille (
- 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 :sqlAttention : désactiver les checks peut entraîner des incohérences : à utiliser lors de l’import uniquement.
-- 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 - 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) :
# 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>
2
3
4
5
6
7
8
9
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
2
3
4
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
2
3
4
5
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 !bashVérifiez bien la génération et la taille du fichier !
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
- Ouvrez
- **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 ligneinnodb_force_recovery
...
- Stoppez le paquet :