SQL database management and code generation tool

These details have not been verified by PyPI

Project links

Project description

🚀 TAI-SQL Framework

TAI-SQL es un framework declarativo para Python que simplifica el trabajo con bases de datos relacionales usando SQLAlchemy. Permite definir esquemas de forma intuitiva y generar automáticamente modelos, CRUDs y diagramas ER.

⚡ Quickstart

# 1. Instalar tai-sql
pip install tai-sql

# 2. Crear proyecto
tai-sql init --name mi-proyecto --schema public
cd mi-proyecto

# 3. Configurar conexión
export MAIN_DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

# 4. Instalar dependencias del proyecto generado
tai-sql install

Define tu schema en schemas/public.py:

from __future__ import annotations
from tai_sql import *
from tai_sql.generators import *

datasource(provider=env('DATABASE_URL'))

generate(
    PythonClientGenerator(output_dir='mi_proyecto'),
    ERDiagramGenerator(output_dir='mi_proyecto/diagrams')
)

class Usuario(Table):
    __tablename__ = "usuario"
    id: int = column(primary_key=True, autoincrement=True)
    nombre: str
    email: str = column(unique=True)
    posts: List[Post]

class Post(Table):
    __tablename__ = "post"
    id: int = column(primary_key=True, autoincrement=True)
    titulo: str
    contenido: str
    usuario_id: int
    usuario: Usuario = relation(fields=['usuario_id'], references=['id'], backref='posts')

# 5. Sincronizar con la BD y generar código
tai-sql push

# 6. Usar el CRUD generado

from mi_proyecto.public import public_sync_api, UsuarioCreate

user = public_sync_api.usuario.create(UsuarioCreate(nombre="Ana", email="ana@example.com"))
users = public_sync_api.usuario.find_many(limit=10)

📑 Índice de contenidos

Instalación
Schema
- Estructura típica de un schema
- Concepto clave
Elementos del Schema
Generadores Incluidos
- PythonClientGenerator
- ERDiagramGenerator
Comandos CLI
Crear tu Propio Generador

📦 Instalación

TAI-SQL se instala con pip. Solo incluye las dependencias mínimas necesarias para definir schemas y ejecutar el CLI:

pip install tai-sql

Esto instala: sqlalchemy, psycopg2-binary, click, jinja2, pydantic.

Extras opcionales

Funcionalidades adicionales se instalan según necesidad:

# Generar diagramas ER
pip install tai-sql[diagrams]

# Columnas encriptadas (encrypt=True en schema)
pip install tai-sql[encryption]

# Deploy vía GitHub PRs
pip install tai-sql[deploy]

# Backup/restore de base de datos
pip install tai-sql[backup]

# Columnas vector (pgvector + sentence-transformers)
pip install tai-sql[vectors]

# Todo incluido
pip install tai-sql[all]

Dependencias del sistema

Para generar diagramas ER (extra diagrams), necesitas instalar Graphviz en el sistema:

# Ubuntu/Debian
sudo apt install graphviz

# macOS
brew install graphviz

# Windows
# Descargar desde: https://graphviz.org/download/

🗂️ Schema

Un schema es un archivo Python que define la estructura completa de tu base de datos. Es el punto central donde configuras la conexión, defines tus modelos y especificas qué recursos se generarán automáticamente.

📁 Estructura típica de un schema

# schemas/mi_proyecto.py
from __future__ import annotations
from tai_sql import *
from tai_sql.generators import *

# 1️⃣ Configurar conexión a la base de datos
datasource(provider=env('DATABASE_URL'))

# 2️⃣ Configurar generadores
generate(
    PythonClientGenerator(output_dir='mi_proyecto'),
    ERDiagramGenerator(output_dir='mi_proyecto/diagrams')
)

# 3️⃣ Definir modelos (Tablas y Vistas)
class Usuario(Table):
    '''Tabla que almacena información de los usuarios del sistema'''
    __tablename__ = "usuario"
    
    id: int = column(primary_key=True, autoincrement=True)
    nombre: str
    pwd: str = column(encrypt=True)
    email: str = column(unique=True)
    
    posts: List[Post]  # Relación implícita

class Post(Table):
    '''Tabla que almacena los posts de los usuarios'''
    __tablename__ = "post"
    
    id: int = column(primary_key=True, autoincrement=True)
    titulo: str = 'Post title'
    contenido: str
    timestamp: datetime = column(default=datetime.now)
    usuario_id: int
    
    # Relación explícita
    usuario: Usuario = relation(
        fields=['usuario_id'],
        references=['id'], 
        backref='posts'
    )

class UserStats(View):
    '''Vista que muestra estadísticas de los usuarios'''
    __tablename__ = "user_stats"
    __query__ = query('user_stats.sql')

    usuario_id: int
    nombre_usuario: str
    post_count: int

🎯 Concepto clave

El schema actúa como el "blueprint" de tu aplicación:

Define la estructura de base de datos (tablas, vistas, tipos, etc...)
Configura la conexión y parámetros
Especifica qué código se generará automáticamente
Centraliza toda la configuración en un solo lugar

Una vez definido, el CLI de TAI-SQL usa este schema para:

Sincronizar la base de datos (tai-sql push)
Generar modelos SQLAlchemy, CRUDs y diagramas (tai-sql generate)
Poblar la base de datos con datos iniciales (tai-sql feed)

🏗️ Elementos del Schema

El esquema es el corazón de TAI-SQL. Define la estructura de tu base de datos y los recursos que se generarán automáticamente.

📊 `datasource()` - Configuración de la Base de Datos

La función datasource() configura la conexión a tu base de datos:

from tai_sql import datasource, env, connection_string, params

# ✅ Opción 1: Variables de entorno (Recomendado para producción)
datasource(
    provider=env('DATABASE_URL')  # postgres://user:pass@host:port/dbname
)

# ✅ Opción 2: String de conexión directo (Para desarrollo/testing)
datasource(
    provider=connection_string('postgresql://user:password@localhost/mydb')
)

# ✅ Opción 3: Parámetros individuales (Para desarrollo/testing)
datasource(
    provider=params(
        drivername='postgresql',
        username='user',
        password='password',
        host='localhost',
        port=5432,
        database='mydb'
    )
)

Opciones avanzadas:

datasource(
    provider=env('DATABASE_URL'),
    secret_key_name='SECRET_KEY',  # Variable de entorno para encriptación
    pool_size=20,           # Tamaño del pool de conexiones
    max_overflow=30,        # Conexiones adicionales permitidas
    pool_timeout=30,        # Timeout para obtener conexión
    pool_recycle=3600,      # Reciclar conexiones cada hora
    echo=True              # Mostrar consultas SQL en desarrollo
)

🔧 `generate()` - Configuración de Generadores

La función generate() define qué recursos se generarán automáticamente:

from tai_sql import generate
from tai_sql.generators import PythonClientGenerator, ERDiagramGenerator

generate(
    # Generar cliente Python (modelos + DAOs + DTOs + session)
    PythonClientGenerator(
        output_dir='database/database'
    ),
    # Generar diagramas ER
    ERDiagramGenerator(
        output_dir='database/diagrams'
    )
)

📋 `Table` - Definición de Tablas

Las tablas son la base de tu modelo de datos:

from __future__ import annotations
from tai_sql import Table, column, relation
from typing import List, Optional
from datetime import date

class Usuario(Table):
    '''Tabla que almacena información de los usuarios'''
    __tablename__ = "usuario"
    
    # Columnas básicas
    id: int = column(primary_key=True, autoincrement=True)
    name: str
    email: str = column(unique=True)
    fecha_alta: date
    
    # Relaciones
    posts: List[Post] # Implícita

class Post(Table):
    '''Tabla que almacena la información de los posts de los usuarios'''
    __tablename__ = "post"
    
    id: int = column(primary_key=True, autoincrement=True)
    title: str = 'Post title'
    content: str
    author_id: int
    published: Optional[bool]
    
    # Relación explícita
    author: Usuario = relation(
        fields=['author_id'], 
        references=['id'], 
        backref='posts'
    )

📝 Documentación de Tablas

TAI-SQL permite documentar las tablas de dos formas equivalentes para proporcionar contexto y descripción de cada modelo:

# Opción 1: Usando docstring de la clase
class Usuario(Table):
    '''Tabla que almacena información de los usuarios del sistema'''
    __tablename__ = "usuario"
    
    id: int = column(primary_key=True, autoincrement=True)
    name: str
    email: str

# Opción 2: Usando el metaparámetro __description__
class Post(Table):
    __tablename__ = "post"
    __description__ = "Tabla que almacena los posts de los usuarios"
    
    id: int = column(primary_key=True, autoincrement=True)
    title: str
    content: str

Prioridad

El uso del metaparámetro description tiene preferencia sobre el docstring de la clase. De esta forma si concurren ambos en una tabla, description tendrá prioridad.

Usos de la documentación:

📊 Diagramas ER: Aparece en los diagramas generados por ERDiagramGenerator

Ambas formas son equivalentes y permiten que los generadores accedan a la descripción de la tabla para crear documentación automática, comentarios en los modelos generados y descripciones en los diagramas ER.

🛠️ Función `column()` - Configuración de Columnas

La función column() permite configurar las propiedades específicas de las columnas:

def column(
    primary_key=False,      # Si es clave primaria
    unique=False,           # Si debe ser único
    default=None,           # Valor por defecto
    server_now=False,       # Para usar NOW() del servidor
    index=False,            # Si debe tener índice
    autoincrement=False,    # Si es autoincremental
    encrypt=False,          # Si queremos que se encripte
    description=''          # Descripción de la columna (para diagramas)
):

Ejemplos de uso:

class Producto(Table):
    __tablename__ = "producto"
    
    # Clave primaria autoincremental
    id: int = column(primary_key=True, autoincrement=True)
    
    # Campo único
    sku: str = column(unique=True)
    
    # Campo con valor por defecto
    estado: str = "activo"
    
    # Equivalente a
    estado: str = column(default="activo")
    
    # Campo con índice para búsquedas rápidas
    categoria: str = column(index=True)
    
    # Campo opcional (nullable automático por tipo Optional)
    descripcion: Optional[str]
    
    # Campo obligatorio (nullable=False automático)
    nombre: str

    # Campo encriptado (necesita una SECRET_KEY)
    password: str = column(encrypt=True)

Parámetros detallados:

Parámetro	Tipo	Descripción	Ejemplo
`primary_key`	`bool`	Define si la columna es clave primaria	`column(primary_key=True)`
`unique`	`bool`	Garantiza valores únicos en la columna	`column(unique=True)`
`default`	`Any`	Valor por defecto para nuevos registros	`column(default="activo")`
`server_now`	`bool`	Usa la función NOW() del servidor de BD	`column(server_now=True)`
`index`	`bool`	Crea un índice en la columna para búsquedas rápidas	`column(index=True)`
`autoincrement`	`bool`	Incrementa automáticamente el valor (solo integers)	`column(autoincrement=True)`
`encrypt`	`bool`	Encripta automáticamente el contenido de la columna	`column(encrypt=True)`
`description`	`str`	Descripción de la columna, usada en diagramas ER	`column(description='Nombre del usuario')`

🔗 Función `relation()` - Definición de Relaciones

La función relation() define relaciones explícitas entre tablas:

def relation(
    fields: List[str],          # Campos en la tabla actual (foreign keys)
    references: List[str],      # Campos referenciados en la tabla destino
    backref: str,              # Nombre de la relación inversa
    onDelete='cascade',        # Comportamiento al eliminar
    onUpdate='cascade'         # Comportamiento al actualizar
):

Conceptos importantes:

Relaciones Explícitas vs Implícitas:
- Explícita: Se define usando relation() en la tabla que CONTIENE la foreign key
- Implícita: Se declara solo con el tipo en la tabla que NO contiene la foreign key
Dónde usar relation():
- SOLO en la tabla que tiene la columna foreign key
- La tabla "origen" muestra la relación como List[...] (implícita)

Ejemplo completo:

class Usuario(Table):
    __tablename__ = "usuario"
    
    id: int = column(primary_key=True, autoincrement=True)
    nombre: str
    email: str = column(unique=True)
    
    # Relación IMPLÍCITA - Usuario NO tiene foreign key hacia Post
    # Se muestra automáticamente como List por la relación inversa
    posts: List[Post]  # ← No necesita relation()

class Post(Table):
    __tablename__ = "post"
    
    id: int = column(primary_key=True, autoincrement=True)
    titulo: str
    contenido: str
    autor_id: int  # ← Esta ES la foreign key
    
    # Relación EXPLÍCITA - Post SÍ tiene foreign key hacia Usuario
    autor: Usuario = relation(
        fields=['autor_id'],     # Campo FK en esta tabla
        references=['id'],       # Campo PK en tabla destino
        backref='posts'         # Nombre de relación inversa en Usuario
    )

Parámetros de relation():

Parámetro	Descripción	Ejemplo
`fields`	Lista de columnas FK en la tabla actual	`['autor_id']`
`references`	Lista de columnas PK en la tabla destino	`['id']`
`backref`	Nombre de la relación inversa	`'posts'`
`onDelete`	Acción al eliminar: `'cascade'`, `'restrict'`, `'set null'`	`'cascade'`
`onUpdate`	Acción al actualizar: `'cascade'`, `'restrict'`, `'set null'`	`'cascade'`

Regla fundamental:

✅ Usa relation() SOLO en la tabla que tiene la foreign key
✅ La tabla "origen" automáticamente muestra List[...] por la relación inversa
❌ NO uses relation() en ambos lados de la relación

🔐 Encriptación de Columnas

TAI-SQL soporta encriptación automática de columnas para proteger datos sensibles:

from tai_sql import Table, column, datasource

# Configurar datasource con clave de encriptación
datasource(
    provider=env('DATABASE_URL'),
    secret_key_name='SECRET_KEY'  # Variable de entorno con la clave secreta
)

class Usuario(Table):
    __tablename__ = "usuarios"
    
    id: int = column(primary_key=True, autoincrement=True)
    email: str = column(unique=True)
    nombre: str
    
    # Columnas encriptadas - Los datos se encriptan automáticamente
    password: str = column(encrypt=True)
    telefono: Optional[str] = column(encrypt=True)
    datos_bancarios: Optional[str] = column(encrypt=True)

Configuración requerida:

Variable de entorno: Define una clave secreta segura

export SECRET_KEY="tu_clave_secreta_de_al_menos_32_caracteres"

Configuración en datasource: Especifica el nombre de la variable

datasource(
    provider=env('DATABASE_URL'),
    secret_key_name='SECRET_KEY'  # Por defecto es 'SECRET_KEY'
)

Características de la encriptación:

✅ Automática: Los datos se encriptan al escribir y desencriptan al leer
✅ Transparente: El código funciona igual que columnas normales
✅ Segura: Usa cryptography.fernet con claves de 256 bits
✅ Validación: Verifica la existencia de la clave secreta antes de generar

Ejemplo de uso:

# El ModelGenerator crea propiedades híbridas automáticamente
user = Usuario(
    email="juan@example.com",
    nombre="Juan",
    password="mi_password_secreto",  # Se encripta automáticamente
    telefono="123-456-7890"          # Se encripta automáticamente
)

# Al leer, se desencripta automáticamente
print(user.password)  # "mi_password_secreto" (desencriptado)
print(user.telefono)  # "123-456-7890" (desencriptado)

# En la BD se almacena encriptado
print(user._password)  # "gAAAAABh..." (encriptado)

Validaciones de seguridad:

❗ Clave requerida: Si hay columnas con encrypt=True, la clave secreta debe existir
❗ Longitud mínima: La clave debe tener al menos 32 caracteres
❗ Solo strings: Solo columnas de tipo string pueden encriptarse

🧠 Columnas Vector (pgvector)

TAI-SQL soporta columnas de embeddings vectoriales integradas con pgvector (PostgreSQL). Se definen con vector_column() y el tipo de anotación vector.

Instalación:

# Solo pgvector (vectores externos pre-computados)
pip install tai-sql[vectors]

# pgvector + sentence-transformers (auto-encoding desde texto)
pip install tai-sql[vectors-encoding]

Caso 1: Vector externo — se almacena un vector ya computado, sin encoder.

from tai_sql import Table, column, vector, vector_column

class Documento(Table):
    __tablename__ = "documento"
    
    id: int = column(primary_key=True, autoincrement=True)
    titulo: str
    contenido: str
    
    # Vector de 1536 dimensiones (OpenAI ada-002)
    embedding: vector = vector_column(
        dimensions=1536,
        metric='cosine',
    )

El campo embedding acepta List[float] en create/update y en el DTO generado.

Caso 2: Auto-encoding con SentenceTransformerEncoder — el DAO generado codifica automáticamente un campo de texto al guardar.

class Articulo(Table):
    __tablename__ = "articulo"
    
    id: int = column(primary_key=True, autoincrement=True)
    titulo: str
    cuerpo: str
    
    # Encoding automático del campo 'cuerpo'
    # Las dimensiones se resuelven solas desde el modelo
    embedding: vector = vector_column(
        source='cuerpo',
        encoder=SentenceTransformerEncoder(),  # all-MiniLM-L6-v2 → 384 dims
    )

Cuando source y encoder están configurados:

Al hacer create(ArticuloCreate(titulo=..., cuerpo=...)), el DAO codifica cuerpo automáticamente y rellena embedding.
No es necesario pasar embedding en el DTO — se omite de ArticuloCreate.

Parámetros de vector_column():

Parámetro	Tipo	Descripción
`dimensions`	`int`	Número de dimensiones del vector. Auto-resuelto si se proporciona `encoder`.
`source`	`str`	Nombre del campo de texto a codificar automáticamente.
`encoder`	`BaseEncoder`	Encoder a usar. Actualmente: `SentenceTransformerEncoder`.
`metric`	`str`	Métrica de distancia: `'cosine'` (default), `'l2'`, `'inner_product'`.
`threshold`	`float`	Distancia máxima para búsquedas de similitud.
`index`	`bool`	Crear índice en la columna (recomendado para búsquedas).
`description`	`str`	Descripción para diagramas ER.

Modelos soportados por SentenceTransformerEncoder:

Modelo	Dimensiones	Uso recomendado
`all-MiniLM-L6-v2` (default)	384	Uso general, rápido
`all-MiniLM-L12-v2`	384	Uso general, mejor calidad
`all-mpnet-base-v2`	768	Alta calidad
`paraphrase-multilingual-MiniLM-L12-v2`	384	Multilingüe
`paraphrase-multilingual-mpnet-base-v2`	768	Multilingüe, alta calidad
`distiluse-base-multilingual-cased-v2`	512	Multilingüe, equilibrado

Para modelos externos (OpenAI, etc.), especifica dimensions explícitamente y omite encoder.

Dimensiones predeterminadas a nivel de proyecto:

En lugar de repetir dimensions= en cada columna, puedes configurar un valor por defecto en datasource():

datasource(
    provider=env('MAIN_DATABASE_URL'),
    default_vector_dimensions=384,  # Aplica a todas las columnas sin dimensions explícitas
)

Métricas y threshold:

Métrica	Rango	Interpretación
`cosine`	[0, 2]	0 = idéntico, 1 = ortogonal, 2 = opuesto
`l2`	[0, ∞)	0 = idéntico. Depende de la magnitud del vector.
`inner_product`	negativo internamente	Menor valor = mayor similitud real.

threshold filtra resultados cuya distancia supere ese valor:

# Solo resultados con similitud coseno alta (distancia < 0.5)
embedding: vector = vector_column(
    dimensions=384,
    metric='cosine',
    threshold=0.5,
)

Validaciones en tiempo de definición:

❗ Si dimensions y encoder se especifican y no coinciden → ValueError al importar el schema
❗ Si no se especifica dimensions ni encoder ni default_vector_dimensions → ValueError
❗ Solo disponible en PostgreSQL (requiere extensión pgvector)
✅ Si se omite dimensions y el encoder es conocido → se resuelve automáticamente

🧮 Columnas Calculadas (`calculated_column`)

Las columnas calculadas son columnas físicas en la base de datos cuyo valor se computa automáticamente a partir de otras columnas. Se definen con el decorador @calculated_column directamente en el modelo y se recomputan en cada INSERT y UPDATE mediante event listeners de SQLAlchemy.

Definición básica:

from tai_sql import Table, column, calculated_column

class Usuario(Table):
    __tablename__ = "usuario"
    
    id: int = column(primary_key=True, autoincrement=True)
    first_name: str
    last_name: str
    
    @calculated_column
    def full_name(self) -> str:
        """Nombre completo del usuario"""
        return f"{self.first_name} {self.last_name}"

Esto genera una columna física full_name de tipo str en la base de datos. El valor se calcula automáticamente al crear o actualizar el registro.

Cuerpo multi-statement con imports externos:

El cuerpo del método puede contener múltiples sentencias y usar imports del módulo donde se define el schema:

from unidecode import unidecode

class Producto(Table):
    __tablename__ = "producto"
    
    id: int = column(primary_key=True, autoincrement=True)
    nombre: str
    categoria: str
    
    @calculated_column
    def slug(self) -> str:
        """Genera un slug SEO-friendly a partir del nombre y categoría"""
        base = f"{self.nombre}-{self.categoria}"
        normalized = unidecode(base).lower()
        return normalized.replace(" ", "-")

TAI-SQL extrae automáticamente los imports necesarios (en este caso from unidecode import unidecode) y los incluye en el modelo generado.

Reglas:

El método debe tener anotación de tipo de retorno (-> str, -> int, -> float, etc.)
El decorador @calculated_column debe ser el único decorador del método
Las dependencias (self.campo) se detectan automáticamente vía AST
Soporta tipos opcionales: -> Optional[str] genera una columna nullable

Cómo funciona internamente:

El modelo SQLAlchemy generado usa el mismo patrón que las columnas encriptadas:

Columna física _full_name (con prefijo _) almacena el valor en la BD
hybrid_property full_name expone lectura/escritura transparente
Event listeners before_insert y before_update recomputan el valor automáticamente

# Código generado (simplificado)
class Usuario(Base):
    _full_name = Column('full_name', String, nullable=False)
    
    @hybrid_property
    def full_name(self):
        return self._full_name
    
    @full_name.setter
    def full_name(self, value):
        self._full_name = value
    
    def _recompute_full_name(self):
        self._full_name = f"{self.first_name} {self.last_name}"

@event.listens_for(Usuario, 'before_insert')
def _usuario_before_insert(mapper, connection, target):
    target._recompute_full_name()

@event.listens_for(Usuario, 'before_update')
def _usuario_before_update(mapper, connection, target):
    target._recompute_full_name()

Comportamiento en DTOs generados:

DTO	Incluye columna calculada	Motivo
`Create`	❌ No	Se computa automáticamente
`UpdateValues`	❌ No	Se recomputa en cada update
`Read`	✅ Sí	El valor almacenado es legible
`Filter`	✅ Sí	Se puede filtrar por el valor almacenado

Características:

✅ Columna física: El valor se almacena en la BD, indexable y filtrable
✅ Recompute automático: Se recalcula en cada INSERT y UPDATE via event listeners
✅ Multi-statement: Soporta cuerpos con múltiples sentencias
✅ Import extraction: Detecta y extrae imports externos usados en el cuerpo
✅ Detección de dependencias: Identifica qué columnas usa (self.X) vía análisis AST
✅ Transparente: El CRUD generado maneja todo automáticamente — el usuario no necesita calcular nada

👁️ `View` - Definición de Vistas

Las vistas permiten crear consultas complejas reutilizables:

from tai_sql import View, query

class UserStats(View):
    '''Estadísticas de usuarios y sus posts'''
    __tablename__ = "user_stats"
    __query__ = query('user_stats.sql')  # Archivo SQL en .../views/
    
    # Definir las columnas que retorna la vista
    user_id: int
    user_name: str
    post_count: int
    last_post_date: datetime

Archivo SQL correspondiente (.../views/user_stats.sql):

SELECT
    u.id AS user_id,
    u.name AS user_name,
    COUNT(p.id) AS post_count,
    MAX(p.created_at) AS last_post_date
FROM usuarios u
LEFT JOIN posts p ON u.id = p.author_id
WHERE u.active = true
GROUP BY u.id, u.name

🔢 `Enum` - Definición de Enumeraciones

Los enums permiten definir listas de valores predefinidos para ciertas columnas, garantizando integridad de datos:

from tai_sql import Table, column
from enum import Enum

# Definir enum como clase Python estándar
class ContentType(Enum):
    TEXT = "text"
    IMAGE = "image" 
    VIDEO = "video"

class Post(Table):
    '''Tabla de posts con tipo de contenido controlado'''
    __tablename__ = "post"
    
    id: int = column(primary_key=True, autoincrement=True)
    title: str
    content: str
    content_type: ContentType  # ← Usar enum como tipo de columna
    timestamp: datetime = column(server_now=True)

Características de los Enums:

✅ Auto-registro: Los enums se registran automáticamente al definirlos
✅ Validación automática: Solo acepta valores definidos en el enum
✅ Integración CRUD: El CRUD generado expone los valores disponibles
✅ Soporte en DTOs: Los Pydantic DTOs incluyen validación de enum
✅ Type hints: Autocompletado completo en tu IDE

Ejemplo con múltiples enums:

class Status(Enum):
    DRAFT = "draft"
    PUBLISHED = "published"
    ARCHIVED = "archived"

class Priority(Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

class Task(Table):
    __tablename__ = "tasks"
    
    id: int = column(primary_key=True, autoincrement=True)
    title: str
    status: Status = Status.DRAFT          # ← Con valor por defecto
    priority: Priority
    created_at: datetime = column(server_now=True)

Ventajas de usar Enums:

🛡️ Integridad de datos: Previene valores inválidos en la BD
📝 Documentación clara: Los valores posibles están definidos en el código
🔄 Refactoring seguro: Cambios de enum se propagan automáticamente
🚀 Performance: Validación rápida sin consultas a BD
🎯 Type safety: Detección de errores en tiempo de desarrollo

🔔 Triggers - Lógica de Negocio en Modelos

Los triggers permiten definir lógica de negocio que se ejecuta automáticamente cuando ocurren operaciones CRUD en una tabla. Se definen directamente en el modelo usando decoradores y se inyectan como código inline en los DAOs generados — no hay overhead de runtime, no hay clases intermedias.

TAI-SQL analiza el código fuente del trigger mediante AST (Abstract Syntax Tree) y lo transforma en código Python explícito que se integra directamente en los métodos create, update y delete del DAO generado.

Decoradores disponibles

Decorador	Evento	Parámetros
`@on_create`	Inserción de registro	`timing`, `priority`, `when`
`@on_update`	Actualización de registro	`timing`, `priority`, `fields`, `when`
`@on_delete`	Eliminación de registro	`timing`, `priority`, `when`

Parámetros comunes

Parámetro	Tipo	Descripción	Default
`timing`	`str`	`'before'` o `'after'` — cuándo se ejecuta respecto a la operación	`'before'`
`priority`	`int`	Orden de ejecución cuando hay múltiples triggers (menor = primero)	`1`
`fields`	`List[str]`	Solo en `@on_update`: lista de campos que activan el trigger	`None` (todos)
`when`	`lambda`	Condición opcional: si retorna `False`, el trigger no se ejecuta	`None`

`t.new` y `t.old` — Acceso a datos del registro

Dentro de un trigger, se accede a los datos del registro a través de t.new y t.old. La disponibilidad depende del evento:

Evento	`t.new`	`t.old`
`@on_create`	✅ Instancia SQLAlchemy a insertar	❌ No disponible (error en tiempo de definición)
`@on_update`	✅ Instancia SQLAlchemy con valores actualizados	✅ Dict snapshot con valores pre-update
`@on_delete`	❌ No disponible (error en tiempo de definición)	✅ Instancia SQLAlchemy del registro a eliminar

Validación en tiempo de definición: Usar t.old en @on_create o t.new en @on_delete lanza un SyntaxError inmediato al importar el schema — no en runtime.

class Post(Table):
    __tablename__ = "post"
    
    id: bigint = column(primary_key=True, autoincrement=True)
    content: str
    author_id: int
    timestamp: datetime = column(default=datetime.now)

    @on_create(timing='before')
    def normalize(self, t: TriggerAPI):
        t.new.content = t.new.content.strip()     # ✅ t.new disponible en create

    @on_update(timing='after', fields=['content'])
    def log_change(self, t: TriggerAPI):
        t.log(f"{t.old['content']} → {t.new.content}")  # ✅ ambos disponibles en update

    @on_delete(timing='before')
    def cleanup(self, t: TriggerAPI):
        t.delete_many(Comment, post_id=t.old.id)   # ✅ t.old disponible en delete

Mapeo interno de variables:

Evento	`t.new` / `self` se mapea a	`t.old` se mapea a
`create`	`new_instance` (instancia SQLAlchemy)	—
`update`	`new_instance` (instancia con valores actualizados)	`old_instance` (dict snapshot pre-update)
`delete`	—	`old_instance` (instancia SQLAlchemy)

`self` — Alias de conveniencia

self.campo es equivalente a t.new.campo en create/update y a t.old.campo en delete. Permite escribir triggers más concisos:

@on_create(timing='after')
def update_author(self, t: TriggerAPI):
    # self.author_id es equivalente a t.new.author_id
    t.update(Usuario, self.author_id, last_post_date=self.timestamp)

@on_delete(timing='before')
def cascade(self, t: TriggerAPI):
    # self.id es equivalente a t.old.id
    t.delete_many(Comment, post_id=self.id)