Saltar a contenido

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.find(Modelo, id, includes=None)                    # → instancia | None
t.find_many(Modelo, limit=None, offset=None,
            order_by=None, order='ASC',
            includes=None, **filtros)                # → List[instancia]
t.count(Modelo, **filtros)                           # → int
t.exists(Modelo, **filtros)                          # → bool
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.

t.sum(Modelo, agg_fields, **filtros)
t.mean(Modelo, agg_fields, **filtros)
t.max(Modelo, agg_fields, **filtros)
t.min(Modelo, agg_fields, **filtros)
t.agg(Modelo, request, **filtros)
t.log('mensaje', level='info')     # al logger del cliente generado
t.abort('motivo')                  # lanza TriggerAborted y deshace la transacción

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.