Objetivo y Diagnóstico Inicial

Al conectar un proyecto Django a un motor MySQL o MariaDB en entornos locales (como Laragon, XAMPP, Docker) o servidores de producción, es muy común encontrar errores de arranque.

El objetivo de esta guía técnica es identificar con precisión si el error de conexión se debe a las versiones de Django/MySQL o al controlador de Python, y aplicar la solución apropiada evitando pasos en falso como borrar migraciones.

💡 Regla de oro antes de actuar:Primero se verifican las versiones y después se decide si es necesario actualizar Django/MySQL o probar un controlador alternativo. PyMySQL no convierte en compatibles versiones de servidor que Django no admite.

Paso 1. Comprobar la Versión de Django y Python

Abre una terminal dentro de la carpeta raíz de tu proyecto y asegúrate de tener el entorno virtual (venv) activado:

Terminal: Verificación de Django y Python

BASH

# 1. Comprobar la versión exacta de Django
python -m django --version
 
# 2. Comprobar la versión de Python del entorno
python --version
 
# 3. Inspeccionar los detalles del paquete instalado
python -m pip show Django

Registra la versión obtenida (por ejemplo, Django 5.2.1 y Python 3.12). Si el comando falla, comprueba que el entorno virtual correcto esté activo.

Paso 2. Comprobar la Versión del Servidor MySQL o MariaDB

Es crucial conocer la versión del servidor que está ejecutándose y escuchando peticiones, no simplemente la de la herramienta cliente:

Opción A: Desde Consola SQL, Workbench o phpMyAdmin

SQL: Versión real del servidor

SQL

1SELECT VERSION();

Devuelve la versión exacta del daemon MySQL o MariaDB al que estás conectado.

Opción B: Desde la Terminal del Servidor

CLI: Versión de la utilidad cliente

BASH

1mysql --version

⚠️ Atención: mysql --version puede mostrar la versión del cliente local; SELECT VERSION() identifica con certeza la versión del servidor.

Paso 3. Verificar la Compatibilidad Oficial

Compara ambas versiones con la documentación oficial correspondiente a la versión instalada de Django. No basta con instalar un controlador si Django no admite la versión del motor de base de datos.

Versión de Django	MySQL Mínimo Oficial	MariaDB Mínimo Oficial	Observaciones
4.2 LTS	8.0.11	10.4	Soporte extendido LTS previo
5.2 LTS	8.0.11	10.5	Versión recomendada de estabilidad empresarial
6.0+	8.0.11	10.6	Requisitos modernos de ventanas y CTEs

Para versiones específicas, consulta siempre las Notas Oficiales de MySQL en Django.

Paso 4. Instalar PyMySQL (Alternativa al Controlador mysqlclient)

El controlador recomendado por Django es mysqlclient, pero al estar escrito en C suele requerir dependencias de compilación y librerías C++ que fallan con frecuencia en Windows.

Si el servidor MySQL es compatible con Django y el inconveniente es la instalación o carga de mysqlclient, podemos usar PyMySQL (escrito 100% en Python puro).

1. Instalación en el entorno virtual

BASH

1python -m pip install pymysql

En el archivo __init__.py del paquete principal del proyecto (la misma carpeta donde se encuentra settings.py), agrega:

mi_proyecto/__init__.py

PYTHON

import pymysql
 
# Le indica a Django que use PyMySQL emulando la interfaz de MySQLdb
pymysql.install_as_MySQLdb()

Estructura del Proyecto:

mi_proyecto/
│
├── manage.py
└── mi_proyecto/
    ├── __init__.py    <-- AQUÍ se agregan las líneas de pymysql
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

Paso 5. Configurar la Conexión en settings.py

Configura el bloque DATABASES utilizando el motor nativo de Django para MySQL:

settings.py: Configuración de MySQL

PYTHON

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'eventos_db',
        'USER': 'usuario_mysql',
        'PASSWORD': 'tu_clave_segura',
        'HOST': '127.0.0.1',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
        },
    }
}

⚠️ Nota de Seguridad: Reemplaza los valores de ejemplo por los de tu instalación local o servidor. No publiques contraseñas reales en repositorios Git; utiliza variables de entorno (como python-decouple o os.environ) en proyectos compartidos o productivos.

Paso 6. Comprobar el Funcionamiento

Ejecuta las siguientes instrucciones en tu terminal para validar el estado de la conexión:

Comandos de validación

BASH

# 1. Comprobación del sistema sin alterar tablas
python manage.py check
 
# 2. Aplicar migraciones al servidor MySQL
python manage.py migrate
 
# 3. Iniciar el servidor de desarrollo
python manage.py runserver

Si python manage.py check responde "System check identified no issues (0 silenced)", la conexión física y lógica está completamente validada.

¿Qué hacer si sigue sin funcionar? (Troubleshooting)

Revisa esta guía rápida de diagnóstico según el síntoma exacto que reporte la consola:

1. Error de versión mínima de MySQL / MariaDB

Causa: El servidor tiene una versión antigua (ej. MySQL 5.7).
Solución: Actualizar el motor MySQL a una versión admitida por Django (8.0.11+), o utilizar una versión anterior de Django que sí soporte el servidor existente. PyMySQL no elimina esta restricción del ORM.

2. Error de mysqlclient / MySQLdb

Causa: Falta el driver o __init__.py no se está ejecutando.
Solución: Comprobar que PyMySQL esté instalado en el mismo entorno virtual (pip list) y que pymysql.install_as_MySQLdb() esté en el __init__.py correcto.

3. Access denied for user '...'@'...'

Causa: Credenciales incorrectas o usuario sin permisos.
Solución: Verificar usuario, contraseña, nombre de la base de datos y otorgar permisos con GRANT ALL PRIVILEGES ON nombre_bd.* TO 'usuario'@'localhost';.

4. Can't connect to MySQL server (2003 / 10061)

Causa: El servicio MySQL está detenido o el puerto está bloqueado.
Solución: Verificar que MySQL esté iniciado (en Laragon, XAMPP, Docker o Servicios de Windows), y que el host (127.0.0.1) y puerto (3306) coincidan.

5. ¿Qué pasa con las migraciones existentes?

Realiza una copia de seguridad antes de cambiar de versión de Django o del servidor. Nunca elimines los archivos de migraciones para intentar corregir un problema de conexión a la base de datos.

Actividad de Comprobación Técnica

Completa este checklist de auditoría antes de dar por finalizada la configuración de tu entorno:

[ ]Versión de Python: __________________

[ ]Versión de Django: __________________

[ ]Versión del servidor MySQL/MariaDB: __________________

[ ]¿Son compatibles según la documentación?: [ Sí / No ]

[ ]¿Se instaló PyMySQL y se registró en __init__.py?: [ Sí / No ]

[ ]Resultado de python manage.py check: [ 0 issues / Falló ]

Ponte a Prueba

Comprueba que dominas el diagnóstico de compatibilidad de MySQL, la sustitución con PyMySQL y la resolución de incidentes de conexión en Django.

Contenido

📚 Cursos de Café y Código

5.4 Conexión de Django con MySQL y PyMySQL 🐬

Objetivo y Diagnóstico Inicial

Paso 1. Comprobar la Versión de Django y Python

Paso 2. Comprobar la Versión del Servidor MySQL o MariaDB

Opción A: Desde Consola SQL, Workbench o phpMyAdmin

Opción B: Desde la Terminal del Servidor

Paso 3. Verificar la Compatibilidad Oficial

Paso 4. Instalar PyMySQL (Alternativa al Controlador mysqlclient)

Estructura del Proyecto:

Paso 5. Configurar la Conexión en settings.py

Paso 6. Comprobar el Funcionamiento

¿Qué hacer si sigue sin funcionar? (Troubleshooting)

1. Error de versión mínima de MySQL / MariaDB

2. Error de mysqlclient / MySQLdb

3. Access denied for user '...'@'...'

4. Can't connect to MySQL server (2003 / 10061)

5. ¿Qué pasa con las migraciones existentes?

Actividad de Comprobación Técnica

Ponte a Prueba

¡Hecho con mucho cariño! ☕