Migrações com Alembic
Autogerar, revisar e aplicar revisões de esquema.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
alembic revision --autogenerate -m "adicionar coluna"
alembic upgrade headQuando usar isso:
- Toda alteração de esquema rastreada
- Implantações em múltiplos ambientes
- Planejamento de rollback
Exemplo de Trabalho
def upgrade():
op.add_column("items", sa.Column("sku", sa.String(32), nullable=True))O que isso demonstra:
- fluxo de trabalho de autogeração
- operações de upgrade
- cadeia de revisão
Análise Detalhada
Como Funciona
- O Alembic compara metadados com o banco de dados ativo.
- Revise humanamente o autogerado antes de mesclar.
- Mantenha as migrações retrocompatíveis para zero downtime.
Armadilhas
- Validação de limite ignorada - Dados inválidos chegam às camadas de persistência. Correção: Valide com Pydantic ou formulários do framework na borda.
- Vazamento de traces de pilha - Clientes veem erros internos. Correção: Mapeie exceções para respostas HTTP estáveis.
- Bloqueio de loops de eventos assíncronos - Workers param sob carga concorrente. Correção: Use drivers assíncronos ou wrappers de threadpool.
- Segredos em controle de código fonte - Credenciais vazam pelo histórico do git. Correção: Carregue segredos de variáveis de ambiente ou de um vault em tempo de execução.
- Falta de observabilidade - Incidentes são difíceis de depurar. Correção: Adicione logs estruturados, métricas e IDs de requisição.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Framework alternativo neste cookbook | Padrão da equipe ou monólito existente | API Greenfield com restrições diferentes |
| BaaS Gerenciado | MVP apenas CRUD | Autenticação personalizada, fluxos de trabalho ou necessidades de conformidade |
| gRPC | RPC interno de alta performance | Clientes HTTP públicos e acesso ao navegador |
FAQs
Quando devo adotar migrações do Alembic?
Use-o quando os padrões e trade-offs desta página corresponderem à sua API ou limite de dados.
Qual é o principal erro de produção com migrações do Alembic?
Ignorar validação, timeouts ou contratos de erro explícitos na borda HTTP.
Como testar migrações do Alembic?
Use o cliente de teste do framework, substitua dependências e afirme o status mais a forma do JSON.
As migrações do Alembic funcionam com Python 3.14?
Sim - os exemplos visam Python 3.14 com versões de framework fixadas do rodapé da stack.
Como as migrações do Alembic se relacionam com Pydantic 2?
Valide e serialize nas bordas; mantenha os serviços funcionando com objetos de domínio tipados.
Síncrono ou assíncrono?
Prefira rotas assíncronas quando I/O domina; mantenha o trabalho de CPU pequeno ou descarregue para workers.
Onde a lógica de negócios deve residir?
Handlers finos; serviços possuem regras; repositórios possuem consultas.
Como documentar APIs?
Publique documentação OpenAPI ou de esquema que corresponda aos modelos de resposta no código.
Como lidar com versionamento?
Versionamento explícito por URL ou cabeçalho com janelas de depreciação - evite quebras silenciosas.
O que devo ler a seguir?
Siga os links Relacionados para a próxima camada de profundidade nesta seção.
Como me mantenho seguro?
Autentique chamadores, autorize por recurso, limite a taxa e nunca registre segredos.
Primeiro passo de performance?
Meça a latência do banco de dados e upstream antes de trocar de framework.
Relacionados
- Noções Básicas de Banco de Dados - Conexões e transações
- SQLAlchemy ORM 2.0 - Padrões ORM
- Migrações com Alembic - Alterações de esquema
- Acesso Assíncrono a Banco de Dados - asyncpg
Versões da Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.