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.
📖 El manual completo está en triplealpha-innovation.github.io/tai-sql
Quickstart
pip install tai-sql # PostgreSQL funciona sin extras
tai-sql init -n mi_proyecto -s public # crea el proyecto
cd mi_proyecto
export MAIN_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
tai-sql install # instala lo que el cliente generado necesitará
Edita schemas/public.py:
# -*- 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
Y a usarlo:
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, includes=['posts'])
Los cinco principios que explican el resto
- 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.
- 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.
- 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. - Modelo declarativo, sin migraciones versionadas. No hay ficheros de migración:
pushcompara el estado declarado con el real y genera el DDL que hace falta. - Definición ≠ runtime. El ORM de tai-sql describe; el comportamiento en producción vive en el código generado.
Qué trae
| Schema declarativo | Tablas, relaciones, vistas, enumerados, constraints e índices de varias columnas, columnas calculadas y jerarquías. Dos sintaxis, v1 y v2, y las dos se soportan |
| Sincronización sin migraciones | push compara y genera el DDL, clasificando cada operación en SAFE / WARNING / BLOCKED antes de tocar nada |
| Cliente Python generado | CRUD completo, filtros por tipo de columna, relaciones anidadas, agregaciones con GROUP BY, DataFrames, RLS, auditoría y transacciones, en síncrono y asíncrono |
| Triggers transpilados | Lógica de negocio declarada en el schema que se inlinea en los DAOs: sin coste en runtime |
| Cifrado y vectores | Columnas cifradas con Fernet, transparentes al leer, y columnas vectoriales con pgvector y búsqueda por similitud |
| Diagrama ER | Una página HTML interactiva, o una imagen con Graphviz |
| Introspección | pull escribe el schema de una base de datos que ya existe |
| Reglas para asistentes de IA | rules install deja en tu proyecto la documentación que un asistente necesita, incluida la derivada de tu schema |
El manual
| Sección | Qué responde |
|---|---|
| Instalación | Qué instalar, y por qué son dos instalaciones y no una |
| Tu primer proyecto | De cero a un cliente generado funcionando |
| El schema | Todo lo que se puede declarar, y cómo |
| El CLI | Qué hace cada comando, y qué puede destruir push |
| El cliente generado | La API que vas a usar desde tu aplicación |
| Referencia | Firmas del DSL, motores, extensión y catálogo de errores |
Desarrollo
git clone https://github.com/triplealpha-innovation/tai-sql
cd tai-sql
poetry install --all-extras # los extras no son opcionales para la suite
poetry run pytest # todo lo que el entorno permita
poetry run pytest -m "not db and not mysql" # lo que corre sin ninguna base de datos
poetry run pytest -m mysql # el ciclo completo contra MySQL
Los tests marcados db necesitan un PostgreSQL alcanzable y se saltan si no lo hay; los
marcados mysql, un MySQL en TAI_SQL_MYSQL_URL. Sus schemas salen de tests/fixtures/project/.
El CI tiene tres workflows: tests.yaml ejecuta la suite en cada push y PR a main y dev —un
trabajo con PostgreSQL y otro con MySQL—, docs.yaml publica el manual y publish.yaml publica
a PyPI en push a main. La rama de trabajo habitual es dev, y la versión se bumpea a mano en
pyproject.toml.
El manual, en local
pip install -r docs/requirements.txt
mkdocs serve # http://127.0.0.1:8000, con recarga en caliente
mkdocs build --strict # lo mismo que valida el CI
El manual vive en docs/ y es para quien usa tai-sql. Las reglas de diseño internas
(.claude/rules/) y el README.md de cada paquete son para quien trabaja en tai-sql, y no
se publican: son dos audiencias con preguntas distintas.
El mapa del código
| Ruta | Qué es |
|---|---|
tai_sql/orm/ |
El mapeo, en cuatro capas: declarative/ → analysis/ → model/ → mapping/ |
tai_sql/sync/ |
Sincronización schema ↔ BD: state/ → diff/ → report.py → plan/ → safety.py → executor.py |
tai_sql/feed/ |
Poblar la base de datos: recoger → planificar → aplicar en una transacción |
tai_sql/introspect/ |
La dirección contraria: BD existente → fichero de schema |
tai_sql/drivers/ |
Todo el SQL dialectal, más las capacidades de cada motor |
tai_sql/generators/ |
Cliente Python, diagrama ER y reglas |
tai_sql/connection/ |
Con qué se conecta tai-sql y cómo se conectará el cliente generado |
tai_sql/cli/ |
El CLI de Click |
tai_sql/errors/ |
TaiSqlError (mensaje + solución obligatoria) y su presentador |
Cada uno de esos paquetes tiene su propio README.md con el detalle.
Licencia
MIT. Ver LICENSE.
Desarrollado por Triple Alpha Innovation · Issues
Metadata
Release files for tai-sql 0.7.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| tai_sql-0.7.11.tar.gz | 619.6 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai_sql-0.7.11-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / tai_sql-0.7.11.tar.gz
| Download URL | tai_sql-0.7.11.tar.gz |
|---|---|
| Size | 619.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c0cc7724b7beab660ce5af0797464e5d77e0782bc8840309ff193845a0f4aac8
|
|
BLAKE2b-256 checksum How to use checksums |
ea38a79c36bed45d977b7fe58a522d63ecc017752d9495d24b470c2f3a7d1a85
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.0 Linux/6.17.0-1022-azure
|
Release files / tai_sql-0.7.11-py3-none-any.whl
| Download URL | tai_sql-0.7.11-py3-none-any.whl |
|---|---|
| Size | 758.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
baece68552edc6087b302d55786cf1c2e5132ccc5f4ecf2880f3915cf47d2e6d
|
|
BLAKE2b-256 checksum How to use checksums |
83bc4dc81ba3c464bae784c740bf01831a68ff18e618c237032c1025afff8ced
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.0 Linux/6.17.0-1022-azure
|
Security for tai-sql 0.7.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
