Upgrades y Migraciones

Upgrades y migraciones: cómo avanzan el schema y el código de Chinaski. Esta página está anclada en la mecánica real del repositorio: sesenta y dos archivos de migración numerados como la historia de evolución del schema, y dos caminos concretos de upgrade: el script de deploy en línea y el script de bundle firmado para ambientes aislados.

La historia de migraciones (evolución del schema)

migrations/ lleva 62 archivos SQL numerados, de 001_phase2_database_foundation.sql a 062_form_submissions_read_at.sql. Cada uno se documenta por sí mismo: un header que lista qué cambia, y el comando de aplicación (sqlite3 chinaski.db < migrations/…) en cada archivo. Los nombres de archivo sirven también como changelog: lee el directorio de abajo hacia arriba y leerás la historia del producto: la fundación de la fase 2 (CHECK constraints, índices de dedup, columnas muertas eliminadas), documents (fase 45), toda la familia de stacks (de la 020 hasta la herencia en la 043), el endurecimiento de forms (ref tokens, atribución, quotas, validación de consentimiento, read-at), event logging, jerarquía/slots/renumeración de nav, versiones del promotion guard, parámetros de durability de build y la render cache.
schema.sql es el punto final del mismo historial para instalaciones frescas: una instalación nueva arranca directamente desde schema.sql, así que ambos caminos deben aterrizar en la misma forma. Eso se exige, no se asume: bin/check-schema-sync.pl compara una base de datos viva contra schema.sql y sale con código nonzero con una nota "Fix: add the missing tables/columns to schema.sql" cuando divergen. El memo de corrección es el contrato propio del proyecto: las instalaciones frescas tienen que coincidir con las vivas.
El orden de las migraciones es de carga crítica: el comentario del script de corrida nota "Must run before phase41: pages/posts rebuild SELECTs og_image_url from existing rows, so a DB predating the column would fail that rebuild." Un bloque grande de escritores helper en el código: cada uno corre solo cuando le llega su turno.
Cada migración está escrita para idempotencia: notas estilo IF NOT EXISTS a lo largo del corpus de migraciones (el lenguaje ha corrido dos veces en un camino fresh-install/boot muchas veces), así que un barrido de migración de arranque nunca explota en re-corridas.

Correr migraciones: automático

Las migraciones corren al arrancar la app: Chinaski::Migrations run_all() encadena los helpers _apply_* en un orden fijo (_apply_perf_indexes primero, luego las familias de content/stacks/forms/nav/doc en orden de dependencia). Un operador nunca corre una migración a mano; la aplicación converge su propia base de datos al schema actual del código.

Los sellos de versión existen donde una migración salta por detección de DB vieja: un incremento de PRAGMA user_version de SQLite dentro de uno de los helpers _apply_* de la cadena (observado: el gate que mueve una entrada pre-53 directo a 53 para saltar el trabajo previo en una base de datos reciente). El mapeo a los números de versión actuales está en el código, no en una tabla; no se incluye una lista de versiones orientada al operador.

Actualizar una instancia corriendo

En línea (en un host conectado)

deploy/deploy.sh <N>: la receta de siempre: 1. git baja el árbol de instalación e instala dependencias. 2. perl -c cms.pl hace el chequeo de sintaxis de la aplicación (un problema de sintaxis aborta antes de tocar nada). 3. Reconstruye el site estático con CHINASKI_DB/CHINASKI_OUTPUT definidos explícitamente. 4. Reinicia el servicio, a menos que el builder haya fallado, en cuyo caso el deploy aborta y el servicio conserva el árbol servido previamente (un reinicio sobre una media salida publicaría corrupción de servicio).

Aislado (air-gapped)

scripts/apply_update.sh: el script de upgrade offline: 1. En una máquina conectada, descarga el bundle de release de su manifest (un .tar.gz) y su firma Ed25519. 2. Transfiere ambos al destino y provee tu clave pública de release. 3. El script verifica la firma primero, respalda el árbol de aplicación actual, luego aplica la actualización, manteniendo la versión previa recuperable.

Notificación de actualizaciones: define una URL de manifest de actualizaciones cuando las actualizaciones se deban comprobar en absoluto; las instalaciones aisladas sin CHINASKI_UPDATE_MANIFEST_URL nunca se conectan.

Restaurar a través de límites de versión

Restaurar un backup rechaza un desajuste de versión de schema: un backup viejo solo se restaura en un esquema que coincida, es decir, en la versión de la app que coincide. Así que actualizar la app para que coincida con la versión de schema del backup es parte de un procedimiento de restauración (la página disaster-recovery recorre ese camino).

Cuando un upgrade aterriza cambios de schema, la maquinaria de restore de backups los refleja en el gate de schema (el gate de restore de la herramienta), no es una migración automática; la app arranca el cambio en el próximo bootstrap.

El pinning: tests

La higiene de migraciones también se exige en la suite de tests, además de en scripts:

Migration lint (migrations_lint.t) verifica que los archivos de migración sigan la higiene del proyecto (ids limpios, re-corrida segura).
Los tests de migración/code-suite ejercitan el flujo run-all real contra DBs de fixture; migrations_helpers corre la maquinaria con manejadores de base de datos dry/mockeados (CHINASKI_DB apuntado a cualquier path; se salta en tests).

Checklist para un upgrade

Backup primero (base de datos + archivos que te importen, sea el backup del sistema o un archivo in-app).
deploy.sh <N> en hosts conectados (que hace chequeo de sintaxis, rebuild, reinicio), o apply_update.sh con un bundle firmado en uno aislado.
Si el deploy.sh falló a nivel de schema (p. ej. las migraciones no corrieron), revisa el journal: las migraciones corren al arranque, no durante el script de deploy mismo.
Divergencia de instalación fresca: corre bin/check-schema-sync.pl para comparar schema.sql contra la DB viva; su salida nonzero marca de inmediato la edición que las instalaciones frescas necesitarán añadir.
Verifica que el site renderiza páginas más /health, verifica la completitud del build vía el build history.