Triggers¶
Lógica de negocio declarada como métodos de la tabla. El generador los transpila e inlinea en los DAOs: no son triggers de la base de datos y no tienen coste en runtime.
class Post(Table):
__tablename__ = 'post'
id: col[bigint] = column(primary_key=True, autoincrement=True)
titulo: col[str]
estado: col[Estado] = column(default=Estado.BORRADOR)
publicado_en: col[datetime | None]
autor_id: col[int]
autor: manytoone[Usuario] = relation(
fields=['autor_id'], references=['id'], backref='posts'
)
@on_update(timing='before', fields=['estado'],
when=lambda t: t.new.estado == 'publicado')
def sellar_publicacion(self, t: TriggerAPI[Post]):
"""Al pasar a publicado, sella la fecha."""
t.new.publicado_en = datetime.now()
@on_create(timing='after')
def actualizar_autor(self, t: TriggerAPI[Post]):
"""Deja constancia en el autor de su último post."""
t.update(Usuario, self.autor_id, ultimo_post=datetime.now())
Los tres decoradores¶
@on_create(timing='before', priority=1, when=None)
@on_update(timing='before', priority=1, fields=None, when=None)
@on_delete(timing='before', priority=1, when=None)
| Parámetro | Qué hace |
|---|---|
timing |
'before' (antes de escribir; puede modificar t.new o abortar) o 'after' (después, con la fila ya persistida y su id asignado). |
priority |
Orden cuando hay varios triggers del mismo evento. Menor = primero. |
fields |
Solo en @on_update: lista de campos que activan el trigger. Sin ella, se ejecuta en cualquier update. |
when |
Condición. Recibe la TriggerAPI y devuelve bool; si es False, el trigger no se ejecuta. |
t.new y t.old¶
@on_create |
@on_update |
@on_delete |
|
|---|---|---|---|
t.new |
la fila que se va a crear | los valores nuevos | ❌ |
t.old |
❌ | los valores anteriores | la fila que se va a borrar |
Usar el lado que no existe es un error de importación
t.old en un @on_create, o t.new en un @on_delete, es un SyntaxError al importar el
schema. Es intencional: en esos eventos ese lado no existe, y descubrirlo en producción es
peor.
La API dentro del trigger¶
Todo lo que hace un trigger va en la misma transacción que la operación que lo disparó.
t.create(Modelo, **datos) # → instancia creada
t.create_many(Modelo, records) # → lista de instancias creadas
t.update(Modelo, id, **datos) # → int
t.update_many(Modelo, filters, **datos) # → int
t.upsert(Modelo, match_fields, update_columns=None, **datos) # → instancia
t.upsert_many(Modelo, records, match_fields, update_columns=None) # → int
t.delete(Modelo, id) # → int
t.delete_many(Modelo, **filtros) # → int
t.upsert y t.upsert_many escriben lo que se les pasa: una clave con None es un NULL
y una que no se pasa no se toca si el registro ya existía. update_columns es un nombre
reservado, como match_fields. Ver Upsert.
Las operaciones de consulta, escritura y agregación se pueden usar en cualquier expresión:
asignadas a una variable, como iterable de un for, en la condición de un if o como
argumento de otra llamada. t.log() y t.abort() van siempre como sentencia, en su propia
línea.
for libro in t.find_many(Libro, autor_id=t.old.id):
if t.exists(Resena, libro_id=libro.id):
t.log(f'«{libro.titulo}» tenía reseñas')
Dos excepciones, porque el cliente async antepone un await a cada operación: no pueden ir
dentro de una lambda, de una expresión generadora (sum(t.count(...) for x in xs)) ni de
una función anidada que no sea async. Usa una comprensión de lista
(sum([t.count(...) for x in xs])) o guarda antes el resultado en una variable.
El nombre t se puede reutilizar en un ámbito interno —[t.strip() for t in etiquetas],
lambda t: t.activo—: ahí es otra variable y se deja como está.
return sale del hook, no solo del trigger
El cuerpo de cada trigger se copia, uno tras otro, dentro del mismo método del DAO
generado. Un return en el cuerpo sale de ese método: se salta los triggers que
vienen detrás en el mismo momento (before/after) y las cascadas a las relaciones.
Para terminar antes un trigger, encierra el resto en un if.
Lo que no se puede transpilar falla al generar
El cuerpo del trigger se transpila al DAO generado, donde t no existe. Una operación mal
formada —t.update_many sin filtros, t.find sin id—, un método que TriggerAPI no tiene
o t pasado como valor a otra función hacen que tai-sql generate se detenga con un error
que nombra el trigger y la expresión. Hasta la 0.7.18 se quedaban tal cual y fallaban al
ejecutar el trigger. Y el código ya transpilado se compila antes de escribirlo: si no es
Python válido, el error sale también al generar, con el nombre del trigger, y no como un
DAO que no se puede importar.
Validar y abortar¶
class Pedido(Table):
__tablename__ = 'pedido'
@on_create(timing='before')
def comprobar_stock(self, t: TriggerAPI[Pedido]):
producto = t.find(Producto, self.producto_id)
if producto is None or producto.stock < self.unidades:
t.abort('No hay stock suficiente')
t.abort() lanza TriggerAborted: la operación no se aplica y la transacción se deshace entera.
Es una regla de negocio, no un fallo, y se captura como tal:
from database.public import TriggerAborted
try:
public_sync_api.pedido.create(PedidoCreate(producto_id=3, unidades=50))
except TriggerAborted as error:
error.message # 'No hay stock suficiente', tal como lo escribió el trigger
Es un ValueError, que es lo que se lanzaba hasta la 0.7.11, así que el código que ya lo
capturaba así sigue funcionando. tai-api la
convierte en un 422 BUSINESS_RULE_VIOLATION con ese mensaje.
Cascadas en la aplicación¶
class Post(Table):
@on_delete(timing='before')
def borrar_comentarios(self, t: TriggerAPI[Post]):
t.delete_many(Comment, post_id=t.old.id)
¿Trigger o ON DELETE CASCADE?
Si lo único que quieres es que se borren las filas hijas, declara onDelete='cascade' en la
relación: lo impone la base de datos y es más barato. Un trigger es para lo
que la base de datos no sabe hacer: escribir en otra tabla, recalcular un agregado, avisar.
Cómo afectan a las operaciones masivas¶
Una tabla con triggers no puede usar los caminos rápidos:
| Método | Sin triggers | Con triggers |
|---|---|---|
create_many |
inserción masiva | inserta y ejecuta los hooks fila a fila |
upsert_many |
INSERT ... ON CONFLICT nativo |
separa altas y modificaciones, y delega en create_many() y update() |
Es el precio de que los triggers se ejecuten siempre. Si una tabla recibe cargas masivas y su trigger no es imprescindible, piénsalo dos veces.
tai-sql pull no los puede reconstruir
Un trigger de tai-sql no existe en la base de datos: vive en el schema y en el cliente generado.