Saltar a contenido

tai-sql

Framework declarativo de Python, sobre SQLAlchemy, que gestiona el ciclo de vida completo de una base de datos. Declaras el modelo una vez, en un fichero Python, y a partir de ahí tai-sql sincroniza la estructura de la base de datos, genera un cliente Python completo —modelos, DTOs y DAOs síncronos y asíncronos— y dibuja el diagrama entidad-relación.

schemas/public.py  ──▶  tai-sql push      ──▶  la base de datos se parece al schema
                   ──▶  tai-sql generate  ──▶  cliente Python + diagrama ER
                   ──▶  tai-sql feed      ──▶  datos iniciales
                   ◀──  tai-sql pull      ◀──  una base de datos que ya existe

Motores soportados: PostgreSQL, MySQL, SQL Server y BigQuery.

Empieza por aquí

  • Instalación

    Qué instalar, y por qué son dos instalaciones y no una.

    Instalación

  • Tu primer proyecto

    De cero a un cliente generado funcionando, paso a paso.

    Primer proyecto

  • El schema

    Cómo se declaran tablas, relaciones, vistas, triggers y todo lo demás.

    El schema

  • tai-sql push

    Cómo sincroniza, qué valida y —lo importante— qué puede destruir.

    push

Los cinco principios que explican el resto

Si algo del framework te sorprende, la explicación casi siempre está en uno de estos cinco principios. Son invariantes: ninguna versión los rompe.

  1. El schema es la única fuente de verdad. Todo lo demás —DDL, cliente, diagramas— es derivado y desechable. Si el cliente generado no hace lo que necesitas, no se edita el cliente: se arregla el schema y se regenera.
  2. Mapear y después actuar. Todo comando importa el schema, lo analiza y actúa sobre ese mapeo. Ningún comando parsea el fichero por su cuenta, y por eso un error del schema aparece en cualquier comando.
  3. El código generado nunca importa tai_sql. tai-sql es una herramienta de desarrollo, no una dependencia de producción: el cliente se despliega donde tai-sql no está instalado.
  4. Modelo declarativo, sin migraciones versionadas. No hay ficheros de migración: push compara el estado declarado con el real y genera el DDL que hace falta.
  5. Definición ≠ runtime. El ORM de tai-sql describe; el comportamiento en producción vive en el código generado.

Un vistazo

# -*- coding: utf-8 -*-
from __future__ import annotations
from tai_sql import *
from tai_sql.generators import *

datasource(provider=env('MAIN_DATABASE_URL'), schema='public', syntax='v2')

generate(
    PythonClientGenerator(output_dir='database'),
    ERDiagramGenerator(output_dir='diagrams', format='html'),
)


class Usuario(Table):
    """Usuarios del sistema."""
    __tablename__ = 'usuario'

    id: col[int] = column(primary_key=True, autoincrement=True)
    nombre: col[str]
    email: col[str] = column(unique=True)
    creado_en: col[datetime] = column(server_now=True)

    posts: onetomany[Post]


class Post(Table):
    """Posts publicados."""
    __tablename__ = 'post'

    id: col[bigint] = column(primary_key=True, autoincrement=True)
    titulo: col[str]
    contenido: col[text]
    autor_id: col[int]

    autor: manytoone[Usuario] = relation(
        fields=['autor_id'], references=['id'], backref='posts'
    )

tai-sql push --dry-run --verbose   # enseña el DDL sin ejecutar nada
tai-sql push                       # lo aplica y regenera el cliente

from database.public import public_sync_api, UsuarioCreate

usuario = public_sync_api.usuario.create(
    UsuarioCreate(nombre='Ana', email='ana@example.com')
)

usuarios = public_sync_api.usuario.find_many(
    limit=10,
    in_email=['ana@example.com', 'luis@example.com'],
    includes=['posts'],
)

Cómo está organizado este manual

Sección Qué responde
Inicio Qué instalar, cómo montar un proyecto y cómo es por dentro
El schema Todo lo que se puede declarar, y cómo
El CLI Qué hace cada comando, en qué orden se usan y qué puede destruir
El cliente generado La API que vas a usar desde tu aplicación
Referencia Firmas, motores soportados, extensión y catálogo de errores

¿Trabajas con un asistente de IA?

tai-sql rules install deja en tu proyecto la documentación que un asistente necesita para escribir schemas correctos, incluida una parte derivada de tu schema. Ver tai-sql rules.