Guide complet Docker MySQL : persistance et réplication maître-esclave

Le message d’erreur dans le terminal fait mal — deux semaines de données de test, envolées. Vous avez redémarré le conteneur MySQL l’après-midi, pensant que c’était une opération banale. Les données sont parties avec le conteneur.

Déployer MySQL avec Docker semble simple : docker run -e MYSQL_ROOT_PASSWORD=123456 mysql et c’est lancé. Puis viennent la perte de données au redémarrage, les montages de configuration qui ne s’appliquent pas, les applications locales qui ne se connectent pas, et la réplication maître-esclave en production — on ne mesure vraiment ces pièges qu’en les ayant vécus. Cet article couvre la persistance jusqu’à la réplication, en détaillant chaque configuration.

Bases du déploiement MySQL standalone avec Docker

Le démarrage le plus simple (et pourquoi il ne suffit pas)

Commençons par une idée reçue fréquente. Beaucoup lancent MySQL avec Docker ainsi :

docker run --name mysql-test -e MYSQL_ROOT_PASSWORD=123456 -d mysql:8.0

Le conteneur tourne, le statut est vert, vous pouvez manipuler la base — tout semble parfait. C’est une bombe à retardement.

Pourquoi ? Les conteneurs sont éphémères par nature. Supprimez le conteneur ou redémarrez-le un jour, et toutes les données disparaissent. MySQL stocke par défaut dans /var/lib/mysql à l’intérieur du conteneur. Supprimez le conteneur, ce répertoire disparaît avec.

La première fois que j’ai marché dans ce piège, j’ai cru que MySQL était en panne. Finalement, ce n’était pas MySQL — c’était l’absence totale de persistance des données.

Persistance des données : monter les volumes correctement

En bref, la persistance consiste à mapper le répertoire de données MySQL vers l’hôte : le conteneur peut tomber, les données restent.

Docker propose trois types de montage :

1. bind mount : mapping direct d’un répertoire hôte, par ex. /home/mysql/data
2. named volume : volume géré par Docker, sans se soucier de l’emplacement réel
3. tmpfs : stockage en RAM, perdu au redémarrage — quasi jamais utilisé

Depuis 2024, Docker recommande officiellement les named volumes ; les performances sont quasi équivalentes aux bind mounts. J’utilise les deux selon le contexte : named volume en développement pour la simplicité, bind mount en production pour faciliter les sauvegardes.

La commande complète :

docker run --name mysql-persistent \
  -e MYSQL_ROOT_PASSWORD=rootpwd123 \
  -p 3306:3306 \
  -v mysql-data:/var/lib/mysql \
  -d mysql:8.0

L’élément clé est -v mysql-data:/var/lib/mysql. mysql-data est le nom du volume (Docker le crée automatiquement), /var/lib/mysql le répertoire de données dans le conteneur.

Vérifions que la persistance fonctionne vraiment :

# Créer une base dans le conteneur
docker exec -it mysql-persistent mysql -uroot -prootpwd123 -e "CREATE DATABASE testdb;"

# Arrêter et supprimer le conteneur
docker stop mysql-persistent
docker rm mysql-persistent

# Relancer avec le même volume
docker run --name mysql-persistent \
  -e MYSQL_ROOT_PASSWORD=rootpwd123 \
  -p 3306:3306 \
  -v mysql-data:/var/lib/mysql \
  -d mysql:8.0

# Vérifier que testdb est toujours là
docker exec -it mysql-persistent mysql -uroot -prootpwd123 -e "SHOW DATABASES;"

Si testdb est toujours présente, vos données sont en sécurité. C’est rassurant.

Montage de configuration : personnaliser les paramètres MySQL

Persistance OK — étape suivante : comment modifier la configuration MySQL ?

Passer le jeu de caractères en utf8mb4 ou augmenter max_connections ? Sans montage de config, il faut modifier manuellement dans le conteneur à chaque fois — et recommencer après chaque redémarrage.

MySQL lit les fichiers supplémentaires dans /etc/mysql/conf.d/. Il suffit d’y monter votre my.cnf.

Créez d’abord le fichier sur l’hôte :

mkdir -p /home/mysql/conf
cat > /home/mysql/conf/my.cnf << 'EOF'
[mysqld]
# Jeu de caractères
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

# Connexions
max_connections=1000

# Plugin d'authentification (résout certains problèmes clients)
default_authentication_plugin=mysql_native_password

[client]
default-character-set=utf8mb4
EOF

Puis montez la configuration au démarrage :

docker run --name mysql-custom \
  -e MYSQL_ROOT_PASSWORD=rootpwd123 \
  -p 3306:3306 \
  -v /home/mysql/conf:/etc/mysql/conf.d \
  -v /home/mysql/data:/var/lib/mysql \
  -d mysql:8.0

Ici, configuration et répertoire de données sont montés simultanément.

Vérifier que la configuration est active :

docker exec -it mysql-custom mysql -uroot -prootpwd123 -e "SHOW VARIABLES LIKE 'character%';"

Si character_set_server vaut utf8mb4, la configuration est appliquée.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Résoudre les connexions externes

Le conteneur tourne, les données persistent, la config est montée — et votre application locale ne se connecte toujours pas :

ERROR 2003 (HY000): Can't connect to MySQL server on 'localhost' (Connection refused)

ou

ERROR 1045 (28000): Access denied for user 'root'@'172.17.0.1'

J’ai rencontré ces deux erreurs. Trouver la cause m’a pris du temps.

Problème 1 : Connection refused

Souvent un mauvais mapping de ports. Au démarrage, ajoutez impérativement -p 3306:3306 pour exposer le port 3306 du conteneur sur l’hôte.

Si le port 3306 est déjà occupé sur l’hôte (MySQL local installé), mappez un autre port :

-p 3307:3306  # hôte 3307, conteneur toujours 3306

Sur un serveur Linux, vérifiez aussi le pare-feu :

# CentOS/RHEL
sudo firewall-cmd --zone=public --add-port=3306/tcp --permanent
sudo firewall-cmd --reload

# Ubuntu
sudo ufw allow 3306/tcp

Problème 2 : Access denied

C’est un problème de permissions. L’utilisateur root créé par défaut n’accepte les connexions que depuis localhost, pas depuis des IP externes.

Solution : modifier le host de root en % (connexion depuis n’importe quelle IP) :

# Entrer dans le conteneur
docker exec -it mysql-custom mysql -uroot -prootpwd123

# Exécuter le SQL suivant
ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY 'rootpwd123';
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Deux points importants :

1. mysql_native_password est souvent plus compatible avec d’anciens clients MySQL
2. En production, ne laissez jamais root accessible depuis n’importe quelle IP — créez des utilisateurs dédiés avec restriction d’IP

Après cela, les applications externes devraient pouvoir se connecter.

Voilà pour les bases du déploiement MySQL standalone avec Docker.

Gérer proprement avec Docker Compose

Pourquoi Docker Compose est recommandé

Pour des tests locaux, les commandes docker run suffisent. En pratique, plusieurs frustrations apparaissent :

1. Commandes très longues à retrouver à chaque fois
2. Paramètres sujets aux erreurs, par ex. mauvais chemin de volume
3. Commandes de démarrage différentes dans l’équipe, configuration chaotique
4. Démarrer plusieurs conteneurs (MySQL + Redis + Nginx) un par un devient pénible

Docker Compose entre en jeu.

En bref : une longue ligne docker run devient un fichier YAML. Démarrage avec docker-compose up -d, arrêt avec docker-compose down, versionnement dans Git.

Un nouveau collègue demande « comment lancer MySQL ? » — vous lui envoyez le docker-compose.yml, il clone et démarre en une commande. Pratique.

Configuration MySQL standalone avec Docker Compose

Configuration complète avec explications :

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: mysql-standalone
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootpwd123
      MYSQL_DATABASE: myapp
      MYSQL_USER: appuser
      MYSQL_PASSWORD: apppwd123
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
      - ./conf/my.cnf:/etc/mysql/conf.d/my.cnf
      - ./logs:/var/log/mysql
    networks:
      - mysql-network
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-prootpwd123"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  mysql-data:

networks:
  mysql-network:
    driver: bridge

Points clés :

environment :

• MYSQL_ROOT_PASSWORD : mot de passe root, obligatoire
• MYSQL_DATABASE : base créée automatiquement au démarrage
• MYSQL_USER / MYSQL_PASSWORD : utilisateur standard (plus sûr que root)

volumes :

• mysql-data:/var/lib/mysql : persistance via named volume
• ./conf/my.cnf:/etc/mysql/conf.d/my.cnf : config avec chemin relatif
• ./logs:/var/log/mysql : journaux pour le diagnostic

restart: always : redémarrage automatique en cas de crash et après reboot serveur

healthcheck : ping régulier ; redémarrage si MySQL ne répond plus

networks : réseau dédié pour la communication entre conteneurs

Étapes :

1. Structure de répertoires :

mkdir -p mysql-docker/{conf,logs}
cd mysql-docker

2. Créer conf/my.cnf :

[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci
max_connections=1000
default_authentication_plugin=mysql_native_password

[client]
default-character-set=utf8mb4

3. Créer docker-compose.yml (configuration ci-dessus)

4. Démarrer :

docker-compose up -d

5. Vérifier l’état :

docker-compose ps

Exemple de sortie :

       Name                     Command                  State                 Ports
------------------------------------------------------------------------------------------------
mysql-standalone      docker-entrypoint.sh mysqld      Up (healthy)    0.0.0.0:3306->3306/tcp

Le statut (healthy) indique que le healthcheck a réussi.

6. Consulter les journaux :

docker-compose logs -f mysql

L’option -f suit les logs comme tail -f. Les problèmes de démarrage s’y trouvent généralement.

7. Arrêter et supprimer les conteneurs :

docker-compose down

Seuls les conteneurs sont supprimés, pas le volume — les données restent. Pour tout supprimer y compris les données :

docker-compose down -v  # Attention — supprime toutes les données

En développement local, j’utilise presque exclusivement Docker Compose : config écrite une fois, une commande pour démarrer et arrêter.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Réplication maître-esclave prête pour la production

Principe de la réplication maître-esclave

Pourquoi la réplication ?

MySQL standalone suffit pour les petits projets. Avec la montée en charge, les limites apparaissent. La réplication résout surtout :

1. Séparation lecture/écriture : le maître gère les écritures (INSERT, UPDATE, DELETE), les esclaves les lectures (SELECT). La plupart des applications lisent plus qu’elles n’écrivent — répartir les lectures sur plusieurs esclaves améliore les performances
2. Sauvegarde et haute disponibilité : si le maître tombe, les esclaves maintiennent au minimum le service de lecture

Le principe :

• Le maître active le binlog, journalisant toutes les modifications
• L’esclave se connecte au maître et lit le binlog
• Deux threads sur l’esclave : le thread IO récupère le binlog dans le relay log, le thread SQL exécute les instructions
• Les modifications du maître se synchronisent ainsi vers l’esclave

Sous Docker, l’essentiel :

1. Deux conteneurs avec des server-id différents
2. Binlog activé sur le maître
3. L’esclave se connecte au maître et démarre la réplication

Cela paraît complexe — avec Docker Compose, une fois la config en place, il suffit de démarrer et vérifier.

Configuration du nœud maître

Le maître nécessite : binlog, server-id, utilisateur de réplication.

1. Créer conf/master.cnf :

[mysqld]
# ID serveur unique, maître et esclave ne doivent pas être identiques
server-id=1

# Activer le journal binaire
log-bin=mysql-bin

# Format ROW enregistre chaque modification de ligne — plus sûr
binlog-format=ROW

# Jeu de caractères
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

# Optionnel : bases à répliquer (toutes par défaut)
# binlog-do-db=myapp

# Optionnel : bases à exclure
# binlog-ignore-db=mysql
# binlog-ignore-db=information_schema

2. docker-compose pour le maître :

version: '3.8'

services:
  mysql-master:
    image: mysql:8.0
    container_name: mysql-master
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootpwd123
      MYSQL_DATABASE: myapp
    ports:
      - "3306:3306"
    volumes:
      - master-data:/var/lib/mysql
      - ./conf/master.cnf:/etc/mysql/conf.d/master.cnf
      - ./logs/master:/var/log/mysql
    networks:
      - mysql-replication

volumes:
  master-data:

networks:
  mysql-replication:
    driver: bridge

3. Démarrer le maître :

docker-compose up -d mysql-master

4. Créer l’utilisateur de réplication :

docker exec -it mysql-master mysql -uroot -prootpwd123

SQL :

-- Utilisateur de réplication
CREATE USER 'repl'@'%' IDENTIFIED WITH mysql_native_password BY 'replpwd123';

-- Droits de réplication
GRANT REPLICATION SLAVE ON *.* TO 'repl'@'%';

FLUSH PRIVILEGES;

-- État du maître — noter File et Position
SHOW MASTER STATUS;

Exemple de sortie :

+------------------+----------+--------------+------------------+
| File             | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+------------------+----------+--------------+------------------+
| mysql-bin.000003 |      156 |              |                  |
+------------------+----------+--------------+------------------+

Important : notez File et Position pour la configuration de l’esclave.

Configuration du nœud esclave

Un peu plus simple que le maître.

1. Créer conf/slave.cnf :

[mysqld]
# server-id unique, différent du maître
server-id=2

# Relay log
relay-log=relay-bin

# Esclave en lecture seule (évite les écritures accidentelles)
read-only=1

# Jeu de caractères
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

2. Mettre à jour docker-compose.yml avec l’esclave :

version: '3.8'

services:
  mysql-master:
    image: mysql:8.0
    container_name: mysql-master
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootpwd123
      MYSQL_DATABASE: myapp
    ports:
      - "3306:3306"
    volumes:
      - master-data:/var/lib/mysql
      - ./conf/master.cnf:/etc/mysql/conf.d/master.cnf
      - ./logs/master:/var/log/mysql
    networks:
      - mysql-replication

  mysql-slave:
    image: mysql:8.0
    container_name: mysql-slave
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootpwd123
    ports:
      - "3307:3306"  # port hôte 3307 pour accéder à l'esclave
    volumes:
      - slave-data:/var/lib/mysql
      - ./conf/slave.cnf:/etc/mysql/conf.d/slave.cnf
      - ./logs/slave:/var/log/mysql
    networks:
      - mysql-replication
    depends_on:
      - mysql-master

volumes:
  master-data:
  slave-data:

networks:
  mysql-replication:
    driver: bridge

3. Démarrer l’esclave :

docker-compose up -d mysql-slave

4. Configurer la connexion de l’esclave au maître :

docker exec -it mysql-slave mysql -uroot -prootpwd123

SQL (remplacez File et Position par vos valeurs) :

-- Connexion au maître
CHANGE MASTER TO
  MASTER_HOST='mysql-master',           -- nom du conteneur maître (réseau Docker)
  MASTER_PORT=3306,
  MASTER_USER='repl',
  MASTER_PASSWORD='replpwd123',
  MASTER_LOG_FILE='mysql-bin.000003',   -- depuis SHOW MASTER STATUS
  MASTER_LOG_POS=156;                   -- depuis SHOW MASTER STATUS

START SLAVE;

SHOW SLAVE STATUS\G

Vérifier la synchronisation maître-esclave

Avec SHOW SLAVE STATUS\G, vérifiez ces champs :

Slave_IO_Running: Yes       # thread IO — doit être Yes
Slave_SQL_Running: Yes      # thread SQL — doit être Yes
Seconds_Behind_Master: 0    # retard en secondes, 0 = synchronisé
Last_IO_Error:              # vide = OK
Last_SQL_Error:             # vide = OK

Si Slave_IO_Running et Slave_SQL_Running valent tous deux Yes, la réplication fonctionne.

Test de synchronisation :

1. Données sur le maître :

docker exec -it mysql-master mysql -uroot -prootpwd123 -e "
USE myapp;
CREATE TABLE test_table (id INT PRIMARY KEY, name VARCHAR(50));
INSERT INTO test_table VALUES (1, 'test data');
"

2. Requête sur l’esclave :

docker exec -it mysql-slave mysql -uroot -prootpwd123 -e "
USE myapp;
SELECT * FROM test_table;
"

Si les données insérées apparaissent sur l’esclave, la synchronisation est opérationnelle.

Dépannage des problèmes courants

Problème 1 : Slave_IO_Running = No

Causes possibles :

• Réseau : conteneurs sur le même réseau Docker ? docker exec -it mysql-slave ping mysql-master
• Utilisateur repl : correctement créé sur le maître ?
• Fichier binlog ou position incorrects : relancer SHOW MASTER STATUS

Problème 2 : Slave_SQL_Running = No

Causes possibles :

• Erreur SQL : lire le champ Last_SQL_Error
• Incohérence maître-esclave : si le maître avait déjà des données avant la config, exporter d’abord vers l’esclave

Problème 3 : Seconds_Behind_Master reste élevé

Causes possibles :

• Esclave sous-dimensionné : vérifier CPU, RAM, I/O disque
• Forte charge d’écriture sur le maître : ajouter des esclaves
• Réseau : vérifier latence et bande passante

Réinitialiser l’esclave et reconfigurer :

-- sur l'esclave
STOP SLAVE;
RESET SLAVE;

-- puis réexécuter CHANGE MASTER TO et START SLAVE

Optimisation des performances et bonnes pratiques

Conseils de performance pour Docker MySQL

Beaucoup craignent une dégradation des performances avec Docker. Il y a quelques années c’était notable ; en 2024, l’impact est souvent inférieur à 5 %, quasi imperceptible en charge I/O.

Quelques optimisations utiles :

1. Type de volume

• named volume : géré par Docker, driver optimal — développement
• bind mount : répertoire hôte direct — production (sauvegarde, monitoring)

# named volume
volumes:
  - mysql-data:/var/lib/mysql

# bind mount
volumes:
  - /data/mysql:/var/lib/mysql

2. Mode réseau

Le réseau bridge suffit en général. Pour des performances maximales, essayez le mode host :

services:
  mysql:
    network_mode: "host"  # réseau hôte, légèrement plus performant

En mode host, le mapping ports n’est plus nécessaire ; MySQL écoute directement sur le port 3306 de l’hôte.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

3. Limites de ressources

En production, imposez des limites pour éviter que MySQL monopolise le serveur :

services:
  mysql:
    image: mysql:8.0
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          memory: 1G

Démarrer avec docker-compose --compatibility up ou en mode Docker Swarm.

4. Gestion des journaux

Sans limite, les journaux du conteneur peuvent saturer le disque :

services:
  mysql:
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"

Checklist production

Sécurité :

1. Pas de mots de passe par défaut ou faibles

# ❌ à éviter
MYSQL_ROOT_PASSWORD: 123456

# ✅ mot de passe fort ou Docker secrets
MYSQL_ROOT_PASSWORD: "Mx8#kL9$pQ2@vN4!"

2. Docker secrets pour les données sensibles

services:
  mysql:
    image: mysql:8.0
    secrets:
      - mysql_root_password
    environment:
      MYSQL_ROOT_PASSWORD_FILE: /run/secrets/mysql_root_password

secrets:
  mysql_root_password:
    file: ./secrets/mysql_root_password.txt

3. Restreindre l’accès réseau

networks:
  mysql-network:
    driver: bridge
    internal: true  # communication inter-conteneurs uniquement, pas d'accès externe

Pour un accès externe, passez par un conteneur applicatif proxy, pas directement MySQL.

Exploitation :

1. Sauvegardes régulières

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker exec mysql-master mysqldump -uroot -prootpwd123 --all-databases > backup_$DATE.sql

# ou archiver le répertoire de données
tar -czf mysql-data-backup_$DATE.tar.gz /data/mysql/

Automatisez quotidiennement, conservez au moins 7 jours de sauvegardes.

2. Healthcheck pour surveiller l’état

healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"]
  interval: 10s
  timeout: 5s
  retries: 3
  start_period: 30s

Combinez avec monitoring et alertes.

3. Monter les journaux séparément

volumes:
  - ./logs:/var/log/mysql

Haute disponibilité :

1. Au minimum un maître et un esclave — idéalement un maître et plusieurs esclaves

Pour les charges lecture-intensive, 3 à 5 esclaves pour répartir les lectures.

2. Load balancing pour la séparation lecture/écriture

MySQL Router, ProxySQL ou au niveau applicatif :

• Écritures → maître
• Lectures → esclaves (load balancing)

3. Tester régulièrement le basculement

Ne découvrez pas au moment de la panne que l’esclave ne peut pas prendre le relais :

-- sur l'esclave
STOP SLAVE;
RESET SLAVE ALL;
SET GLOBAL read_only=0;  -- promouvoir l'esclave en maître

En production, utilisez MHA, Orchestrator ou équivalent pour un basculement automatique.

Conclusion

Récapitulons l’essentiel de cet article.

Du déploiement MySQL standalone Docker à la persistance, au montage de configuration, à la résolution des connexions externes, à la gestion avec Docker Compose, jusqu’à la réplication maître-esclave production — ce guide couvre les scénarios de déploiement les plus courants.

Points clés :

1. La persistance est obligatoire — ne lancez plus MySQL dans un conteneur « nu »
2. Le montage de configuration pour le jeu de caractères, les connexions, etc.
3. Docker Compose pour centraliser la config et faciliter le travail d’équipe
4. La réplication est accessible si config et étapes sont correctes
5. Sécurité et sauvegardes en production — pas de mots de passe faibles, sauvegardes régulières

Toutes les configurations de cet article sont testées et prêtes à l’emploi — adaptez mots de passe et ports, puis lancez.

Si c’est votre premier déploiement MySQL avec Docker, commencez par le standalone : maîtrisez persistance et montage de config avant la réplication. Étape par étape.

En cas de problème, consultez les journaux — la cause s’y trouve généralement. Si vous êtes bloqué, échangez en commentaires, je répondrai.

MySQL avec Docker est bien plus simple que l’installation traditionnelle : configurez une fois, exécutez partout.