🚀 Guide de Migration vers MariaDB - Version Complète

📋 Vue d'ensemble

Ce guide vous accompagne pour migrer votre blog Django de SQLite vers MariaDB sur votre Raspberry Pi.

Prérequis

✅ Serveur MariaDB dans Docker sur le RPI (conteneur nommé mariadb)
✅ Accès réseau du Mac vers le RPI
✅ Python 3.x installé
✅ Fichier .env configuré

🎯 Étape 1 : Vérifications préliminaires

1.1 Vérifier l'environnement

# Rendre le script exécutable
chmod +x scripts/pre_migration_check.sh

# Lancer les vérifications
./scripts/pre_migration_check.sh

Ce script vérifie :

✅ Python et dépendances installées
✅ Configuration du fichier .env
✅ Connexion réseau vers MariaDB
✅ Présence de la base SQLite source

1.2 Installer les dépendances manquantes

Si des dépendances manquent :

pip3 install -r requirements.txt

Important: mysqlclient nécessite des outils de compilation :

Sur macOS :

brew install mysql-client pkg-config
export PKG_CONFIG_PATH="/opt/homebrew/opt/mysql-client/lib/pkgconfig"
pip3 install mysqlclient

🔧 Étape 2 : Configuration du serveur MariaDB

2.1 Vérifier que le conteneur Docker est démarré

Sur votre Raspberry Pi :

# Vérifier si le conteneur tourne
docker ps | grep mariadb

# Si non démarré, le démarrer
docker start mariadb

# Voir les logs
docker logs mariadb

2.2 Vérifier l'exposition du port

# Sur le RPI
docker port mariadb
# Devrait afficher : 3306/tcp -> 0.0.0.0:3306

Si le port n'est pas exposé, recréez le conteneur :

docker run -d \
  --name mariadb \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=votre_mot_de_passe_root \
  -v mariadb_data:/var/lib/mysql \
  --restart unless-stopped \
  mariadb:latest

2.3 Créer la base de données et l'utilisateur

Sur le Raspberry Pi :

# Se connecter à MariaDB
docker exec -it mariadb mysql -u root -p

Puis dans le shell MySQL :

-- Créer la base de données
CREATE DATABASE IF NOT EXISTS duhaz_blog 
  CHARACTER SET utf8mb4 
  COLLATE utf8mb4_unicode_ci;

-- Créer l'utilisateur
CREATE USER IF NOT EXISTS 'duhaz_user'@'%' 
  IDENTIFIED BY 'votre_mot_de_passe_securise';

-- Donner tous les droits sur la base
GRANT ALL PRIVILEGES ON duhaz_blog.* TO 'duhaz_user'@'%';

-- Appliquer les changements
FLUSH PRIVILEGES;

-- Vérifier
SHOW DATABASES;
SELECT User, Host FROM mysql.user WHERE User = 'duhaz_user';

-- Quitter
EXIT;

Note: 'duhaz_user'@'%' permet les connexions depuis n'importe quelle IP. Pour plus de sécurité, remplacez % par l'IP de votre Mac.

🌐 Étape 3 : Configuration réseau

3.1 Trouver l'IP de votre Raspberry Pi

Sur le RPI :

hostname -I
# Exemple de résultat : 192.168.1.100

3.2 Tester la connexion réseau

Depuis votre Mac :

# Test de ping
ping 192.168.1.100

# Test du port MariaDB
nc -zv 192.168.1.100 3306
# ou
telnet 192.168.1.100 3306

Si le port n'est pas accessible, vérifiez :

Le pare-feu du RPI : sudo ufw status
Le conteneur Docker expose bien le port
Votre réseau local autorise les connexions

⚙️ Étape 4 : Configuration du fichier .env

4.1 Éditer le fichier .env

Deux options pour DB_HOST :

Option A : Utiliser le nom du conteneur (si votre Mac fait partie du réseau Docker)

DB_ENGINE=mysql
DB_NAME=duhaz_blog
DB_USER=duhaz_user
DB_PASSWORD=votre_mot_de_passe_securise
DB_HOST=mariadb
DB_PORT=3306

Option B : Utiliser l'IP du RPI (recommandé pour développement depuis un autre machine)

DB_ENGINE=mysql
DB_NAME=duhaz_blog
DB_USER=duhaz_user
DB_PASSWORD=votre_mot_de_passe_securise
DB_HOST=192.168.1.100
DB_PORT=3306

4.2 Sécurité du mot de passe

⚠️ Important : N'utilisez JAMAIS de mots de passe simples en production !

Générer un mot de passe fort :

openssl rand -base64 32

🧪 Étape 5 : Test de connexion

5.1 Test direct avec Python

python3 scripts/test_mariadb_connection.py

Ce script teste :

Import du module MySQLdb
Connexion directe à MariaDB
Connexion via Django

5.2 Interpréter les résultats

✅ Succès :

✅ Tous les tests sont passés!

❌ Échec - Erreurs courantes :

Erreur	Solution
`ModuleNotFoundError: No module named 'MySQLdb'`	`pip3 install mysqlclient`
`Can't connect to MySQL server`	Vérifier que MariaDB est démarré et accessible
`Access denied for user`	Vérifier DB_USER et DB_PASSWORD dans .env
`Unknown database`	Créer la base avec les commandes SQL ci-dessus

📦 Étape 6 : Sauvegarde des données SQLite

6.1 Sauvegarde automatique

Le script de migration crée automatiquement un backup, mais vous pouvez aussi le faire manuellement :

# Créer le dossier de backup
mkdir -p backup

# Copier la base SQLite
cp db.sqlite3 backup/db.sqlite3.backup

# Export JSON des données
python3 manage.py dumpdata \
  --natural-foreign \
  --natural-primary \
  --exclude=contenttypes \
  --exclude=auth.permission \
  --indent=2 \
  --output=backup/sqlite_data.json

6.2 Vérifier le backup

# Taille du fichier
ls -lh backup/

# Nombre d'objets dans le JSON
grep -c '"model":' backup/sqlite_data.json

🚀 Étape 7 : Migration des données

7.1 Lancer la migration automatique

python3 scripts/migrate_to_mariadb.py

Le script effectue :

Export des données depuis SQLite
Pause pour que vous modifiiez le .env vers MariaDB
Import des données dans MariaDB
Vérification du nombre d'enregistrements

7.2 Processus étape par étape

Le script vous demandera :

⚠️ IMPORTANT: Maintenant, modifiez votre fichier .env
Changez DB_ENGINE de 'sqlite3' à 'mysql'
Appuyez sur Entrée quand c'est fait...

À ce moment :

Éditez le fichier .env
Changez DB_ENGINE=sqlite3 vers DB_ENGINE=mysql
Appuyez sur Entrée dans le terminal

7.3 Migration manuelle (si nécessaire)

Si vous préférez contrôler chaque étape :

# 1. Exporter depuis SQLite (avec DB_ENGINE=sqlite3)
python3 manage.py dumpdata \
  --natural-foreign \
  --natural-primary \
  --exclude=contenttypes \
  --exclude=auth.permission \
  --indent=2 \
  --output=backup/manual_export.json

# 2. Modifier le .env pour passer à MariaDB
# DB_ENGINE=mysql

# 3. Créer les tables dans MariaDB
python3 manage.py migrate --run-syncdb

# 4. Importer les données
python3 manage.py loaddata backup/manual_export.json

✅ Étape 8 : Vérification post-migration

8.1 Vérifier les données

# Lancer le shell Django
python3 manage.py shell

Dans le shell Python :

from django.contrib.auth.models import User
from blog.models import Article

# Compter les utilisateurs
print(f"Utilisateurs: {User.objects.count()}")

# Compter les articles
print(f"Articles: {Article.objects.count()}")

# Afficher le premier article
article = Article.objects.first()
if article:
    print(f"Premier article: {article.title}")

8.2 Tester l'interface admin

# Démarrer le serveur
python3 manage.py runserver

Accédez à : http://127.0.0.1:8000/admin/

Vérifiez :

✅ Connexion avec votre compte admin
✅ Liste des articles visible
✅ Modification d'un article fonctionne
✅ Création d'un nouvel article fonctionne

8.3 Tester le site public

Accédez à : http://127.0.0.1:8000/

Vérifiez :

✅ Les articles s'affichent
✅ Les images sont visibles
✅ Les liens fonctionnent
✅ La recherche fonctionne

🔧 Dépannage

Problème : Can't connect to MySQL server

Cause : Le serveur n'est pas accessible

Solutions :

# 1. Vérifier que le conteneur tourne
docker ps | grep mariadb

# 2. Voir les logs
docker logs mariadb

# 3. Tester la connexion réseau
telnet 192.168.1.100 3306

# 4. Vérifier le pare-feu
sudo ufw status

Problème : Access denied for user

Cause : Identifiants incorrects

Solutions :

# Vérifier les variables dans .env
cat .env | grep DB_

# Tester la connexion directement
docker exec -it mariadb mysql -u duhaz_user -p

Problème : Unknown database 'duhaz_blog'

Cause : La base n'existe pas

Solution :

# Se connecter en root
docker exec -it mariadb mysql -u root -p

# Créer la base
CREATE DATABASE duhaz_blog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Problème : Table already exists

Cause : Les migrations ont déjà été appliquées