Migración de base de datos con Docker, Alembic y pruebas automatizadas

Con un enfoque práctico y confiable, aquí se muestra cómo garantizar que un servicio de API esté listo para una migración de base de datos usando Docker, Alembic y pruebas automatizadas. El flujo integra unit tests, un Makefile con comandos útiles y la asistencia de Claude Code para planificar, ejecutar y validar cada paso sin romper el servicio.

¿Cómo iniciar el servicio y validar la API con Docker y Makefile?

Para empezar, es clave que el servicio corra en local. En la carpeta backend existe un Makefile con comandos para construir la imagen, iniciarla y revisar logs. Esto permite confirmar que la API responde en localhost en el puerto ocho mil.

• Ir a la carpeta del proyecto en backend.
• Construir la imagen para descargar dependencias necesarias.
• Iniciar la API y verificar con logs.
• Abrir el navegador en localhost:8000 para ver la respuesta de la API.

cd backend
make build
make start
make logs

Conceptos clave: - Imagen Docker: empaqueta dependencias y entorno de ejecución. - Logs: confirman si el servicio “se encendió correctamente”. - Makefile: centraliza comandos para tareas repetibles.

¿Qué hacer si falta un comando para pruebas?

Si no hay un comando de pruebas en el Makefile, se le puede pedir a Claude Code crear uno llamado test que ejecute pytest dentro del contenedor. Así se estandariza la ejecución de unit tests.

make test

¿Cómo ejecutar y reparar los unit tests con pytest dentro del contenedor?

La validación de la migración se apoya en unit tests. Con el nuevo comando test, las pruebas corren dentro del contenedor de API. Si fallan por dependencias, hay que corregirlas antes de continuar.

• Dependencias necesarias para pruebas: httpx y pytest-asyncio.
• Solución: agregarlas a las dependencias opcionales y reconstruir con UV.
• Resultado esperado: pruebas corriendo al cien por ciento.

Habilidades puestas en práctica: - Ejecución de comandos dentro de contenedores. - Gestión de dependencias y reconstrucción del entorno. - Uso de pytest para validar el estado del sistema.

¿Qué rol cumplen Claude Code y el bash tool?

Claude Code puede ejecutar comandos “como terminal” con su tool de Bash, por ejemplo, usando docker compose para correr pytest en el contenedor de API. Además, ayuda a editar archivos, como el Makefile, e incorporar comandos nuevos.

• bash mode: permite escribir comandos de Bash con !.
• plan mode: muestra el plan antes de ejecutar, para aprobar paso a paso.
• auto accept: acepta cambios y ejecuciones automáticamente.
• Modo por defecto: pide confirmación antes de avanzar.

¿Cómo crear migraciones con Alembic y validar el estado del sistema?

La fase uno se centra en base de datos: crear la tabla de “course rating” en PostgreSQL con sus constraints e índices mediante Alembic, verificando que todo se aplique correctamente y que el servicio siga funcionando.

• Identificar el contenedor de API en ejecución.
• Consultar el estado actual de migraciones con Alembic.
• Crear la nueva migración siguiendo el patrón del proyecto.
• Aplicar la migración con el comando de Make correspondiente.
• Validar en PostgreSQL que la migración quedó aplicada.

Buenas prácticas observadas: - Usar plan mode para entender objetivos, pasos y validaciones antes de ejecutar. - Mantener el contexto correcto de directorios (evitar errores con pwd). - Asegurar que los comandos se ejecuten dentro del contenedor de API.

¿Qué es plan mode y cómo aprobar cambios?

Con plan mode, Claude Code detalla qué hará: crear el archivo de migración, ejecutar la migración y verificar en base de datos. Luego ofrece opciones de ejecución.

• Opción de ejecutar automáticamente aceptando ediciones.
• Permitir que no vuelva a pedir confirmación para docker compose en esa carpeta.
• Revisar el resumen final de cambios aplicados y validaciones.

¿Cómo verificar endpoints y estado de contenedores?

Tras la migración, se reejecutan unit tests y se valida el endpoint de health. Además, se permite usar curl y python3 para una verificación ligera de integración: llamar a endpoints y revisar respuestas.

• Validación final: pruebas pasan, contenedor activo, endpoints responden correctamente.
• Garantía de no regresión: ejecutar unit tests después de cambios en base de datos.
• Visibilidad: Claude Code entrega un resumen claro de resultados.

Hacia la siguiente fase: - Implementar la fase dos creando los modelos de SQLAlchemy. - Compartir retos y soluciones en comentarios.

¿Te animas a completar la fase dos con modelos de SQLAlchemy usando Claude Code? Cuéntame en los comentarios qué obstáculos tuviste y cómo los resolviste.