taskbot/docs/how-to/adding-migration.md

Cómo añadir una migración

Contexto

• Migraciones up-only con checksum estático y función up(db).

Pasos

1. Crear migración

   • Edita src/db/migrations/index.ts y añade una entrada Migration con:
     • version (número incremental),
     • name (descriptivo),
     • checksum (string calculado una vez),
     • up: (db) => { ... } con SQL idempotente cuando sea posible (usa helpers como tableHasColumn).

2. SQL y convenciones

   • Timestamps como 'YYYY-MM-DD HH:MM:SS[.mmm]' con strftime.
   • FOREIGN KEYs explícitas y PRAGMA foreign_keys = ON.
   • Usa ON CONFLICT para upserts cuando aplique.

3. Pruebas

   • En un test, crea const memdb = new Database(':memory:') y ejecuta initializeDatabase(memdb).
   • Valida que la tabla/columna existe y que el esquema es el esperado.

4. Despliegue

   • El arranque (server.start) invoca Migrator.migrateToLatest. No necesitas pasos manuales.

Notas

• No hay “down”; si necesitas revertir, crea una nueva migración correctiva.
• Evita cambios destructivos sin plan de migración de datos.