Migraciones de esquema con Alembic

Alembic es una herramienta diseñada para gestionar versiones de esquemas de bases de datos en proyectos que utilizan SQLAlchemy. Permite realizar migraciones incrementales, actualizando el esquema de la base de datos sin tener que eliminar y recrear todo, lo cual es crucial en proyectos activos donde los cambios en la estructura de la base de datos son frecuentes.

Instalación de Alembic

Puedes instalar Alembic mediante pip:

pip install alembic

O agregarse como dependencia en un proyecto gestionado con uv:

uv add alembic

Configuración

Configuración inicial

Para comenzar a usar Alembic, debes inicializar un entorno de migración ejecutando:

alembic init alembic

Este comando crea el archivo alembic.ini y el directorio alembic/, que contendrán la configuración y los scripts de migración.

Comando alembic no encontrado

Recuerda que por defecto los programas ejecutables agregados al proyecto no son cargados en la sesión actual. Para poder ejecutarlo, debes cargar el entorno virtual o usar uv run (más detalles en esta sección).

Configuración del archivo alembic.ini

El archivo alembic.ini gestiona configuraciones esenciales, como la URL de la base de datos. Por ejemplo, para utilizar SQLite, realiza el siguiente cambio:

sqlalchemy.url = sqlite:///db.sqlite3

Si quieres utilizar PostgreSQL, MySQL u otra base de datos, asegúrate de instalar el conector adecuado, y cambia la url según corresponda.

Otra configuración útil es ajustar file_template, que determina el formato de los nombres de los archivos de migración. Por defecto, el esquema del archivo comienza con el ID, que es aleatorio, lo cual no lista las revisiones en orden. Con la siguiente configuración, quedarán ordenados por fecha/hora:

file_template = (month).2d(hour).2d(rev)s_%%(slug)s

Configuración del script env.py

Para que Alembic reconozca tu esquema de SQLAlchemy, edita el archivo env.py, importando la base de modelos y asignando la metadata a la variable target_metadata:

from myapp.models import Base
 
target_metadata = Base.metadata

Scripts de migración

Los scripts de migración definen cómo cambia el esquema de la base de datos entre versiones. Pueden crear, eliminar o modificar tablas y columnas, y también ejecutar sentencias SQL personalizadas. Para crear un nuevo script, utiliza:

Para generar un nuevo script de migración, usa el comando revision.

alembic revision -m "Init"

Esto crea un archivo en alembic/versions que puedes editar para incluir las modificaciones del esquema.

A continuación puedes ver un ejemplo de script de migración:

"""Init
 
Revision ID: e942d21c3e3f
Revises: 0c21f2ccc381
Create Date: 2024-09-24 15:10:29.304873
 
"""
 
from typing import Sequence, Union
 
from alembic import op
import sqlalchemy as sa
 
# revision identifiers, used by Alembic.
revision: str = "e942d21c3e3f"
down_revision: Union[str, None] = "0c21f2ccc381"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
 
 
def upgrade() -> None:
    pass
 
 
def downgrade() -> None:
    pass

Cuando generas un nuevo script de migración con el comando revision, las funciones upgrade() y downgrade() en el archivo generado estarán vacías. Necesitas definir las operaciones necesarias para modificar el esquema (en upgrade()) y para revertir los cambios (en downgrade()). Por ejemplo, para crear la tabla “usuarios”:

...
from sqlalchemy import INTEGER, VARCHAR, Column
 
 
def upgrade() -> None:
    op.create_table(
        "usuarios",
        Column("id", INTEGER, primary_key=True),
        Column("name", VARCHAR(64), nullable=False),
    )
 
 
def downgrade() -> None:
    op.drop_table("usuarios")

De esta forma, la función upgrade() crea la tabla y downgrade() la elimina, lo que te permite revertir los cambios si es necesario.

Puedes consultar todas las operaciones que Alembic permite realizar en esta sección de la documentación.

Autogenerar scripts

Para evitar escribir las migraciones manualmente, puedes usar Alembic para comparar el esquema actual de la base de datos con tus modelos de SQLAlchemy y autogenerar un script con los cambios necesarios:

alembic revision --autogenerate -m "Mi migración"

Esto simplifica la creación de scripts, sin embargo, algunos cambios pueden no ser detectados correctamente, por lo que siempre es recomendable que verifiques la revisión generada.

Aplicar y revertir migraciones

Para aplicar las migraciones pendientes a la base de datos:

alembic upgrade head

Esto actualizará la base de datos a la versión más reciente.

Para revertir la última migración aplicada:

alembic downgrade -1

Este comando revierte la última migración. También puedes especificar un número de revisión para revertir hasta una versión específica.

Resumen

Alembic es una herramienta esencial para gestionar el ciclo de vida de la base de datos en proyectos que usan SQLAlchemy. Facilita la creación de migraciones incrementales, tanto manual como automáticamente, asegurando que los cambios en el esquema se realicen de manera segura y eficiente.

Para más información y opciones avanzadas, consulta la documentación oficial de Alembic.