Doc Technique - Fix Index Collisions (MariaDB/MySQL 1061)

Cron / Management Command

Fix Index Collisions — Résout les erreurs 1061 (Duplicate key name) sur MariaDB/MySQL

Ce cron est un “outil de déblocage” : il analyse le plan de migrations et drop automatiquement les index déjà présents que Django tente de recréer — cause typique de : django.db.utils.OperationalError: (1061) "Duplicate key name".

MariaDB / MySQL 1061 Duplicate key name Auto drop indexes Mode chirurgical --drop-index Dry-run Scope --apps

Ce que fait la commande :

Reconstruit les index que Django va tenter de créer (Meta.indexes, AddIndex, index_together, AlterIndexTogether).
Interroge la DB (INFORMATION_SCHEMA) pour voir si ces index existent déjà.
Optionnellement : drop les index conflictuels, puis tu relances migrate.
Supporte un mode “chirurgical” : drop un index donné par son nom.

Important : ce cron est conçu pour MariaDB/MySQL. Il est parfait en dev / staging. En prod : à utiliser avec précaution (fenêtre de maintenance).

Étape 1 — Installation du Cron / Management Command

1) Où placer le fichier Python

Place fix_index_collisions.py dans une app installée (ex: toolbox), sous management/commands.

your_project/
  toolbox/                               # ou accounts/, tools/...
    management/
      __init__.py
      commands/
        __init__.py
        fix_index_collisions.py          # <= le cron

Ne pas oublier : les __init__.py dans management/ et commands/.

2) Copier le fichier `fix_index_collisions.py`

Colle le contenu exact du cron (ta version actuelle). :contentReference[oaicite:1]{index=1}

# (colle ici le contenu complet du fichier — Référence : :contentReference[oaicite:2]{index=2})

3) Vérifier que l’app est dans INSTALLED_APPS

INSTALLED_APPS = [
  # ...
  "toolbox",  # ou l'app qui contient management/commands/fix_index_collisions.py
]

4) Vérifier la commande

python manage.py fix_index_collisions --help

Étape 2 — Utilisation

A) Mode auto (scan plan migrations)

# Liste les index qui vont poser un problème (sans drop)
python manage.py fix_index_collisions --dry-run --verbose-sql

# Drop les index conflictuels puis relance migrate
python manage.py fix_index_collisions --verbose-sql
python manage.py migrate

B) Restreindre à une ou plusieurs apps

# Exemple : ne scanner que l'app "weglot"
python manage.py fix_index_collisions --dry-run --apps weglot

C) Spécifier une base (alias Django)

# Par défaut: "default"
python manage.py fix_index_collisions --database default --dry-run

Modes & Scénarios

1) Mode auto (recommandé)

Analyse le plan de migrations de Django
Reconstruit les index attendus
Drop les index déjà présents en DB (collisions 1061)

python manage.py fix_index_collisions --dry-run --verbose-sql
python manage.py fix_index_collisions --verbose-sql
python manage.py migrate

2) Mode chirurgical (ultra pratique)

Si Django t’affiche un index précis dans l’erreur : Duplicate key name 'xxxx_idx' tu peux le supprimer directement, sans scanner le plan.

# Exemple : drop direct, la commande retrouve la table automatiquement
python manage.py fix_index_collisions --drop-index analyzer_co_app_nam_f60e0c_idx --verbose-sql
python manage.py migrate

Astuce : commence toujours par --dry-run en prod / staging, ou par --verbose-sql pour tracer le SQL.

FAQ / Dépannage

1) Je ne vois pas la commande dans manage.py

Vérifie :

le chemin management/commands
les __init__.py
que l’app est dans INSTALLED_APPS

2) “No conflicting indexes found” mais migrate plante

Utilise le mode chirurgical :

copie le nom exact dans l’erreur Django
lance : --drop-index NOM

python manage.py fix_index_collisions --drop-index NOM_DONNE_PAR_DJANGO --verbose-sql

3) J’ai maintenant une erreur 1071 (key too long)

Normal : tu as supprimé les collisions 1061, et tu révèles le problème suivant. Utilise le cron migration_analyze (V2) pour diagnostiquer & proposer des actions (191, etc.).

# Tous les jours à 03:10 - audit uniquement (dry-run)
10 3 * * * cd /opt/ideo-lab && . venv/bin/activate && python manage.py fix_index_collisions --dry-run --verbose-sql >> /var/log/ideo-lab/fix_index_collisions.log 2>&1

Auto-drop en cron n’est pas conseillé en prod. En revanche, en staging/dev, ça peut automatiser un reset propre.

Session type (dev)

# 1) Repérer ce qui coince
python manage.py fix_index_collisions --dry-run --verbose-sql

# 2) Drop auto
python manage.py fix_index_collisions --verbose-sql

# 3) Migrer
python manage.py migrate

Session chirurgicale (quand Django donne l’index)

python manage.py fix_index_collisions --drop-index analyzer_co_app_nam_f60e0c_idx --verbose-sql
python manage.py migrate