176 lines
4.4 KiB
Markdown
176 lines
4.4 KiB
Markdown
# 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)
|