9. Arquitectura en capas y acceso a datos
Los ejemplos anteriores mantenían sus datos en memoria. Una aplicación real los almacena en una base de datos y está organizada en capas (véase el diagrama de la introducción):
- la capa web (vistas, formularios, plantillas): lee la solicitud, llama a la capa de negocio, selecciona la plantilla;
- la capa de negocio: las reglas de negocio;
- la capa DAO (Data Access Object): las consultas a la base de datos.
Cada capa conoce solo la capa inferior, y con la menor cantidad de detalles posible: la capa web desconoce las consultas, y la capa de negocio desconoce el HTML. Esta separación hace que cada capa sea más fácil de entender, probar y evolucionar. El ejemplo 28 aplica esto a la gestión de una lista de personas: es, a menor escala, la gestión de médicos y clientes del caso de estudio.
En [Python], el acceso a las bases de datos se organiza en varias capas:
- el estándar DB-API 2.0 (PEP 249) de [Python] define una interfaz común para todos los SGBD: abrir una conexión, obtener un cursor, ejecutar un comando SQL y leer filas. Cada SGBD tiene su propio controlador: para [MySQL] (y [MariaDB]), [Django] recomienda [mysqlclient], una biblioteca escrita en C, instalada por el archivo de ejemplo [requirements.txt] ;
- el ORM (Object-Relational Mapper) de [Django] asigna clases (modelos) a tablas de la base de datos y convierte las filas leídas en objetos. Gestiona las conexiones y las transacciones, genera por sí mismo los comandos SQL —adaptados a cada SGBD— y traduce los errores de cada controlador en excepciones comunes (una violación de una restricción de unicidad se convierte en una [IntegrityError], sea cual sea el SGBD). Sigue el llamado patrón Active Record: cada objeto sabe cómo guardarse ([person.save()]) y eliminarse ([person.delete()]), y cada clase tiene un gestor ([Person.objects]) desde el cual se envían las consultas. Este es el modelo de [Eloquent], el ORM de [Laravel]; [Doctrine], el ORM derivado de [Symfony], en cambio, siguió el patrón Data Mapper, en el que un objeto separado lee y guarda las entidades.
El ORM, derivado de [Django], forma parte de [Django] y es uno de sus componentes clave: la interfaz de administración, la aplicación de autenticación, las sesiones en base de datos y las vistas genéricas se apoyan en él. Es el equivalente de [JPA] y [Hibernate] en [Java], de [Entity Framework Core] para [C#], o de [SQLAlchemy] (usado con [Flask]) para [Python]. Observe una consecuencia de cómo funciona [Django]: de forma predeterminada, cada solicitud abre su propia conexión a la base de datos (en su primera solicitud SQL) y la cierra al terminar (con la señal [request_finished], ejemplo 24). El ajuste [CONN_MAX_AGE] permite que las conexiones permanezcan abiertas de una solicitud a otra (conexiones persistentes), y [Django] 5.1 agregó un verdadero pool de conexiones para [PostgreSQL]. Abrir una conexión a [MySQL] en la misma máquina toma apenas unos milisegundos.
Este ejemplo requiere un servidor [MySQL] 8.4 o posterior en ejecución (o [MariaDB] 10.11 o posterior; las versiones mínimas son las de [Django] 6.1): el apéndice explica cómo instalar uno con [Laragon].
9.1. Ejemplo 28: un sistema de gestión de personal en tres capas
9.1.1. La base de datos
La base de datos [dbpersons] se crea mediante el script SQL. Con [Laragon], se puede ejecutar, por ejemplo, en la herramienta [HeidiSQL] (menú Archivo / Ejecutar un archivo SQL), o desde la línea de comandos, en la carpeta del ejemplo:
El archivo [database/dbpersons.sql]:
- línea 3: el script está escrito en [UTF-8]; esto se indica al servidor para que los acentos de los datos ([Pélissier]) permanezcan intactos;
- línea 5: el conjunto de caracteres [utf8mb4] acepta todos los caracteres (acentos, emojis, etc.). La collation [utf8mb4_unicode_ci] compara las cadenas sin distinguir entre mayúsculas y minúsculas ni acentos: para [MySQL], [pelissier] y [Pélissier] son iguales;
- línea 11: un número de versión, incrementado cada vez que se modifica la fila (véase «bloqueo optimista», más abajo);
- línea 17: una restricción de unicidad con nombre: la base de datos no permite dos personas con el mismo nombre y apellido.
[Django] también puede crear las tablas por sí mismo, a partir de los modelos, mediante migraciones: archivos [Python] que describen, paso a paso, la creación y las modificaciones de cada tabla. El comando [python manage.py makemigrations] escribe estos archivos comparando los modelos con el estado descrito por las migraciones anteriores; [python manage.py migrate] las aplica a la base de datos. Esta es la forma estándar de trabajar con [Django]. Aquí mantenemos un script SQL, común a todas las versiones del caso de estudio, que muestra exactamente lo que contiene la base de datos. A la inversa, el comando [python manage.py inspectdb] escribe los modelos de una base de datos existente: un buen punto de partida, que conviene revisar.
9.1.2. La configuración: config/settings.py
- líneas 21–26: el middleware del ejemplo 21: protección anti-CSRF, mensajes flash y la simulación de los métodos PUT y DELETE (el archivo [config/middleware.py] es el del ejemplo 21);
- líneas 32–42: la configuración [DATABASES] describe las bases de datos de la aplicación: en este caso, una sola, la base de datos [default]. [ENGINE] hace referencia al motor de [Django] para [MySQL] (que usa el controlador [mysqlclient]); seguido del nombre de la base de datos, el nombre de usuario y la contraseña (en blanco con la configuración de [Laragon]: si su servidor tiene contraseña, escríbala aquí), el nombre del host y el puerto. [OPTIONS] pasa al controlador el conjunto de caracteres para la comunicación con el servidor, que es el de la base de datos;
- líneas 44–55: las plantillas, con [APP_DIRS] para las plantillas de formulario (ejemplo 18) y el procesador de contexto de mensajes (ejemplo 20);
- líneas 67–74: el ajuste [LOGGING] configura el registro de [Python] (el módulo [logging]), que [Django] usa para sus mensajes. Sigue el formato del módulo [logging.config]: destinos ([handlers]: en este caso, la consola, mediante un [StreamHandler], que escribe en la salida de error) y registros ([loggers]), identificados por sus nombres. El registro [django.db.backends] recibe, solo en modo de depuración, cada comando SQL enviado a la base de datos, junto con su duración: lo enviamos a la consola en el nivel [DEBUG] (el más detallado). [disable_existing_loggers: False] conserva los registros que [Django] configura por sí mismo.
No hay nada más que configurar: los módulos de las tres capas se importan entre sí (la capa web importa la capa de negocio, que importa la capa DAO), y el ORM establece por sí mismo la conexión con la base de datos cuando la necesita.
9.1.3. El modelo Person: persons/models.py
El archivo se llama [models.py]: es donde [Django] busca los modelos de una aplicación declarada en [INSTALLED_APPS].
- línea 8: un modelo es una clase que hereda de [models.Model];
- línea 10: la clave primaria, generada por la base de datos ([AutoField]: el [AUTO_INCREMENT] de [MySQL]). [Django] la agregaría automáticamente si no estuviera declarada (un campo [id], del tipo elegido por el ajuste [DEFAULT_AUTO_FIELD]); la incluimos aquí para mayor claridad. Es igual a [None] hasta que el objeto se ha insertado;
- línea 12: la versión de la fila. El ORM de [Django] no tiene un bloqueo optimista integrado: lo escribe la capa DAO (véase más abajo);
- líneas 14–16: las columnas. Cada atributo de clase que es un campo del modelo ([models.XxxField]) corresponde a la columna del mismo nombre; el tipo de columna se infiere del tipo de campo ([CharField]: [VARCHAR], de longitud [max_length]; [IntegerField]: [INT]). Como en un formulario (ejemplo 08), los campos se declaran como atributos de la clase, pero no son los mismos campos: los de [django.db.models] describen columnas, mientras que los de [django.forms] describen campos de formulario;
- líneas 19–25: la clase interna [Meta] proporciona información sobre el propio modelo. [db_table]: el nombre de la tabla (de lo contrario, [Django] tomaría el nombre de la aplicación seguido del nombre del modelo, [persons_person]). [managed = False]: la tabla ya existe y [Django] no la gestiona: [makemigrations] no generará ninguna migración de creación ni de modificación para ella. [ordering]: el orden de las filas cuando una consulta no especifica ninguno;
- líneas 28–29: el método [__str__] (ejemplo 12) devuelve el texto que representa al objeto: [str(p)], o [{p}] en una f-string, devuelve [Marie Pélissier].
Un modelo es una clase ordinaria a la que se pueden agregar métodos y propiedades. El ORM, por su parte, completa los atributos a partir de las filas leídas y genera los comandos SQL a partir de los atributos.
9.1.4. La capa DAO: persons/dao.py
La capa DAO contiene solo consultas, sin reglas de negocio. Cada función comienza con [Person.objects], el administrador del modelo, del cual parten todas las consultas.
- Líneas 11–12: [all()] devuelve un [QuerySet]: un objeto que describe una consulta sin ejecutarla. La consulta se envía a la base de datos solo cuando se necesitan sus resultados (aquí, cuando [list] los recorre): se dice que un [QuerySet] es diferido (lazy). Por lo tanto, se puede enriquecer antes de ejecutarlo ([filter], [exclude], [order_by]...), y cada método devuelve un nuevo [QuerySet]. El orden es el de [Meta.ordering];
- Líneas 16–17: [filter(id=id)] agrega la condición [WHERE id = ...]; [first()] ejecuta la consulta, limitada a una fila ([LIMIT 1]), y devuelve el primer objeto, o [None]. ([Person.objects.get(id=id)] devolvería el objeto, pero lanzaría la excepción [Person.DoesNotExist] si no existiera, y el atajo [get_object_or_404], ejemplo 03, devolvería un error 404);
- Líneas 22–23: varias condiciones en [filter] se combinan con [AND]; [exclude] agrega una condición [NOT]. Los parámetros con nombre se refieren a los campos ([first_name=...]); los sufijos especifican la comparación: [age__gte=18] ([>=]), [last_name__startswith="P"], [last_name__iexact=...] (sin distinguir mayúsculas de minúsculas)... Los valores se transmiten a la base de datos por separado y nunca se copian en el texto de la instrucción SQL, lo que hace imposible la inyección SQL;
- líneas 27–28: [create] construye el objeto y lo guarda ([INSERT]); después de la inserción, el ORM almacena en el objeto el identificador generado por la base de datos. Esto equivale a [p = Person(first_name=..., ...)] seguido de [p.save()];
- líneas 35–38: la actualización, con su bloqueo optimista. [update] actualiza todas las filas especificadas por el [QuerySet] en una sola operación, con un único comando [UPDATE], y devuelve el número de filas actualizadas. El filtro tiene dos condiciones: el identificador y la versión leída. Si otra solicitud ha modificado la fila entretanto —lo que hace cambiar su versión—, [UPDATE] no modifica ninguna fila y la función devuelve [False]. Este es el principio del bloqueo optimista: no se bloquea nada, pero se detectan las modificaciones concurrentes. La expresión [F("version") + 1] se refiere a la propia columna, en la instrucción SQL ([version = version + 1]): el cálculo lo realiza la base de datos, no [Python] a partir de un valor leído con anterioridad;
- Líneas 42–43: la eliminación: [delete()] envía el [DELETE] de la fila del objeto.
A diferencia de [Doctrine], el ORM de [Django] no tiene un gestor que compare cada objeto leído con su estado original para guardar solo las columnas modificadas: [save()] reescribe todas las columnas del objeto (o las de su parámetro [update_fields]). Esto es más simple y más predecible; [update] permite escribir exactamente la instrucción deseada.
9.1.5. La capa de negocio: persons/business.py
- líneas 12–14: mensajes de las reglas de negocio;
- líneas 18–19: una clase de excepción propia de la capa de negocio: una regla de negocio rechaza la operación, y el mensaje de la excepción está destinado al usuario. Hereda de [Exception] sin añadirle nada; solo importa su nombre;
- líneas 23–27: los datos de una persona, tal como la capa web los transmite a la capa de negocio: un objeto simple, independiente de [Django];
- líneas 34–38: una persona inexistente es un error de negocio;
- líneas 44–52: regla n.º 1: no puede haber dos personas con el mismo nombre y apellido. La regla se verifica antes de escribir en la base de datos, y se lanza una excepción [BusinessError] si no se cumple. Pero esta verificación no es suficiente: dos solicitudes simultáneas podrían verificar ambas que no hay homónimo y luego proceder las dos a insertar el registro. La restricción de unicidad de la base de datos rechaza entonces el segundo [INSERT], y el ORM lanza un [IntegrityError], que se transforma en el mismo [BusinessError]. La base de datos es la última línea de defensa. [raise ... from e] vincula la excepción original con la nueva: el registro mostrará ambas;
- líneas 55–70: regla n.º 2: no modificar un registro que otra persona ha modificado entretanto. El formulario de actualización lleva la versión del registro leída (en un campo oculto); si difiere de la versión actual, el registro cambió desde que se mostró. Queda el caso en que la modificación concurrente ocurre entre la lectura de la línea 58 y el guardado de la línea 66: lo detecta el bloqueo optimista de la capa DAO. La función vuelve entonces a leer el registro de la persona para devolver la nueva versión;
- líneas 73–77: la eliminación deja a la persona como «eliminada» para el mensaje de confirmación.
Toda operación que escribe datos se ejecuta dentro de una transacción: [transaction.atomic()], utilizado con [with] (un administrador de contexto, ejemplo 20), abre una transacción ([BEGIN]) al comienzo del bloque; si el bloque termina con normalidad (incluso con un [return]), la transacción se confirma ([COMMIT]); si se produce una excepción dentro del bloque, la transacción se revierte ([ROLLBACK]): no se conserva ninguno de los cambios realizados en el bloque, y la excepción sigue su camino. [transaction.atomic] también puede usarse como decorador de una función completa ([@transaction.atomic]). La capa de negocio determina así el alcance de las transacciones: una operación de negocio equivale a una transacción. Fuera de un bloque [atomic], el ORM funciona en modo «autocommit»: cada instrucción SQL se confirma de inmediato. Un [IntegrityError] se intercepta fuera del bloque [with]: dentro del bloque, la transacción ya no sería utilizable después del error. Las demás excepciones (como una falla de la base de datos o un error de programación) no son errores de negocio: siguen su curso.
9.1.6. La capa web
La entrada de datos se describe mediante un formulario (ejemplo 19):
- líneas 9–17: los campos y sus restricciones, con mensajes en inglés;
- líneas 20–26: un parámetro adicional del constructor, [edit], especificado por nombre ([PersonForm(request.POST, edit=True)]): un parámetro escrito después de [*args] solo puede pasarse por nombre. El formulario de actualización recibe un campo adicional, «version», en un campo oculto: [self.fields] es un diccionario al que se le puede agregar un campo;
- líneas 30–32: los datos validados, en el formato esperado por la capa de negocio.
[Django] también puede generar un formulario a partir de un modelo (la clase [forms.ModelForm]): sus campos y sus restricciones se derivan de las columnas, y su método [save()] guarda el objeto. Esto es muy común. Sin embargo, el formulario modificaría entonces el modelo antes de que la capa de negocio haya verificado sus reglas. Un formulario separado mantiene las capas distintas: la capa web transmite a la capa de negocio solo datos validados.
- línea 8: la capa de negocio, la única capa que conoce la capa web;
- líneas 25–40: el alta, en tres pasos: validación del formulario (errores de entrada, ejemplo 19); llamada a la capa de negocio (reglas de negocio); y luego el esquema PRG, con un mensaje flash de éxito (ejemplo 20). Un [BusinessError] vuelve a mostrar el formulario, junto con los datos ingresados y el mensaje de la excepción ([str(e)]), que la plantilla mostrará al final de la página. Los errores de entrada y los errores de lógica de negocio se tratan así de la misma manera;
- líneas 44–54: el formulario de edición, rellenado con la persona recuperada (parámetro [initial], ejemplo 18). Si la persona no existe, se redirige a la lista con un mensaje flash de error ([messages.error]). El formulario se envía con el método PUT (el campo oculto [_method], ejemplo 21), a la URL [/persons/<id>] ([reverse], con los parámetros de la ruta en [args]);
- líneas 58–78: la vista de [/persons/<id>], para los métodos PUT (actualización, con el mismo esquema que el alta) y DELETE (eliminación, protegida por el token anti-CSRF, ejemplo 21). En la eliminación no hay formulario que volver a mostrar: cualquier error también se comunica mediante un mensaje flash;
- líneas 83–86: la página del formulario. Un error de negocio se devuelve con el código 422, igual que un formulario no válido.
La capa web no contiene ni SQL ni reglas de negocio: traduce la solicitud en una llamada a la capa de negocio y el resultado en una página. Las rutas ([persons/urls.py]): [/persons] (la lista), [/persons/add], [/persons/<id>/edit] y [/persons/<id>] (PUT y DELETE).
Las plantillas:
- líneas 14–16: los mensajes flash en la parte superior de la página (ejemplo 20). Su etiqueta ([message.tags]: [success], [error]) determina su color;
- línea 20: el bloque del pie de página, donde las páginas muestran sus errores (ejemplo 19);
- líneas 22–23: la ventana de confirmación y su script (ejemplo 21).
La lista incluye los enlaces y botones del ejemplo 21, junto con su ventana de confirmación (los archivos [fragments/confirmation.html] y [static/js/app.js] son los del ejemplo 21). Los atributos [p.first_name], [p.last_name]... son los de los objetos [Person] leídos por el ORM. El bloque [{% empty %}] (ejemplo 14) procesa la lista vacía.
Una plantilla común para el alta y la modificación:
- línea 8: el campo oculto [_method], solo para la modificación;
- línea 13: el campo oculto de la versión, si existe en el formulario;
- líneas 21–25: el error de negocio, al final de la página.
9.1.7. Ejecución
La lista de personas:

Un formulario de alta completado incorrectamente: los errores de entrada los detecta la capa web.

Un homónimo: la entrada es correcta, pero la capa de negocio rechaza el alta. Como la comparación la realiza la base de datos, esta ignora tanto las mayúsculas como los acentos: [marie pelissier] es un homónimo de [Marie Pélissier].

Un alta exitosa:

Para probar la regla n.º 2, abramos el mismo registro en dos pestañas. En la primera pestaña, cambiemos la edad y guardemos. En la segunda pestaña, que todavía muestra la versión anterior, modifiquemos también el registro:

La eliminación, con su confirmación:


9.1.8. Los comandos SQL
Sigamos en la consola los comandos SQL de una modificación (se reinició el servidor y se recreó la base de datos). La visualización del formulario de modificación de la persona n.º 1:
Cada línea muestra la duración del comando (en segundos), el comando SQL, sus parámetros ([args]) y el nombre de la base de datos ([alias]). Los dos primeros comandos sirven para establecer la conexión: [Django] consulta al servidor (su versión, su configuración) y luego establece el nivel de aislamiento de las transacciones ([READ COMMITTED]: una transacción ve los cambios confirmados por otras). A continuación viene la lectura por clave primaria, con su [ORDER BY] (correspondiente a [Meta.ordering]) y su [LIMIT 1] (correspondiente a [first()]). En el registro, los parámetros se copian en orden para que puedan leerse; originalmente se envían por separado ([args]). No hay transacción: una lectura aislada no la requiere. Se guarda el registro del maestro con una nueva edad:
(la conexión ya estaba abierta, como en la solicitud anterior). Dentro de una sola transacción ([BEGIN] ... [COMMIT]), se ven: la lectura del registro, la búsqueda de un homónimo, el [UPDATE] y luego la nueva lectura del registro. El [UPDATE] incrementa la versión ([version + 1]) y establece la condición del bloqueo optimista ([AND version = 0]). El servidor de desarrollo registra la solicitud como POST: así llegó, antes de que el middleware la convirtiera en PUT. Ahora enviemos el mismo formulario por segunda vez, siempre con la versión anterior:
La versión leída no es la del formulario: la capa de negocio lanzó un [BusinessError], que revirtió la transacción ([ROLLBACK]), y la página muestra «This record has been modified meanwhile: reload it.» De igual modo, el alta de un homónimo se detiene después de la búsqueda del homónimo, sin ningún [INSERT].