tai-sql pull¶
tai-sql pull [-p <provider>] [--db-schema <x>] [-s <fichero>] [--syntax v1|v2]
[--exclude <tabla>] [--env-var <VAR>] [--stdout] [--force]
Escribe el fichero schemas/<nombre>.py que describe una base de datos que ya existe. Es la
dirección contraria a push, y sirve para empezar a usar tai-sql sobre algo que ya
está en producción sin transcribir las tablas a mano.
tai-sql pull # variable MAIN_DATABASE_URL, schema del motor
tai-sql pull -p OTRA_URL --db-schema ventas # de dónde leer
tai-sql pull -s facturacion # cómo llamar al fichero
tai-sql pull --exclude tabla_legacy # tabla que NO se declara
tai-sql pull --stdout # imprímelo, no escribas nada
tai-sql pull --syntax v1 # type hints desnudos en vez de col[...]
tai-sql pull --force # sobrescribe un schema que ya exista
Es determinista y no pregunta nada¶
Con los mismos argumentos produce siempre el mismo fichero, así que sirve igual en un terminal que en un script.
No sobrescribe un schema que ya exista: tendría docstrings, feed(), triggers y calculadas
que la base de datos no contiene. Para eso está --force, o -s <otro nombre>.
No escribe un schema que no carga¶
Antes de escribir nada, pull carga y analiza el schema que ha deducido en un proyecto
temporal: el mismo camino que seguirá generate, con el import del fichero, sus query() y el
análisis completo. Si no carga, no lo escribe y dice por qué. Con --stdout lo imprime
igualmente y avisa de que no cargaría tal cual.
Un fallo ahí es de pull, no de tu base de datos: repórtalo con el mensaje.
Mientras trabaja¶
Leer el catálogo de una base de datos grande —y más detrás de un túnel o una VPN— tarda: cien
tablas pueden ser un minuto. Mientras tanto, pull enseña una línea que se reescribe con la fase
en la que va, las consultas que lleva lanzadas y el tiempo transcurrido:
Si el contador y el reloj avanzan, está trabajando. La línea se borra al terminar y va por la
salida de errores, así que no se mezcla con --stdout; en un script o en CI, donde no hay
terminal, no sale.
MySQL y MariaDB¶
En estos motores el schema de la base de datos es la propia base de datos, así que el fichero
declara datasource(schema='<nombre de la base de datos>'), y las vistas se escriben en
views/<esa base>/, que es donde las buscará query(). Su SQL sale sin el prefijo
`base`. con el que MySQL las guarda cualificadas.
El provider¶
-p acepta el nombre de una variable de entorno (lo normal) o una cadena de conexión
completa. En el fichero se escribe siempre env('NOMBRE'), nunca la cadena: el schema se
commitea.
Con --env-var eliges qué nombre de variable se escribe, si no quieres el que usaste para leer.
Lo que declara¶
El tipo de cada columna se elige compilando cada tipo del DSL con el dialecto del motor y quedándose con el que da exactamente lo que hay, así que el fichero dice el tamaño real:
- Los parámetros de tipo: un
VARCHAR(50)salecol[str] = column(length=50), unDECIMAL(10,2)salecol[numeric] = column(precision=10, scale=2), y unMEDIUMTEXTde MySQL,col[text]con sulength. Ver el tamaño exacto. timestamptzysmallint: unTIMESTAMP WITH TIME ZONE, o elTIMESTAMPde MySQL, saletimestamptz; unSMALLINT,smallint.- Un entero que el DSL no tiene (
TINYINT,MEDIUMINT) se amplía al menor que lo contiene —TINYINTasmallint,MEDIUMINTaint— y se marca como inexacto: no pierde ningún valor, pero el primerpushampliará la columna. autoincrement=Trueen las claves primariasAUTO_INCREMENTde MySQL.UUID: unUUIDde PostgreSQL, o unUNIQUEIDENTIFIERde SQL Server, salecol[UUID]. Si es la clave primaria y la base la genera (DEFAULT gen_random_uuid(),NEWID()), salecolumn(primary_key=True, autoincrement=True), que es como se declara una clave generada (verUUID). En cualquier otra columna, eseDEFAULTno se puede declarar, y se avisa.- Los defaults con el tipo de la columna:
default=Trueen un booleano, nodefault='1'. Cada uno se verifica antes de escribirlo; el que no se sabe reproducir no se declara, y se avisa.
Los nombres de las relaciones¶
Una relación se llama como su columna FK sin el _id: menu_id → menu,
delegation_of_service_id → delegation_of_service. Es el nombre que ya le diste, y dice
más que el de la tabla: dos columnas que apuntan a delegations son dos cosas distintas. Si la
columna no sigue esa convención, o el nombre ya lo ocupa una columna, se usa el de la tabla
destino; y si también choca, se le añaden las columnas: usuario_por_author_id.
El backref sigue siendo <tabla>_list (sin _list en un uno a uno), y si choca —dos FKs de
una tabla hacia la misma— se desambigua con _por_<columna sin _id>:
albaran_list_por_asignada. Los nombres son mecánicos y no pluralizan: renombrar
es un cambio que se hace una vez, con criterio, sobre un fichero que ya funciona.
Las tablas de otras herramientas¶
Una base de datos que se adopta suele traer tablas que no son del dominio: la tabla de
versiones del sistema de migraciones que la gestionaba, o el catálogo de una extensión. pull
no las declara, pero las cuenta como ignoradas en el informe, y push nunca las elimina
aunque el schema no las declare. Antes sí las eliminaba.
| Herramienta | Tablas |
|---|---|
| Alembic | alembic_version |
| Prisma | _prisma_migrations |
| Rails, golang-migrate | schema_migrations, ar_internal_metadata |
| Laravel | migrations |
| Django | django_migrations |
| Flyway | flyway_schema_history |
| Liquibase | databasechangelog, databasechangeloglock |
| Knex | knex_migrations, knex_migrations_lock |
| Doctrine | doctrine_migration_versions |
| Entity Framework | __EFMigrationsHistory |
| goose | goose_db_version |
| Sequelize | SequelizeMeta |
| PostGIS | spatial_ref_sys, geometry_columns, geography_columns |
Si declaras en el schema una tabla con uno de esos nombres, se gestiona como cualquier otra: la lista solo decide qué no se borra por no estar declarado.
Las tablas sin clave primaria¶
El DSL exige una clave primaria en cada tabla, así que una que no la tenga —la
password_resets de Laravel es el caso típico— no se puede declarar. pull no la declara y
la cuenta como ignorada, y push nunca la elimina: tai-sql no ha podido crearla, así que
no es suya. Antes, pull la declaraba igualmente y el schema no cargaba (E014), así que no
escribía nada.
Para gestionarla con tai-sql, dale una clave primaria en la base de datos y vuelve a ejecutar
pull.
Lo que no puede reconstruir¶
La base de datos no los guarda, así que no salen:
| No se recupera | Por qué |
|---|---|
feed() |
Son datos, no estructura |
| Triggers | Viven en el schema y en el cliente generado, no en el motor |
| Columnas calculadas | Una calculada es una columna física: aparece como una columna normal |
| Encoders de columnas vectoriales | La columna sale, el encoder no |
| Descripciones | Solo las que estén como COMMENT |
Tampoco distingue str de text cuando el motor usa el mismo tipo para los dos.
Los avisos del final¶
Al terminar dice qué había en la base de datos que el schema no declara, en bloques que no significan lo mismo:
- Lo que un
pushposterior eliminaría, porque la comparación lo mira y no lo encuentra declarado: una tabla excluida con--exclude, una columna de tipo desconocido, unDEFAULTque el DSL no sabe escribir. - Lo que un
pushposterior ignora, y sobrevive intacto: entre otras, las tablas de otras herramientas. - Las columnas cuyo tipo el DSL no reproduce exacto —un
TINYINTse declarasmallint—: esas no se borran, se alteran.
Los avisos que quedan dentro del propio fichero, junto a la tabla a la que se refieren, son comentarios de una línea.
Antes de aplicar nada
El schema que sale de pull es un punto de partida, no un resultado final. Revísalo —sobre
todo los tipos y los DEFAULT— antes del primer push sobre una base de datos que te
importe.
Después del pull¶
A partir de ahí manda el fichero: el ciclo es el de siempre, y pull no se vuelve a ejecutar.