El CLI¶

El patrón que siguen todos¶

Sin excepción, un comando de tai-sql hace tres cosas:

Resolver sobre qué schema actúa: --schema, el default_schema del .taisqlproject, o preguntando.
Mapear: importa schemas/<nombre>.py, las clases se registran solas y el schema queda analizado y validado.
Actuar sobre ese mapeo.

De ahí salen dos consecuencias prácticas: cualquier error del schema aparece en el paso 2 de cualquier comando —así que tai-sql info sirve para validarlo sin tocar nada— y todos aceptan --schema.

tai-sql --debug <comando>    # traza completa cuando el fallo es interno

Los comandos¶

Comando	Para qué	Toca la BD
`init`	Crear un proyecto	No
`new-schema`	Añadir un schema al proyecto	No
`set-default-schema`	Cambiar el schema por defecto	No
`install`	Instalar las dependencias del cliente generado	No
`info`	Ver y validar lo que hay declarado	No
`ping`	Comprobar la conectividad	Solo lee
`pull`	Escribir el schema de una BD existente	Solo lee
`push`	Sincronizar el schema con la BD	Sí, escribe DDL
`generate`	Producir el cliente y los diagramas	No
`feed`	Insertar los datos iniciales	Sí, escribe datos
`backup` / `restore`	Copias de seguridad	Sí
`rules`	Reglas de contexto para asistentes de IA	No

Montar un proyecto¶

tai-sql init -n mi_proyecto -s public    # crea el proyecto, su .taisqlproject y su pyproject
tai-sql install                          # instala en él lo que su schema necesita
tai-sql new-schema ventas                # añade un schema más
tai-sql set-default-schema ventas        # el que usarán los comandos sin --schema
tai-sql info                             # qué hay declarado: schemas, default, comandos
tai-sql ping                             # ¿se llega a la base de datos?
tai-sql ping -d -t 10                    # comprueba además que la BD concreta existe

Comando	Opciones
`init`	`-n/--name`, `-s/--schema`, `--install/--no-install`
`new-schema`	`NAME`
`set-default-schema`	`SCHEMA_NAME`
`install`	`--async`, `-y/--yes`
`info`	—
`ping`	`-s/--schema`, `-t/--timeout`, `-d/--check-db`

El orden normal de trabajo¶

Si la base de datos ya existe, el primer paso es tai-sql pull, una sola vez. A partir de ahí manda el fichero de schema:

vim schemas/public.py               # 1. cambias el schema
tai-sql push --dry-run --verbose    # 2. miras qué implicaría
tai-sql push                        # 3. lo aplicas (regenera el cliente al terminar)
tai-sql rules install               # 4. actualizas las reglas del asistente, si te avisó

Si solo quieres regenerar el cliente sin tocar la base de datos, tai-sql generate.

Cómo se leen los errores¶

Un problema que tú puedes arreglar nunca sale como traceback:

❌ La variable de entorno MAIN_DATABASE_URL no está definida
   💡 Defínela en tu entorno o en el fichero .env: MAIN_DATABASE_URL=postgresql://usuario:clave@host:5432/basededatos
   📍 Schema 'public'
   🔗 E011

Qué ha pasado, qué hacer, dónde, y un código para buscarlo. Ver catálogo de errores.