Migraciones en Django: qué son, cómo funcionan y ejemplos paso a paso

▶

Ya con nuestros modelos definidos, seguramente ahora te estas preguntando cómo mantener sincronizada la base de datos con los modelos de tu proyecto Django, las migraciones son tu mejor aliada. En esta guía te explico, desde mi experiencia desarrollando con Django, qué son, cómo se crean y cómo resolver los errores más comunes.

Lo primero que te puedes preguntar seria...

¿Qué son las migraciones en Django y por qué son importantes?

En términos generales, ya que este mismo esquema lo emplean otros frameworks modernos como Laravel, CodeIgniter 4 y Flask; podríamos ver una migración como simplemente un esquema que va a hacer mapeado en la base de datos que tengamos configurada, en la misma generalmente indicamos como está descrita una tabla.

Las migraciones son una manera incremental que tenemos para actualizar el esquema o como esta formada la base de datos; con incremental quiero decir que podemos ir agregando más migraciones a medida que vayamos desarrollando el proyecto y tienen un orden secuencial en que se ejecuten que es directamente proporcional al orden en el cual creamos las mismas.

En pocas palabras, una migración en Django es la forma en que el framework traduce tus modelos de Python (models.py) a estructuras reales de base de datos (tablas, columnas, relaciones, etc.).
Cada vez que modificas un modelo, Django registra esos cambios en un archivo de migración, que luego puede aplicarse a la base de datos con un comando.

Cuando comencé a trabajar con Django, me sorprendió lo fácil que era versionar el esquema sin tocar directamente SQL. A diferencia de frameworks como Laravel o Flask, aquí las migraciones se generan automáticamente y se aplican con un simple comando.

Ventajas principales:

• Control total del esquema de tu base de datos.
• Historial versionado de cambios.
• Facilidad para compartir el estado de la base con otros miembros del equipo.
• Posibilidad de revertir o rehacer cambios sin perder datos.

Las migraciones nos facilitan el proceso a los desarrolladores: en lugar de enviar un dump SQL, solo compartíamos los archivos de migración y todo quedaba perfectamente sincronizado.

Cómo funcionan las migraciones en Django

Detrás de escena, Django usa su ORM (Object Relational Mapper) para traducir tus modelos a instrucciones SQL.

Cada app dentro de tu proyecto contiene una carpeta migrations/, donde se almacenan los archivos que describen cada cambio incremental.

El flujo general es:

1. Modificas tus modelos.
2. Ejecutas python manage.py makemigrations → Django genera archivos con los cambios.
3. Ejecutas python manage.py migrate → Django aplica esos cambios a la base de datos.

Una vez me encontré con el clásico mensaje “No changes detected”, y resultó que había olvidado registrar la app en INSTALLED_APPS. Desde entonces, siempre reviso la configuración antes de crear migraciones.

Ventajas de la migración

Las migraciones tienen una ventaja enorme con respecto al esquema tradicional en la cual la definición del a base de datos en tarea aparte; con las migraciones podemos tener un control total sobre las tablas que tengamos definida en la base de datos y por lo tanto estamos creando otra capa entre la base de datos y nuestro proyecto como tal en la cual tenemos el control total sobre la estructura de la base de datos.

Con las migraciones es muy fácil compartir a otros integrantes del proyecto tu esquema de trabajo, ya que simplemente puedes pasar el archivo o migración para que tu compañero o compañeros de trabajo puedan emplear el mismo esquema que tú; ya no es necesario que cada quien cree la base de datos de manera manual si no mediante nuestro propio framework.

Así que, ya sabes para qué son las migraciones y su ventaja enorme en comparación con otros esquemas; así que vamos a ir a nuestro proyecto en Django para crear las migraciones.

Crear tu primera migración paso a paso

Para crear una migración en Django, nada más fácil, ya lo tenemos todo gratis al momento de crear un proyecto en Django; simplemente tenemos que ejecutar el siguiente comando desde tu terminal, a la altura de las carpetas de las aplicaciones (dentro de la carpeta del proyecto):

$ python manage.py makemigrations

O correr las migraciones por aplicación:

$ python manage.py makemigrations firstApp

En cualquier caso, verás una salida como la siguiente:

python manage.py makemigrations firstApp   Migrations for 'firstApp':  firstApp\migrations\0001_initial.py    - Create model Emplyoee

En la cual ya tenemos la migración creada; por lo tanto, tenemos una carpeta llamada migrations dentro de la aplicación firstApp y dentro de l misma, la migración correspondiente.

Aquí tu eres libre de personalizar ciertos aspectos de la misma antes de que Django traduzca esto a SQL para luego crear la tabla en la base de datos configurada; aunque generalmente NO es necesario hacer ningún cambio extra.

1️⃣ Verifica tu configuración y modelo

Primero, debes de tener algún modelo creado, por ejemplo:

Ejemplo de modelo simple:

models.py

from django.db import models
class Employee(models.Model):
   name = models.CharField(max_length=100)
   position = models.CharField(max_length=100)
   salary = models.DecimalField(max_digits=10, decimal_places=2)

2️⃣ Ejecuta python manage.py makemigrations

Para ejecutar la migración anterior simplemente tenemos que ejecutar el siguiente comando:

$ python manage.py migrate

Y con esto se van a ejecutar una serie de migraciones, y no solo la tuya, ya que, para cada aplicación que tengas instalado aunque sea por defecto en Django, las mismas tienen migracions creadas y por lo tanto ya están listas para ser mapeadas a la base de datos con el comando anterior:

Migrations for 'firstApp':
  firstApp/migrations/0001_initial.py
    - Create model Employee

Y con esto, si revisamos en la base de datos:

Tenemos nuestra tabla o tablas creada en caso de que tuvieses más de una migración o modelo definido.

Volver a ejecutar migraciones 

Puedes ejecutar cualquiera de los comandos anteriores nuevamente:

python manage.py migrate Operations to perform:  Apply all migrations: admin, auth, contenttypes, firstApp, sessions Running migrations:  No migrations to apply.

Pero verás que no pasa nada, ya que Django detecta que ya no tiene que crear una migración, ya que la misma fue creada y fue ejecutada en la base de datos y traducida con la tabla en nuestra base de datos que vimos anteriormente; te puedes preguntar cómo sabe Django que la tabla existe; pues básicamente por la otra tabla que se creó llamada:

Que básicamente guarda registros de las migraciones que se hallan ejecutada en nuestra base de datos; en este punto puedes crear nuevas aplicaciones y modelos, o definir mas modelos o cambiar los ya existente y en cualquier punto crear y ejecutar las migraciones.

Principales comandos y su uso (cheat sheet visual)

Comando    Descripción    Cuándo usarlo
makemigrations    Crea los archivos de migración a partir de tus modelos    Después de modificar modelos
migrate    Aplica las migraciones a la base de datos    Para reflejar cambios reales
showmigrations    Lista todas las migraciones existentes    Para verificar estado
sqlmigrate <app> <número>    Muestra el SQL que ejecutará Django    Para revisar qué hará la migración
migrate --plan    Muestra el plan de ejecución de migraciones    Antes de aplicar cambios críticos
migrate --fake    Marca una migración como aplicada sin ejecutarla    En sincronizaciones manuales

Yo uso showmigrations antes de desplegar, para confirmar que todo está en orden y evitar sorpresas en producción.

Renombrar campos sin perder datos

Usa RenameField para mantener la integridad de la información sin borrar la columna.

Revertir una migración

Puedes deshacer una migración ejecutando:

$ python manage.py migrate firstApp 0001

Esto revierte a la migración indicada.

Una vez tuve que revertir porque había definido un CharField con longitud insuficiente. Django lo manejó sin pérdida de datos.

Revertir migraciones en Django, 2 FORMAS

▶

En Django no contamos con un comando directo como migrate rollback para revertir migraciones, lo cual sería extremadamente útil en muchas situaciones.

Muchas veces creamos nuestros modelos, generamos las migraciones asociadas mediante el comando makemigrations pero luego nos damos cuenta de que nos equivocamos en algo... y bueno, tremendo problema.

Opción 1: Revertir todas las migraciones de una app

Para este caso, te voy a mostrar un par de maneras de hacerlo. Nuevamente, pueden existir muchas implementaciones, pero todas van más o menos en la misma línea.

Una opción muy común es ejecutar el siguiente comando:

python manage.py migrate nombre_app zero

Por ejemplo, si tu app se llama blog, sería:

python manage.py migrate blog zero

¿Qué significa esto?

Que se van a revertir todas las migraciones de esa aplicación llamada blog, que se supone es la que tiene el problema y que necesitas corregir.

Luego de eso, debes hacer correcciones tanto en tu modelo como, posiblemente, en los archivos de migración generados.
Por ejemplo, si te faltó agregar el campo description, puedes hacerlo directamente en el modelo y también, si lo prefieres, modificar manualmente la migración duplicando y ajustando un bloque existente.

Opción 2: Revertir hasta una migración específica

Otra opción es indicar exactamente hasta qué migración deseas volver.
Por ejemplo:

python manage.py migrate blog 0002

Esto supone que quieres regresar a la migración 0002.

Recuerda que las migraciones van creciendo cada vez que haces cambios en tus modelos. Por ejemplo:

• 0001_initial.py
• 0002_add_description.py
• 0003_add_subscribers.py

Y así sucesivamente, dependiendo de las modificaciones que vayas haciendo en la app blog.

Este método es útil si, por ejemplo, más adelante agregas una migración para suscriptores u otra tabla, y necesitas revertir solo hasta un punto específico sin borrar todo lo anterior.

¿Cuál usar?

En resumen:

• Si quieres eliminar todas las migraciones de una app (por ejemplo, porque estás empezando de cero o el error está desde el inicio), puedes usar la opción del zero.
• Si quieres revertir solo una migración específica sin eliminar todo, puedes usar el número exacto de migración como en el segundo método.

Este segundo comando sería lo más cercano al concepto de rollback, ya que te permite volver a un estado anterior puntual.
No es tan automático como rollback, pero en esencia cumple el mismo objetivo: revertir una migración para que puedas corregir algo que salió mal.

Así que, si solo tienes una migración o el error está en la primera, la opción del zero es perfecta.
Pero si necesitas un poco más de control, puedes especificar la migración exacta a la que deseas volver.

Conflictos y errores comunes al usar migraciones

Errores que verás tarde o temprano:

• “No changes detected” → la app no está registrada o no hay cambios.
• “Conflicting migrations detected” → dos desarrolladores crearon migraciones distintas en paralelo.
• “no such table” → migraciones aplicadas fuera de orden.

Soluciones prácticas:

• Fusionar migraciones con python manage.py makemigrations --merge.
• Falsificar migraciones con migrate --fake o --fake-initial cuando la base ya existe.
• Regenerar las migraciones eliminando archivos locales y recreándolos (solo en entornos de desarrollo).

Buenas prácticas para trabajar con migraciones en equipo

• Asegúrate de ejecutar makemigrations solo después de actualizar tu rama.
• Evita modificar directamente archivos de migración ya aplicados.
• Realiza squash de migraciones viejas periódicamente (python manage.py squashmigrations).
• Mantén tus migraciones bajo control de versiones (Git).
• Coordina con tu equipo los cambios en modelos antes de fusionar ramas.

Preguntas frecuentes (FAQ)

1. ¿Qué diferencia hay entre makemigrations y migrate?
El primero genera los archivos de migración, el segundo los aplica a la base de datos.

2. ¿Por qué Django no detecta cambios?
Porque no hubo modificaciones en los modelos o la app no está en INSTALLED_APPS.

3. ¿Cómo revertir una migración?
Ejecuta python manage.py migrate <app> <número_de_migración>.

4. ¿Dónde guarda Django el historial de migraciones?
En la tabla django_migrations dentro de tu base de datos.

5. ¿Qué pasa si elimino la carpeta migrations/?
Perderás el historial; Django no sabrá qué cambios se aplicaron. Evítalo en proyectos activos.

Conclusiones

Las migraciones son un componente muy potente que existen en este tipos de frameworks; nos permiten modificar y agregar o alterar la estructura de los modelos para que luego podamos reflejar estos cambios en nuevas migraciones y a posterior en la base de datos.

Recuerda los tres pasos para trabajar las migraciones:

1. Cambiar los modelos (en models.py).
2. Ejecutar el comando python manage.py makemigrations para crear migraciones para esos cambios
3. Ejecutar el comando python manage.py migrate para aplicar esos cambios a la base de datos.

Recuerda que cada comando hace una operación en específico y debe de seguir el orden correspondiente para que todo te funcione y puedas ver los cambios reflejados.

Trabajar con migraciones es sencillo cuando entiendes su flujo natural:

• Cambia los modelos (models.py).
• Crea migraciones (makemigrations).
• Aplica cambios (migrate).

Seguir este orden te ahorrará errores y dolores de cabeza.

En mi caso, dominar las migraciones cambió mi forma de trabajar con Django: ya no temo modificar modelos ni tocar la base de datos, porque sé que el framework lleva el control por mí.

Ahora, aprende a crear un listado paginado en Django.