Migraciones de bases de datos
Las migraciones de Tyrus son archivos SQL numerados que el desarrollador revisa antes de aplicarlos. Los builds y las conexiones normales a la base nunca crean ni aplican migraciones automáticamente. Consulta Comandos de schema de la base para ver la referencia completa de la CLI.
Generar y revisar
tyrus db migrate generate <name> crea una migración inicial a partir de los Models del proyecto cuando la base configurada no existe. Las migraciones generadas validan cada @foreignKey contra los Models del proyecto en un schema inicial o contra el catálogo SQLite actual en cambios incrementales. Las migraciones iniciales también exigen tipos compatibles en los campos del Model; las incrementales comprueban la afinidad de tipos SQLite. Ambas verifican la tabla y las columnas de destino y su unicidad, incluidas las claves compuestas y los índices únicos, en el schema SQLite reproducido. La validación de identificadores SQLite en los snapshots no distingue mayúsculas de minúsculas, pero el snapshot conserva la grafía informada por la base. Para una base existente, requiere un snapshot actualizado del schema y puede crear tablas para Models nuevos, añadir columnas opcionales o columnas con valores predeterminados literales y reconstruir una tabla cuando un Model elimina columnas o cambia la clave primaria, constraints @unique o claves foráneas salientes. Las reconstrucciones copian los valores conservados y restauran los índices personalizados, los triggers de la tabla y las views desde el catálogo de schema de SQLite. Antes de guardar el SQL generado, la CLI lo reproduce en una copia en memoria del schema SQLite y valida las views y los triggers resultantes; las views y los triggers sin relación con la columna eliminada no bloquean la eliminación, pero las dependencias que fallen o hagan referencia a un campo eliminado de un trigger requieren una migración manual. La generación también se rechaza cuando una columna eliminada se usa en un índice, cuando otra tabla referencia la tabla reconstruida o cuando adiciones simultáneas impiden conservar los datos de forma segura. La aplicación de un cambio de clave o clave foránea puede fallar si los registros existentes lo infringen; en ese caso, la transacción SQLite se revierte. Los cambios en definiciones de columnas existentes requieren una migración escrita manualmente. El comando guarda un archivo SQL numerado y nunca modifica la base. Los nombres como initial_schema de los ejemplos son ilustrativos; sustitúyelos por un nombre descriptivo para tu migración o seed.
La comparación de migrations de Model sigue las reglas de SQLite que no distinguen mayúsculas de minúsculas para los nombres de tablas y columnas, incluidos los destinos de claves foráneas y los mapeos físicos de columnas. Dos Models o campos no pueden mapear nombres que solo se diferencian por mayúsculas y minúsculas.
Flujo habitual
Para una base SQL existente, modifica el Model, compáralo con la base activa y el snapshot actual, genera una migración, revisa el archivo SQL numerado en db/migrations/, aplícala y actualiza el snapshot. PostgreSQL y MySQL generan nuevas tablas de Model y adiciones seguras de columnas; los cambios que alteran o eliminan definiciones existentes requieren una migración escrita manualmente. En el ejemplo, add_profile es un nombre elegido por el desarrollador. Para una base nueva, genera una migración inicial a partir de los Models, revisa y aplica el archivo y luego ejecuta tyrus db introspect para crear el snapshot.
# Compare the edited Models with the snapshot and live database.
tyrus db diff
# Replace add_profile with a descriptive migration name.
tyrus db migrate generate add_profile
# Review and edit the generated SQL file before applying it.
tyrus db migrate apply
# Refresh the snapshot after the database schema changes.
tyrus db introspect# Replace `initial_schema` with a descriptive name for this migration.
tyrus db migrate generate initial_schema
tyrus db migrate status
tyrus db migrate apply
tyrus db introspect
# Replace `default_roles` with a descriptive name for this seed.
tyrus db seed create default_roles
tyrus db seed status
tyrus db seed applyInspecciona y edita el SQL generado antes de aplicarlo. Se rechazan los mapeos de tipos SQLite que puedan perder valores; los campos u8[] del modelo se mapean a columnas SQLite BLOB y al tipo lógico de snapshot bytes. Después de que una migración cambie el schema, ejecuta tyrus db introspect para actualizar el snapshot local que usan el compilador y el Language Server. Los snapshots PostgreSQL y MySQL incluyen tablas base visibles, columnas, tipos nativos, motores de tabla cuando están disponibles, claves, índices, claves foráneas y triggers; el snapshot guarda un identificador hash del destino sin credenciales de conexión.
Aplicar y seguir las migraciones
tyrus db migrate status enumera los archivos aplicados y pendientes sin modificar SQLite, PostgreSQL o MySQL. tyrus db migrate apply aplica las migraciones PostgreSQL en una sola transacción y registra el checksum de cada archivo en _tyrus_migrations; en MySQL, guarda el estado de recuperación started antes de cada migración, porque el DDL puede confirmar implícitamente. Las aplicaciones concurrentes en PostgreSQL usan un bloqueo advisory ligado a la transacción y en MySQL usan un bloqueo con nombre. El validador de migraciones del servidor reconoce cuerpos PostgreSQL delimitados por dollar-quote, cadenas escapadas E'...' y comentarios de bloque anidados, además de comentarios MySQL #, antes de comprobar comandos transaccionales. Así, las funciones PostgreSQL pueden contener puntos y coma y BEGIN/END procedural sin confundir las comprobaciones de la transacción administrada. PostgreSQL revierte un lote fallido. Si falla una migración MySQL, inspecciona la base y el archivo antes de reintentar; la entrada incompleta del historial impide la reaplicación automática. Los archivos aplicados no se pueden editar ni eliminar, y no existe un comando de downgrade automático.
Migraciones de Model de PostgreSQL y MySQL
Para PostgreSQL y MySQL, tyrus db migrate generate <name> crea una migración inicial a partir de los Models del proyecto sin conectarse a la base de datos. Cuando ya existen migraciones, la generación incremental se conecta al servidor configurado, verifica que el schema activo coincida con el snapshot y puede crear nuevas tablas de Model, agregar columnas, ampliar tipos numéricos compatibles y convertir columnas obligatorias en opcionales. Las columnas agregadas deben ser opcionales o tener un valor predeterminado literal. Una nueva columna @unique solo se admite si es opcional y no tiene un valor predeterminado; agregar @unique a una columna existente genera una constraint única, cuya aplicación puede fallar si ya hay valores duplicados, sin reescribir esas filas. Las columnas nuevas con @foreignKey deben ser opcionales y no tener valor predeterminado; agregar una foreign key a una columna existente solo se admite si es opcional y la tabla de destino, la clave única y el tipo nativo compatible constan en el snapshot. MySQL también exige InnoDB en ambas tablas y anchos iguales para enteros con signo registrados mediante introspección; PostgreSQL también verifica el tipo nativo exacto. Las filas existentes con valores huérfanos pueden hacer que la constraint de foreign key generada falle al aplicarse, sin reescribir esas filas. La ampliación se limita a smallint/integer/bigint y real/double admitidos por el backend, requiere metadatos nativos y se rechaza para columnas que formen parte de claves, índices o relaciones. Convertir una columna en opcional conserva sus valores y constraints existentes; MySQL también requiere los metadatos del tipo nativo porque MODIFY COLUMN vuelve a declarar la definición completa de la columna. Cambiar o quitar un valor predeterminado literal de una columna existente que no sea de identidad genera ALTER COLUMN SET DEFAULT o DROP DEFAULT; los valores predeterminados de expresión, la reducción de tipos, convertir una columna en obligatoria, cambios de claves primarias, eliminación de columnas o constraints, cambios de claves foráneas existentes y cambiar la opción timestamps de un Model existente requieren una migración manual. Si el snapshot no contiene los tipos nativos necesarios, vuelve a ejecutar tyrus db introspect antes de generar una migración segura o validar foreign keys. El generador admite campos de enteros con signo, punto flotante, texto y arrays de bytes, campos obligatorios y opcionales, valores predeterminados literales admitidos por el backend, claves primarias, constraints únicas y relaciones @foreignKey validadas para tablas nuevas. Las claves primarias enteras de PostgreSQL reciben generación de identidad; las de MySQL reciben AUTO_INCREMENT, y las tablas MySQL generadas usan InnoDB. El generador rechaza tipos sin soporte y claves o valores predeterminados de texto/binarios en MySQL. Usa tyrus db migrate create <name> para crear un archivo SQL identificado por backend y escribir manualmente las migraciones posteriores. status, apply, introspect, check y diff del schema activo también admiten PostgreSQL y MySQL. La comparación de solo lectura entre Models y snapshot admite SQLite, PostgreSQL y MySQL; los cambios aditivos seguros del servidor se generan incrementalmente, mientras que las operaciones destructivas o ambiguas siguen siendo manuales.
Seeds
Crea manualmente programas de seed como archivos .tyr en db/seeds/. Una seed puede usar la API de Model o db.query; ejecuta un archivo con tyrus db apply default_roles.tyr y consulta su estado con tyrus db seed status. La CLI registra checksums SHA-256 en _tyrus_seeds (una tabla en SQLite, PostgreSQL y MySQL, y una colección en MongoDB) y rechaza volver a ejecutar un archivo aplicado o aceptar archivos aplicados modificados o ausentes. El historial de seeds de MongoDB usa los mismos comandos, pero las migraciones de schema todavía no están disponibles para esa base. El programa de seed se ejecuta en un proceso Tyrus separado, por lo que la CLI no puede envolver operaciones arbitrarias en una única transacción de la base; usa la API de transacciones cuando varios cambios deban ser atómicos. Un programa que falle o se interrumpa permanece como started y bloquea nuevos intentos. Inspecciona la base, corrige o revierte los cambios parciales y luego elimina la fila o el documento correspondiente de _tyrus_seeds antes de reintentarlo; crea un archivo de seed nuevo para cambios posteriores en los datos.
