Modelos en Django y Base de Datos: Guía Práctica con ORM

- Andrés Cruz - EN In english

Video thumbnail

Cuando empecé con Django, lo que más me sorprendió fue su enfoque para gestionar la base de datos a través de los modelos. Si vienes del ecosistema de PHP —como fue mi caso al trabajar con frameworks como Laravel o CodeIgniter—, notarás una diferencia muy interesante: en Django puedes centralizar toda la definición de tus tablas dentro de un único archivo por aplicación, manteniendo un control limpio, estructurado y ordenado de tus datos.

En este artículo te enseño qué son los modelos en Django, cómo crearlos paso a paso y cómo aprovecharlos para estructurar tu base de datos de forma profesional con el ORM, conociendo los tipos de campos indispensables, sus relaciones, el proceso de migraciones y el registro en el panel de administración.

Partimos del paso previo: si aún no has montado tu primer proyecto, te sugiero revisar cómo crear nuestro primer Hola Mundo en Django.

Qué es un modelo en Django y por qué es tan importante

Video thumbnail

Un modelo es una de las piezas angulares del patrón de diseño MTV (Model–Template–View) en Django.
Representa tanto la estructura como el comportamiento de las entidades de tu aplicación. En términos de base de datos, cada modelo equivale a una tabla, y cada atributo definido dentro de la clase se traduce en una columna.

En Django, el modelo es tu puente directo hacia la base de datos: define cómo se almacenan los registros, qué restricciones aplican, cómo se relacionan entre sí y cómo interactúas con ellos mediante el ORM (Object-Relational Mapping) de Django, sin necesidad de escribir consultas SQL manuales.

El modelo dentro del patrón MTV

El modelo representa la "M" de la arquitectura MTV y asume tres responsabilidades clave:

  • Estructurar los datos: define los nombres de columnas, tipos de datos (CharField, IntegerField, TextField) y validaciones.
  • Gestionar relaciones entre entidades: establece vínculos de tipo clave foránea (ForeignKey), relaciones uno a uno (OneToOneField) o muchos a muchos (ManyToManyField).
  • Encapsular la lógica de negocio: almacena métodos personalizados, propiedades calculadas y reglas específicas de cada entidad.

Los modelos constituyen la única fuente de verdad sobre tus datos. Si tu plataforma gestiona mascotas, tendrás un modelo Dog; si gestiona un blog, tendrás un modelo Post y un modelo Comment.

Conexión con la base de datos: el papel de las migraciones

Una vez definido un modelo en código Python, entra en juego el sistema de migraciones de Django. Una migración es un archivo generado automáticamente que describe las modificaciones de esquema que deben aplicarse sobre el motor de base de datos para que coincidan con lo que definiste en tus modelos.

Por defecto, un proyecto recién creado en Django utiliza SQLite, un motor de base de datos embebido y listo para usar cuya configuración reside en el bloque DATABASES del archivo settings.py. Más adelante en nuestro aprendizaje veremos cómo conectar motores robustos en producción, tales como PostgreSQL o MySQL.

Cómo Django convierte una clase Python en una tabla

Cuando declaras una clase que hereda de models.Model dentro de models.py y ejecutas las migraciones, Django inspecciona los atributos y ejecuta internamente el comando CREATE TABLE con la sintaxis precisa del motor que estés utilizando. Esa abstracción limpia y transparente es el mayor beneficio del ORM de Django.

Estructura modular: el archivo models.py

Para trabajar con modelos, primero debes contar con una aplicación creada dentro de tu proyecto. En nuestro ejemplo nos apoyaremos en la aplicación:

firstProject

Dentro del directorio de la aplicación encontrarás el archivo models.py. Como su nombre anticipa, este módulo sirve para definir todos los modelos correspondientes a dicha aplicación.

Si tienes experiencia previa con PHP o frameworks como Laravel, esto puede llamarte la atención al principio: en Laravel suele crearse un archivo por cada modelo (por ejemplo, User.php, Post.php). En Django, gracias al sistema de paquetes y módulos de Python, podemos definir múltiples clases relacionadas dentro del mismo models.py, lo que otorga una visibilidad global de todo el esquema de esa app.

Tener las entidades de un módulo concentradas en su propio models.py facilita auditar dependencias entre clases, mantener consistencia en las relaciones y modularizar la lógica de datos de forma limpia.

Cómo crear un modelo en Django

Crear un modelo es tan directo como declarar una clase en Python que herede de models.Model (provisto por django.db.models). Cada atributo que declares en esa clase será una columna con sus propias reglas y restricciones en la tabla.

Tipos de campos habituales en django.db.models

Django proporciona un extenso repertorio de clases para modelar prácticamente cualquier tipo de dato en tu base de datos:

  • models.CharField: para cadenas de texto de longitud limitada (requiere el parámetro max_length).
  • models.TextField: para textos largos, descripciones o contenido editorial sin límite fijo.
  • models.IntegerField y models.PositiveSmallIntegerField: para valores numéricos enteros o enteros pequeños positivos.
  • models.FloatField y models.DecimalField: para números decimales o importes financieros con control de dígitos y precisión.
  • models.BooleanField: para valores booleanos (True o False).
  • models.DateField y models.DateTimeField: para almacenar fechas y marcas de tiempo con soporte para auto_now_add y auto_now.
  • models.SlugField: para generar identificadores legibles en URLs basados en texto alfanumérico y guiones.
  • models.ForeignKey: para establecer relaciones de uno a muchos con integridad referencial.

Puedes consultar la lista completa y detallada de opciones en la documentación oficial de Django Model Fields.

Veamos un primer ejemplo práctico con un modelo de comentarios:

from django.db import models

class Comment(models.Model):
    text = models.TextField()
    date_posted = models.DateTimeField(auto_now_add=True)
    element = models.ForeignKey(Element, related_name='comments', on_delete=models.CASCADE, null=True)

    def __str__(self):
        return 'Comentario #{}'.format(self.id)

Explicación del modelo Comment

Analicemos qué compone este primer modelo:

  • text = models.TextField(): campo destinado a almacenar el cuerpo del comentario sin una restricción de tamaño rígida.
  • date_posted = models.DateTimeField(auto_now_add=True): guarda la fecha y hora de creación. Con el argumento auto_now_add=True, Django asigna automáticamente el timestamp actual del servidor al momento de insertar el registro por primera vez.
  • element = models.ForeignKey(Element, related_name='comments', on_delete=models.CASCADE, null=True): establece una relación foránea hacia el modelo Element. El parámetro on_delete=models.CASCADE asegura que, si el elemento padre es eliminado, sus comentarios asociados se supriman en cascada; mientras que null=True permite que el campo admita valores nulos en la base de datos si fuera necesario.
  • El método especial def __str__(self): define la representación en texto legible de la instancia del modelo, devolviendo en este caso una cadena como Comentario #1.

Caso práctico: diseño de modelos en elements/models.py

Para ver cómo interactúan varios modelos en un proyecto real, supongamos una aplicación llamada elements donde modelamos categorías, tipos de contenido y publicaciones generales.

Editamos el archivo elements/models.py con la siguiente estructura:

from django.db import models

# Create your models here.
class Category(models.Model):
    title = models.CharField(max_length=255)
    slug = models.SlugField(max_length=255)

    def __str__(self):
        return self.title

class Type(models.Model):
    title = models.CharField(max_length=255)
    slug = models.SlugField(max_length=255)

    def __str__(self):
        return self.title

class Element(models.Model):
    title = models.CharField(max_length=255)
    slug = models.SlugField(max_length=255, blank=True)
    description = models.TextField()
    price = models.DecimalField(max_digits=10, decimal_places=2, default=6.10)  # ej: 12345678.10
    category = models.ForeignKey(Category, on_delete=models.CASCADE)
    type = models.ForeignKey(Type, on_delete=models.CASCADE)
    created = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.title

Desglose paso a paso del código:

Primero, importamos el módulo models desde django.db:

from django.db import models

A continuación, declaramos cada clase heredando de models.Model:

class Category(models.Model):
    # atributos y métodos

class Type(models.Model):
    # atributos y métodos

class Element(models.Model):
    # atributos y métodos

Con esta herencia, Django dota a cada una de estas clases de toda la funcionalidad del ORM: acceso al gestor de consultas (objects), métodos de persistencia como save() y delete(), y compatibilidad con las migraciones.

En este caso, Category y Type funcionan como modelos maestros o catálogos auxiliares, mientras que Element representa el elemento principal del negocio (un artículo, un curso o cualquier contenido publicable).

Detalle de los campos del modelo Element

  • title = models.CharField(max_length=255): campo de texto corto. El argumento obligatorio max_length=255 restringe la longitud a nivel de base de datos (generalmente una columna VARCHAR(255)).
  • slug = models.SlugField(max_length=255, blank=True): campo especializado en almacenar slugs aptos para URLs amigables. El modificador blank=True indica que el campo puede dejarse vacío al validar formularios en el panel de administración o vistas.
  • price = models.DecimalField(max_digits=10, decimal_places=2, default=6.10): ideal para valores monetarios. Requiere definir max_digits (total de dígitos admitidos) y decimal_places (cantidad de cifras decimales). Definimos un valor predeterminado con default=6.10.
  • category = models.ForeignKey(Category, on_delete=models.CASCADE) y type = models.ForeignKey(Type, on_delete=models.CASCADE): crean sendas relaciones muchos a uno con sus respectivos modelos. Con on_delete=models.CASCADE aseguramos la integridad referencial en la base de datos eliminando los elementos dependientes cuando se borre la categoría o tipo asociado.
  • description = models.TextField(): campo de texto enriquecido o extenso, óptimo para guardar el cuerpo o sinopsis del contenido.
  • created = models.DateTimeField(auto_now_add=True) y updated = models.DateTimeField(auto_now=True): mientras que auto_now_add=True fija la fecha de creación una sola vez al insertar el registro, auto_now=True actualiza la marca de tiempo cada vez que se llama al método save(), permitiendo auditar la última modificación.

Migraciones: sincronizar tus modelos con la base de datos

Tener las clases declaradas en models.py no crea las tablas de forma automática. Para materializarlas en la base de datos, debemos recurrir a dos comandos fundamentales de Django:

python manage.py makemigrations
python manage.py migrate

¿Qué hace cada uno?

  • python manage.py makemigrations: examina los cambios en tus modelos dentro de models.py y redacta archivos de migración (ubicados en la carpeta migrations/ de tu aplicación).
  • python manage.py migrate: lee esas migraciones pendientes y ejecuta las instrucciones SQL correspondientes en el motor de base de datos activo.

Recomendación: mantén tus migraciones sincronizadas y commiteadas en tu repositorio Git. Evita alterar campos o borrar atributos sin generar previamente su correspondiente migración con makemigrations, ya que podrías romper la consistencia entre el código y la base de datos.

Registro y gestión en el panel de administración de Django

Una de las grandes ventajas de Django frente a otros frameworks es su panel administrativo listo para producción (django.contrib.admin). Para gestionar tus nuevos modelos desde la interfaz visual, solo debes registrarlos en el archivo admin.py de tu aplicación:

from django.contrib import admin
from .models import Category, Type, Element

admin.site.register(Category)
admin.site.register(Type)
admin.site.register(Element)

Tras iniciar el servidor con python manage.py runserver y entrar en la ruta /admin con tu usuario administrador, podrás crear, consultar, modificar y eliminar registros de Category, Type y Element con formularios generados automáticamente.

El método mágico __str__: representación en texto de un modelo

Un detalle indispensable al trabajar con modelos es declarar el método __str__() de Python. Si no lo implementas e intentas imprimir una instancia o verla listada en el panel de administración, obtendrás una cadena genérica poco descriptiva:

<Comment: Comment object (1)>

Donde Comment es la clase y (1) es su clave primaria (id).

Al sobreescribir __str__() en tu clase, decides qué información representará al registro cuando se convierta a cadena de texto:

class Comment(models.Model):
    text = models.TextField()
    date_posted = models.DateTimeField(auto_now_add=True)
    element = models.ForeignKey(Element, related_name='comments', on_delete=models.CASCADE, null=True)

    def __str__(self):
        return f'Comentario #{self.id}'

De este modo, cuando invoques print(comentario) o cuando Django liste el registro en un selector del admin, se visualizará limpiamente como:

Comentario #1

Dentro de __str__() tienes acceso a cualquier atributo de la instancia (como self.title, self.id o self.slug), lo que aporta claridad tanto en consola como en la interfaz gráfica.

⚠️ Errores comunes y buenas prácticas al diseñar modelos

  • Confundir null=True y blank=True: recuerda que null=True aplica a nivel de base de datos (permite valores NULL en la columna), mientras que blank=True aplica a nivel de validación de formularios en Django.
  • Olvidar implementar __str__(): sin este método, tus listados en el panel de administración y tus registros en el depurador serán mucho más difíciles de identificar.
  • Modificar un modelo y no migrar: cada vez que agregues, renombres o retires un atributo en models.py, debes ejecutar inmediatamente python manage.py makemigrations y python manage.py migrate.
  • Elegir mal el tipo numérico: para precios e importes financieros, usa siempre DecimalField en lugar de FloatField para evitar problemas de precisión en operaciones matemáticas.

Conclusión

Los modelos son el corazón de toda aplicación en Django. A través de ellos defines la arquitectura de datos, estableces relaciones sólidas y aprovechas al máximo el ORM para mantener un código limpio, seguro y desacoplado del motor SQL subyacente.

Invertir tiempo en estructurar adecuadamente tus modelos y sus relaciones en models.py garantiza que tu proyecto sea escalable y fácil de mantener a medida que crezca en complejidad.

❓ Preguntas frecuentes (FAQ)

  • ¿Qué diferencia hay entre un modelo y una migración en Django?
    • El modelo es la definición de tu entidad en código Python (dentro de models.py); la migración es el archivo generado que traduce esos cambios a instrucciones SQL para crear o modificar las tablas reales en la base de datos.
  • ¿Qué es el ORM de Django y qué ventajas ofrece?
    • El ORM (Object-Relational Mapping) permite interactuar con la base de datos utilizando objetos y métodos de Python en lugar de escribir consultas SQL directamente. Esto aporta portabilidad entre diferentes motores (SQLite, PostgreSQL, MySQL) y previene inyecciones SQL por defecto.
  • ¿Cómo relacionar modelos entre sí en Django?
    • Puedes utilizar models.ForeignKey para relaciones de uno a muchos, models.OneToOneField para relaciones de uno a uno, o models.ManyToManyField para relaciones de muchos a muchos.
  • ¿Dónde se define el archivo models.py?
    • Se localiza en la raíz de cada aplicación de Django. Cada aplicación puede tener su propio models.py con sus respectivas entidades.
  • ¿Qué comandos se emplean para aplicar cambios de base de datos?
    • Se ejecuta primero python manage.py makemigrations para registrar el cambio en un archivo de migración, y luego python manage.py migrate para impactarlo en la base de datos.
  • ¿Cuál es la diferencia entre null=True y blank=True en un campo de modelo?
    • null=True indica que la columna de la base de datos puede almacenar un valor NULL, mientras que blank=True determina si el campo es opcional en la validación de formularios y en el panel de administración.

El siguiente paso consiste en descubrir cómo configurar y conectar una base de datos MySQL en un proyecto Django.

Aprende qué son los modelos en Django, cómo crearlos en models.py, definir tipos de campos, usar el ORM y sincronizar tu base de datos con migraciones paso a paso.


Únete a la comunidad de desarrolladores que han decidido dejar de picar código y empezar a construir productos reales. Recibe mis mejores trucos de arquitectura cada semana:

Acepto recibir anuncios de interes sobre este Blog.