La Base de Datos

Chinaski guarda todo en un solo archivo SQLite por instancia (sin servidor de base de datos, sin credenciales, sin protocolo de red) y mantiene su esquema al día con migraciones idempotentes que se ejecutan automáticamente al arrancar.

Un archivo por instancia

La base de datos es un único archivo chinaski.db, por defecto en la raíz de la aplicación, o donde apunte tu variable de entorno CHINASKI_DB. Cada instancia que ejecutes (chinaski@1, chinaski@prod, una copia de staging) tiene su propio archivo y sus propios ajustes; las plantillas de unidad de producción derivan estas rutas por nombre de instancia para que las copias nunca choquen.

Las conexiones pasan por un único módulo compartido con un conjunto canónico de opciones: los errores afloran de inmediato, el texto es Unicode limpio, y un busy timeout de 5 segundos evita que un archivo bloqueado cuelgue una solicitud. El modo WAL se establece de forma persistente, de modo que los lectores no bloquean a los escritores y la carga de trabajo típica (una sesión de admin activa más builds periódicos) se mantiene ágil. Las verificaciones de salud en el endpoint tipo /health comprueban lectura, escritura y modo de journal, advirtiendo cuando WAL no está activo.

Cómo evoluciona el esquema

Las instalaciones frescas se siembran con schema.sql, el esquema completo para una base de datos nueva; los scripts de instalación lo ejecutan por ti (o puedes ejecutar sqlite3 chinaski.db < schema.sql a mano).
Los archivos numerados bajo migrations/ no se aplican mecánicamente a las instancias en ejecución. Documentan la evolución y sirven solo para instalaciones frescas.
Las instancias ya desplegadas se actualizan mediante subs de migración idempotentes cableados a una única rutina de arranque. Cada migración primero introspecciona la base de datos (¿ya existe la columna o la tabla?) y no hace nada si es así. Los casos de primer arranque se saltan esto por completo porque schema.sql creó la forma fresca.

Como estas migraciones corren al arrancar y son idempotentes, actualizar Chinaski es levantar el servicio y listo: la instancia repara su propio esquema en el camino.

Qué hay dentro

Todo lo que gestiona el CMS: páginas, posts, bloques, snippets, stacks, categorías, redirecciones, navegación, formularios con sus envíos, metadatos de medios, documentos, usuarios y sesiones, los registros de auth/auditoría/eventos, el build log con reportes de validación, el render cache, los ajustes clave-valor, los historiales de revisiones y los registros de ejecución de respaldos.

Dos notas de confidencialidad que vale la pena conocer:

Las credenciales que introduces en los ajustes (contraseñas SMTP, claves de API, secretos de almacenamiento) se guardan cifradas en la base de datos, con clave derivada del secreto de tu instancia, nunca en texto plano.
Una marca de versión de esquema ata la disposición del archivo a las expectativas del código, y es el mismo número que verifica el flujo de respaldo/restauración: una base de datos restaurada en una instancia de versión distinta se rechaza en lugar de aplicarse parcialmente.

Salud y limpieza

La limpieza está incorporada: los tokens de restablecimiento de contraseña vencidos, las sesiones muertas y los historiales de registros acotados se podan automáticamente al arrancar y en temporizadores periódicos. El endpoint /health verifica que la base de datos pueda leerse y escribirse y reporta el modo de journal, de modo que la deriva respecto a la configuración esperada se detecta antes de que muerda.

Los respaldos son copias de archivo ordinarias, sin necesidad de herramientas especiales, y las páginas dedicadas a respaldos cubren snapshots, retención y restauración.