Cómo Configurar y Conectar Django con MySQL paso a paso

▶

Partimos de que, ya sabemos como trabajar con los modelos en Django, y el siguiente paso es la base de datos; aunque, Django por defecto usa SQLite, la cual es una base de datos excelente, a veces necesitamos emplear alguna base de datos más completa como lo es MySQL.

Con todas las capas que cuenta nuestro framework, una de las principales es la del manejo de datos, en otras palabras forma parte de nuestra base de datos, que pueden ser de varios tipos como MySQL, MariaDB, PostgreSQL entre otras.

Una de las partes que más dudas puede generar es cómo conectar Django con MySQL.

Aunque el framework trae SQLite por defecto, en cuanto un proyecto crece o se despliega en producción, MySQL se vuelve una opción más robusta y escalable.

En esta guía te muestro cómo integrar Django con MySQL paso a paso, tal como lo hago en mis proyectos reales. Vamos a ver requisitos, instalación, configuración y cómo resolver los errores más comunes.

¿Por qué usar MySQL con Django?

Aunque Django funciona perfectamente con SQLite, MySQL ofrece ventajas clave:

• Escalabilidad: ideal para entornos de producción con múltiples usuarios.
• Compatibilidad: muchos servicios de hosting soportan MySQL nativamente.
• Gestión avanzada: puedes usar herramientas como MySQL Workbench o phpMyAdmin.

Es importante mencionar que Django soporta oficialmente varios motores:

• PostgreSQL
• MariaDB
• MySQL
• Oracle
• SQLite (que es la que viene por defecto).

Conectores para cada motor de base de datos

Django puede conectarse a MySQL usando dos drivers:

• mysqlclient (oficial)
• PyMySQL (alternativo, más flexible)

Selección del Driver: mysqlclient vs. PyMySQL

Lo principal que tienes que tener en cuenta al momento en el cual quieras conectarte a un motor de base de datos, es que simplemente varía el conector, es decir, dependiendo al servidor de la base de datos que quieras conectarte simplemente tienes que variar el conector y en la documentación oficial que te dejo un poco más abajo podrás ver los distintos tipos de conectores que puedes emplear y con esto los diferentes clientes.

Para conectar Django con MySQL necesitamos un "driver". Existen dos opciones principales:

• mysqlclient (Oficial): Es el driver recomendado por Django. Su principal ventaja es el rendimiento, pero suele dar problemas en la instalación porque intenta compilar archivos en C. Esto requiere tener instaladas herramientas de desarrollo en el sistema operativo, lo cual puede ser tedioso en entornos como Mac o en servidores de producción como PythonAnywhere.
• PyMySQL: Es una alternativa escrita puramente en Python. No requiere compilación, por lo que es mucho más fácil de instalar en cualquier ambiente, aunque técnicamente Django no lo reconoce de forma nativa sin un pequeño "truco".

mysqlclient, el driver oficial

Podemos instalar el driver oficial mediante:

$ pip install mysqlclient  

Django desde la versión 3, podemos emplear un Driver nativo para MySQL y para MariaDB que tu eres libre de probar la solución oficial, pero en caso de que te de un error como el siguiente:

*** no se puede abrir el archivo incluir 'mysql.h' ***
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 1022, in exec_module
  File "<frozen importlib._bootstrap_external>", line 1160, in get_code
  File "<frozen importlib._bootstrap_external>", line 1090, in source_to_code
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/Users/andrescruz/Desktop/proyects/django/mystore/mystore/settings.py", line 95

Instalación con PyMySQL (Opción recomendada por facilidad)

Dado que mysqlclient suele dar errores de compilación si faltan librerías en C (que es el lenguaje que usa internamente) podemos utilizar PyMySQL en su lugar que lo cubrimos en el siguiente apartado.

Solventar los errores anteriores

Sin embargo, puedes intentar los siguientes pasos para poder instalar el Driver oficial:

$ brew install mysql-client pkg-config

Configura las variables de entorno (esto es lo que pide el error al final). Debes decirle a tu Mac dónde están los archivos de MySQL que acabas de descargar. Ejecuta esto antes de intentar el pip install:

export FLAGS=$(pkg-config --cflags --libs mysqlclient)
export LDFLAGS="-L/opt/homebrew/opt/mysql-client/lib"
export CPPFLAGS="-I/opt/homebrew/opt/mysql-client/include"

Intenta instalar de nuevo:

$ pip install mysqlclient

Probando la versión NO oficial del conector de MySQL

Podemos probar otra solución que seria instalar un paquete que servirá como driver o conector a nuestro MySQL que viene siendo el siguiente:

$ pip install PyMySQL

Para que Django acepte PyMySQL como si fuera el driver oficial, debemos ir al archivo __init__.py de la carpeta de nuestro proyecto (donde está el archivo settings.py) y agregar el siguiente código:

firstProject\firstProject\__init__py

import pymysql
pymysql.version_info = (2, 2, 7, "final", 0) # Definimos una versión compatible, el 2 2 7 corresponde a la version actual de mysqlclient
pymysql.install_as_MySQLdb()

Configuración del archivo settings.py

Una vez instalado cualquiera de los drivers, debemos modificar el diccionario DATABASES en nuestro proyecto. Cambiaremos el motor de SQLite a MySQL y definiremos los parámetros de conexión:

firstProject\firstProject\settings.py

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'djangofirstproyect',
        'USER': 'root',
        'PASSWORD': ''
    }
}

Y con esto estamos listos para hacer operaciones más interesantes empleando nuestro MTV en Django cosa que haremos a partir de la siguiente entrada.  

• DATABASE_NAME Indicamos el nombre de la base de datos. Si estás usando SQLite, especifica la ruta completo incluyendo el sistema de archivos hacia el archivo/base de datos.
• DATABASE_USER Indicamos cual es el usuario de base de datos que vamos a emplear para conectarnos a la base de datos anterior.
• DATABASE_PASSWORD Indicamos la contraseña del usuario anterior
• DATABASE_HOST Este es uno de los elementos más importantes y es el host, si estamos en ambiente de desarrollo seguro será el de localhost o servidor local, pero si estas en ambiente de producción es muy probable que cambie a otro o una IP.

Dependiendo de la base de datos que vayas a emplear, seguramente tendrás que agregar algunos parámetros más o menos, por ejemplo en el caso de SQLite, que es la que viene por defecto, no es necesario indicar ni usuario/contraseña y tampoco host, ya que la misma simplemente es un archivo.

Una vez configurado el settings.py, ejecuta las migraciones en Django para verificar la conexión:

$ python manage.py migrate

❗ Errores comunes al conectar Django con MySQL (y cómo los resolví)

Durante mis primeras pruebas me topé con algunos errores típicos:

Error    Causa    Solución
no se puede abrir mysql.h    Falta de dependencias de MySQL client    Instala PyMySQL o instala libmysqlclient-dev en Linux
Access denied for user 'root'@'localhost'    Contraseña incorrecta o usuario sin permisos    Revisa USER y PASSWORD en settings.py
django.db.utils.OperationalError    MySQL no iniciado    Verifica que el servicio esté activo (sudo service mysql start)

Estos pequeños contratiempos son comunes. En mi caso, con PyMySQL todo funcionó sin complicaciones.

⚖️ PyMySQL vs mysqlclient: ¿cuál conviene más?

Aspecto    PyMySQL    mysqlclient
Instalación    Muy sencilla, sin compilación    Requiere dependencias del sistema
Rendimiento    Ligero y suficiente para la mayoría de proyectos    Algo más rápido en grandes bases
Compatibilidad    Funciona bien en Windows, macOS y Linux    A veces da errores en Windows
Recomendación    Ideal para entornos de desarrollo y medianos    Recomendado en producción si tu entorno lo permite

Yo prefiero PyMySQL por su facilidad y estabilidad, especialmente cuando trabajo en Windows o entornos virtualizados.

Conclusión y próximos pasos

Con esto ya tienes tu proyecto Django conectado a MySQL y listo para construir modelos, vistas y migraciones.
En mi experiencia, esta configuración se mantiene estable incluso al desplegar en producción.
El siguiente paso natural es crear tus modelos y comenzar a manipular datos desde el ORM de Django.

❓ Preguntas frecuentes

• ¿Puedo usar MariaDB en lugar de MySQL?
  • Sí, Django es compatible de forma nativa desde la versión 3.
• ¿Cómo pruebo si mi conexión funciona?
  • Ejecuta python manage.py migrate o usa python manage.py dbshell.
• ¿Qué hago si PyMySQL no funciona?
  • Verifica tu versión de Python y Django, reinstala con pip install --upgrade PyMySQL.