Subir archivos a "/"

MIGRATIONS.md

@@ -0,0 +1,175 @@
+# Guía de Migraciones con Alembic
+
+Este proyecto usa Alembic para manejar las migraciones de base de datos.
+
+## 📋 Comandos Útiles
+
+### Dentro del contenedor Docker
+
+```bash
+# Acceder al contenedor
+docker exec -it control_mve_api bash
+
+# Crear una nueva migración automáticamente
+alembic revision --autogenerate -m "descripción del cambio"
+
+# Aplicar migraciones pendientes
+alembic upgrade head
+
+# Revertir última migración
+alembic downgrade -1
+
+# Ver historial de migraciones
+alembic history
+
+# Ver estado actual
+alembic current
+```
+
+### Desde el host (sin entrar al contenedor)
+
+```bash
+# Crear nueva migración
+docker exec -it control_mve_api alembic revision --autogenerate -m "descripción"
+
+# Aplicar migraciones
+docker exec -it control_mve_api alembic upgrade head
+
+# Ver historial
+docker exec -it control_mve_api alembic history
+```
+
+## 🚀 Flujo de Trabajo
+
+### 1. Modificar modelos
+
+Edita tus modelos en `app/models/`:
+
+```python
+# Ejemplo: agregar un nuevo campo
+class Cliente(Base):
+    __tablename__ = "clientes"
+    # ... campos existentes ...
+    nuevo_campo = Column(String(100))
+```
+
+### 2. Generar migración automática
+
+```bash
+docker exec -it control_mve_api alembic revision --autogenerate -m "agregar campo nuevo_campo a clientes"
+```
+
+Esto creará un archivo en `alembic/versions/` con los cambios detectados.
+
+### 3. Revisar la migración generada
+
+**IMPORTANTE**: Siempre revisa el archivo generado antes de aplicarlo.
+
+```bash
+# Ver el archivo más reciente
+ls -lt alembic/versions/ | head -n 2
+```
+
+### 4. Aplicar la migración
+
+```bash
+docker exec -it control_mve_api alembic upgrade head
+```
+
+### 5. Verificar que se aplicó
+
+```bash
+docker exec -it control_mve_api alembic current
+```
+
+## 🔄 Migración Inicial
+
+La migración inicial ya se ejecuta automáticamente cuando levantas los contenedores gracias al script `migrate.sh`.
+
+Si necesitas recrear la migración inicial:
+
+```bash
+# Eliminar migraciones existentes
+rm alembic/versions/*.py
+
+# Crear migración inicial
+docker exec -it control_mve_api alembic revision --autogenerate -m "migración inicial"
+
+# Aplicarla
+docker exec -it control_mve_api alembic upgrade head
+```
+
+## 📝 Ejemplos Comunes
+
+### Agregar un nuevo modelo
+
+1. Crear archivo en `app/models/nueva_entidad.py`
+2. Importarlo en `app/models/__init__.py`
+3. Generar migración: `alembic revision --autogenerate -m "agregar modelo NuevaEntidad"`
+4. Revisar y aplicar: `alembic upgrade head`
+
+### Modificar un campo existente
+
+1. Editar el modelo
+2. Generar migración: `alembic revision --autogenerate -m "modificar campo X"`
+3. **Revisar migración** - Alembic no siempre detecta todos los cambios
+4. Aplicar: `alembic upgrade head`
+
+### Crear migración manual
+
+Si necesitas hacer cambios que Alembic no detecta automáticamente:
+
+```bash
+docker exec -it control_timbres_api alembic revision -m "mi cambio manual"
+```
+
+Luego edita el archivo generado en `alembic/versions/`:
+
+```python
+def upgrade() -> None:
+    op.execute("UPDATE clientes SET estado = 'activo' WHERE estado IS NULL")
+
+def downgrade() -> None:
+    pass
+```
+
+## ⚠️ Buenas Prácticas
+
+1. **Siempre revisa** las migraciones autogeneradas antes de aplicarlas
+2. **Prueba en desarrollo** antes de aplicar en producción
+3. **Haz backup** de la base de datos antes de migraciones importantes
+4. **Escribe downgrades** funcionales para poder revertir cambios
+5. **Commits pequeños** - una migración por cambio lógico
+6. **Nombres descriptivos** para las migraciones
+
+## 🔧 Troubleshooting
+
+### La migración no detecta mis cambios
+
+- Verifica que importaste el modelo en `app/models/__init__.py`
+- Asegúrate de que `alembic/env.py` importa todos los modelos
+- Reinicia el contenedor: `docker-compose restart api`
+
+### Error: "Target database is not up to date"
+
+```bash
+# Ver qué migraciones faltan
+docker exec -it control_mve_api alembic current
+docker exec -it control_mve_api alembic history
+
+# Aplicar pendientes
+docker exec -it control_mve_api alembic upgrade head
+```
+
+### Quiero empezar de cero
+
+```bash
+# CUIDADO: Esto borra todos los datos
+docker-compose down -v
+docker-compose up -d
+```
+
+## 📚 Recursos
+
+- [Documentación oficial de Alembic](https://alembic.sqlalchemy.org/)
+- [Tutorial de Alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html)