# 🚀 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

```bash
# 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 :

```bash
pip3 install -r requirements.txt
```

**Important**: `mysqlclient` nécessite des outils de compilation :

**Sur macOS :**
```bash
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** :

```bash
# 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

```bash
# 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 :

```bash
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** :

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

Puis dans le shell MySQL :

```sql
-- 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** :

```bash
hostname -I
# Exemple de résultat : 192.168.1.100
```

### 3.2 Tester la connexion réseau

Depuis votre **Mac** :

```bash
# 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)
```env
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)
```env
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 :
```bash
openssl rand -base64 32
```

---

## 🧪 Étape 5 : Test de connexion

### 5.1 Test direct avec Python

```bash
python3 scripts/test_mariadb_connection.py
```

Ce script teste :
1. Import du module MySQLdb
2. Connexion directe à MariaDB
3. 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 :

```bash
# 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

```bash
# 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

```bash
python3 scripts/migrate_to_mariadb.py
```

Le script effectue :
1. **Export** des données depuis SQLite
2. **Pause** pour que vous modifiiez le .env vers MariaDB
3. **Import** des données dans MariaDB
4. **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 :
1. Éditez le fichier `.env`
2. Changez `DB_ENGINE=sqlite3` vers `DB_ENGINE=mysql`
3. Appuyez sur Entrée dans le terminal

### 7.3 Migration manuelle (si nécessaire)

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

```bash
# 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

```bash
# Lancer le shell Django
python3 manage.py shell
```

Dans le shell Python :

```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

```bash
# 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** :
```bash
# 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** :
```bash
# 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** :
```bash
# 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

**Solution** :
```bash
# Supprimer toutes les tables et recommencer
docker exec -it mariadb mysql -u root -p

DROP DATABASE duhaz_blog;
CREATE DATABASE duhaz_blog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Relancer la migration
python3 scripts/migrate_to_mariadb.py
```

### Problème : ImportError: No module named 'MySQLdb'

**Cause** : mysqlclient n'est pas installé

**Solution macOS** :
```bash
# Installer les dépendances système
brew install mysql-client pkg-config

# Configurer PKG_CONFIG_PATH
export PKG_CONFIG_PATH="/opt/homebrew/opt/mysql-client/lib/pkgconfig"

# Installer mysqlclient
pip3 install mysqlclient
```

---

## 📊 Comparaison SQLite vs MariaDB

| Caractéristique | SQLite | MariaDB |
|----------------|--------|---------|
| **Performance lecture** | Excellente | Très bonne |
| **Performance écriture** | Bonne | Excellente |
| **Concurrence** | Limitée | Excellente |
| **Backup** | Copie de fichier | mysqldump |
| **Taille max** | ~140 To | Pratiquement illimitée |
| **Adapté pour** | Dev, petits sites | Production, sites moyens/grands |

---

## 🔒 Sécurité en production

Avant de déployer en production, modifiez `.env` :

```env
# Désactiver le mode debug
DEBUG=False

# Limiter les hôtes autorisés
ALLOWED_HOSTS=duhaz.fr,www.duhaz.fr

# Utiliser un mot de passe fort
DB_PASSWORD=<mot_de_passe_généré_par_openssl>
```

Et dans `settings.py`, décommentez :

```python
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_BROWSER_XSS_FILTER = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = 'DENY'
```

---

## 📚 Ressources

### Documentation officielle
- [Django Database Configuration](https://docs.djangoproject.com/en/5.1/ref/databases/)
- [MariaDB Knowledge Base](https://mariadb.com/kb/en/)
- [mysqlclient Documentation](https://mysqlclient.readthedocs.io/)

### Fichiers du projet
- `scripts/pre_migration_check.sh` - Vérifications préliminaires
- `scripts/test_mariadb_connection.py` - Test de connexion
- `scripts/migrate_to_mariadb.py` - Migration automatique
- `scripts/setup_mariadb.sh` - Configuration du serveur
- `scripts/setup_mariadb.sql` - Commandes SQL

---

## ✨ Checklist finale

Avant de considérer la migration terminée :

- [ ] Tous les tests de connexion passent
- [ ] L'admin Django fonctionne
- [ ] Les articles s'affichent sur le site
- [ ] Les images sont visibles
- [ ] Les modifications sont sauvegardées
- [ ] Un backup de SQLite est conservé
- [ ] Le fichier `.env` est sécurisé
- [ ] Les mots de passe sont forts
- [ ] La documentation est à jour

---

## 🆘 Besoin d'aide ?

Si vous rencontrez des problèmes :

1. Consultez la section **Dépannage** ci-dessus
2. Vérifiez les logs : `docker logs mariadb`
3. Testez chaque étape individuellement
4. Gardez votre backup SQLite jusqu'à ce que tout fonctionne

**Rappel important** : Ne supprimez JAMAIS `db.sqlite3` avant d'avoir vérifié que tout fonctionne parfaitement avec MariaDB !

---

Bonne migration ! 🚀