Saltar a contenido

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:

⠴ Leyendo el catálogo de 'vilane_new'… 66 consultas 0:00:02

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) sale col[str] = column(length=50), un DECIMAL(10,2) sale col[numeric] = column(precision=10, scale=2), y un MEDIUMTEXT de MySQL, col[text] con su length. Ver el tamaño exacto.
  • timestamptz y smallint: un TIMESTAMP WITH TIME ZONE, o el TIMESTAMP de MySQL, sale timestamptz; un SMALLINT, smallint.
  • Un entero que el DSL no tiene (TINYINT, MEDIUMINT) se amplía al menor que lo contiene —TINYINT a smallint, MEDIUMINT a int— y se marca como inexacto: no pierde ningún valor, pero el primer push ampliará la columna.
  • autoincrement=True en las claves primarias AUTO_INCREMENT de MySQL.
  • UUID: un UUID de PostgreSQL, o un UNIQUEIDENTIFIER de SQL Server, sale col[UUID]. Si es la clave primaria y la base la genera (DEFAULT gen_random_uuid(), NEWID()), sale column(primary_key=True, autoincrement=True), que es como se declara una clave generada (ver UUID). En cualquier otra columna, ese DEFAULT no se puede declarar, y se avisa.
  • Los defaults con el tipo de la columna: default=True en un booleano, no default='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:

  1. Lo que un push posterior eliminaría, porque la comparación lo mira y no lo encuentra declarado: una tabla excluida con --exclude, una columna de tipo desconocido, un DEFAULT que el DSL no sabe escribir.
  2. Lo que un push posterior ignora, y sobrevive intacto: entre otras, las tablas de otras herramientas.
  3. Las columnas cuyo tipo el DSL no reproduce exacto —un TINYINT se declara smallint—: 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

tai-sql pull
# revisa el fichero a mano
tai-sql push --dry-run --verbose

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.