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.

📦 Instalación

Usando Poetry (Recomendado)

poetry add tai-sql

Usando pip

pip install tai-sql

Dependencias del sistema

Para generar diagramas ER, necesitas instalar Graphviz:

# 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(
    ModelsGenerator(output_dir='mi_proyecto'),
    CRUDGenerator(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 ModelsGenerator, CRUDGenerator, ERDiagramGenerator

generate(
    # Generar modelos SQLAlchemy
    ModelsGenerator(
        output_dir='database/database'
    ),
    # Generar CRUDs sincronos
    CRUDGenerator(
        output_dir='database/database',
        mode='sync'  # 'sync', 'async', o 'both'
    ),
    # 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

👁️ `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`

Referencia de `self` y `TriggerAPI`

Dentro de un trigger, self se refiere al modelo actual (la tabla donde se define el trigger). El parámetro t: TriggerAPI proporciona métodos para interactuar con otros modelos y utilidades.

Acceso a datos del modelo actual con self:

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='after')
    def update_author(self, t: TriggerAPI):
        # self.author_id → accede al campo author_id del Post que se está creando
        # self.timestamp → accede al campo timestamp del Post que se está creando
        t.update(Usuario, self.author_id, last_post_date=self.timestamp)

Mapeo interno de self según evento:

Evento	`self.campo` se mapea a	Contexto
`create`	`instance.campo`	`instance` es el objeto SQLAlchemy recién creado
`update`	`record.campo`	`record` es el registro cargado de la BD con los nuevos valores aplicados
`delete`	`record.campo`	`record` es el registro antes de ser eliminado