Gestiona de forma segura los cambios en el esquema de la base de datos (PostgreSQL), incluyendo diagnóstico, generación de revisiones con Alembic y validación de integridad.
Esta skill guía al agente a través del proceso obligatorio para modificar la estructura de la base de datos. El objetivo es prevenir inconsistencias ("multiple heads"), pérdida de datos o bloqueos en producción.
db/models.py.db/models.py.El agente debe seguir este orden estricto. Si un paso falla, DETENERSE y pedir intervención humana.
Antes de tocar nada, verifica el estado actual:
Ejecuta: python scripts/debug_migrations.py
Ejecuta: python scripts/check_schema.py
[!CAUTION] Si alguno de estos scripts reporta errores, NO CONTINUAR. Solicita intervención humana para resolver el conflicto antes de generar nuevas migraciones.
Si el diagnóstico es verde (OK), procede a generar el script:
alembic revision --autogenerate -m "<descripción_breve_del_cambio>"
"agrega_columna_stock_a_productos").[!IMPORTANT] CRÍTICO: El agente debe leer el archivo generado en
db/migrations/versions/y verificar:
| Verificación | Acción Requerida |
|---|---|
¿Hay columnas nullable=False? | Asegurarse de que tengan un server_default o que la tabla esté vacía |
¿El downgrade() revierte lo que hace el upgrade()? | Confirmar que la reversión es correcta |
¿Hay operaciones destructivas (drop_column, drop_table)? | Advertir al usuario sobre posible pérdida de datos |
Aplica los cambios:
alembic upgrade head
Verifica integridad post-migración:
python scripts/audit_schema.py # si existe
# o alternativamente:
python scripts/check_schema.py
Acción Documental: Agrega una nueva entrada en docs/MIGRATIONS_NOTES.md con:
| Acción | Comando |
|---|---|
| Ver historial | alembic history |
| Ver revisión actual | alembic current |
| Bajar una versión | alembic downgrade -1 |
| Estado detallado | python scripts/db_diag.py |
| Verificar heads | alembic heads |
| Merge de branches | alembic merge heads -m "merge_branches" |
flowchart TD
A[Usuario pide cambio en BD] --> B{Ejecutar diagnóstico}
B -->|OK| C[Generar migración con autogenerate]
B -->|ERROR| D[🛑 DETENER - Pedir ayuda humana]
C --> E{Revisar archivo generado}
E -->|nullable=False sin default| F[⚠️ Agregar server_default]
E -->|Operación destructiva| G[⚠️ Advertir al usuario]
E -->|Todo OK| H[Aplicar: alembic upgrade head]
F --> H
G -->|Usuario confirma| H
H --> I[Verificar con check_schema.py]
I --> J[Documentar en MIGRATIONS_NOTES.md]