Alembic: Migrações de Banco de Dados com Python e SQLAlchemy

Introdução

O desenvolvimento de aplicações web modernas está inevitavelmente ligado à evolução da estrutura do banco de dados. Adicionar novas tabelas, alterar tipos de dados, criar índices e modificar relacionamentos entre entidades — tudo isso exige uma abordagem sistemática de gerenciamento. Fazer alterações manuais no esquema do banco de dados pode causar erros, perda de dados e inconsistências entre diferentes ambientes de desenvolvimento.

O Alembic é uma ferramenta poderosa para gerenciar migrações de banco de dados, desenvolvida especialmente para o ecossistema SQLAlchemy. É a solução oficial que garante alterações seguras e controladas na estrutura do banco de dados, permitindo que desenvolvedores acompanhem o histórico de mudanças, apliquem atualizações e, se necessário, revertam modificações problemáticas.

O que é Alembic

Alembic é uma biblioteca para gerenciamento de migrações de banco de dados em projetos Python que utilizam SQLAlchemy. Ela fornece ferramentas para criar, aplicar e reverter alterações no esquema do banco de dados de forma controlada.

Principais vantagens do Alembic

Versionamento de esquema de banco de dados — cada alteração é registrada como uma migração individual com um identificador único, permitindo rastrear a evolução da estrutura dos dados.

Geração automática de migrações — possibilidade de criar arquivos de migração com base em alterações nos modelos ORM do SQLAlchemy, acelerando significativamente o processo de desenvolvimento.

Segurança nas operações — todas as alterações são aplicadas dentro de transações, minimizando o risco de corrupção de dados.

Suporte a diversos SGBDs — funciona com PostgreSQL, MySQL, SQLite, Oracle e outros bancos de dados suportados pelo SQLAlchemy.

Instalação e configuração do Alembic

Instalação do pacote

pip install alembic

Para trabalhar com aplicações assíncronas, também é necessário instalar dependências adicionais:

pip install alembic[asyncio]

Inicialização do projeto de migrações

Após a instalação, é preciso inicializar a estrutura do projeto:

alembic init alembic

O comando criará a seguinte estrutura de arquivos:

alembic/
├── versions/           # Diretório para arquivos de migração
├── env.py             # Configuração do ambiente
├── script.py.mako     # Template para geração de migrações
└── alembic.ini        # Arquivo principal de configuração

Configuração da conexão com o banco de dados

No arquivo alembic.ini, informe a string de conexão com o banco de dados:

sqlalchemy.url = postgresql://usuario:senha@localhost/nome_do_banco

Alternativamente, a conexão pode ser configurada programaticamente no arquivo env.py:

from sqlalchemy import create_engine
from meuprojeto.config import DATABASE_URL

config.set_main_option("sqlalchemy.url", DATABASE_URL)

Integração com SQLAlchemy

Conectando modelos

Para que a autogeração de migrações funcione corretamente, é necessário informar os metadados dos modelos no arquivo alembic/env.py:

from meuprojeto.models import Base

# Informa os metadados para autogeração
target_metadata = Base.metadata

Exemplo de modelo básico

from sqlalchemy import Column, Integer, String, DateTime, Boolean
from sqlalchemy.ext.declarative import declarative_base
from datetime import datetime

Base = declarative_base()

class Usuario(Base):
    __tablename__ = 'usuarios'
    
    id = Column(Integer, primary_key=True)
    nome_usuario = Column(String(50), unique=True, nullable=False)
    email = Column(String(100), unique=True, nullable=False)
    ativo = Column(Boolean, default=True)
    criado_em = Column(DateTime, default=datetime.utcnow)