# 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)