FastAPI: Banco de Dados, Modelos e Migrações

Introdução ao FastAPI com persistência de dados

FastAPI é um framework moderno para construção de APIs REST em Python que ganhou popularidade pela sua velocidade, validação automática de dados e documentação interativa. No entanto, criar uma API funcional vai além de apenas definir endpoints — é necessário integrar um banco de dados, estruturar modelos de dados e gerenciar mudanças no esquema através de migrações. Este vídeo da Hashtag Programação aborda justamente esses componentes essenciais, transformando uma API básica em um sistema de back-end robusto e pronto para produção.

Integrando bancos de dados em FastAPI

O primeiro passo para construir um back-end persistente é estabelecer a conexão com um banco de dados. FastAPI não inclui um ORM (Object-Relational Mapping) nativo, mas funciona perfeitamente com bibliotecas como SQLAlchemy, que abstrai a complexidade de SQL puro e oferece uma interface Pythônica para manipular dados. A integração envolve configurar a string de conexão, criar uma sessão reutilizável e disponibilizá-la aos endpoints através de dependency injection — um padrão que FastAPI implementa de forma elegante. Essa abordagem garante que cada requisição tenha acesso ao banco sem poluir o código com boilerplate repetitivo.

Estruturando modelos com Pydantic e SQLAlchemy

Modelos são o coração da arquitetura de dados. Em FastAPI, é comum trabalhar com dois tipos de modelos: Pydantic (para validação de entrada e saída de dados) e SQLAlchemy (para representação das tabelas no banco). O Pydantic define o contrato da API, validando tipos, valores padrão e restrições. O SQLAlchemy mapeia essas estruturas para tabelas SQL, permitindo operações CRUD sem escrever queries manualmente. Compreender a diferença entre esses dois modelos e como eles interagem é fundamental para manter o código limpo, seguro e fácil de manter. Muitos desenvolvedores iniciantes confundem quando usar cada um, resultando em código redundante ou difícil de debugar.

Validação e relacionamentos entre tabelas

Bancos de dados relacionais funcionam através de chaves estrangeiras que conectam tabelas. Em FastAPI com SQLAlchemy, é possível definir relacionamentos (one-to-many, many-to-many) de forma declarativa, tornando a navegação entre entidades intuitiva. Além disso, o Pydantic oferece validadores customizados para garantir que dados inválidos nunca cheguem ao banco. Combinando essas ferramentas, é possível criar modelos que não apenas armazenam dados, mas também garantem integridade referencial e semântica. Isso reduz bugs silenciosos e comportamentos inesperados em produção.

O papel das migrações no desenvolvimento

À medida que um projeto evolui, o esquema do banco de dados muda — novas colunas são adicionadas, tabelas são criadas ou estruturas são refatoradas. Migrações são scripts que rastreiam essas mudanças de forma controlada e versionada. Ferramentas como Alembic, frequentemente usadas com SQLAlchemy, geram migrações automaticamente ao detectar diferenças entre o código de modelos e o banco atual. Isso permite que múltiplos desenvolvedores trabalhem simultaneamente, que o histórico de mudanças seja preservado e que rollbacks sejam possíveis em caso de erro. Sem migrações, fazer backup do banco e restaurar após uma mudança se torna um pesadelo operacional.

Gerenciando migrações com Alembic

Alembic é a ferramenta padrão para migrações em projetos Python com SQLAlchemy. Ele cria um arquivo de versão para cada mudança no banco, com um timestamp e uma descrição legível. Cada migração contém uma função upgrade (para aplicar a mudança) e downgrade (para reverter). O fluxo básico envolve executar alembic revision --autogenerate após modificar os modelos, revisar o SQL gerado, fazer ajustes se necessário, e então aplicar com alembic upgrade head. Esse processo garante rastreabilidade total — qualquer pessoa pode entender quando, por que e como o banco foi alterado apenas lendo o histórico de commits e migrações.

Boas práticas e armadilhas comuns

Ao trabalhar com FastAPI, modelos e migrações, existem padrões que experimentados evitam. Por exemplo, nunca exportar sessões diretamente em variáveis globais; sempre usar dependency injection. Não misturar lógica de negócio com queries SQL puro — manter a camada de dados separada. Testar migrações em ambiente isolado antes de rodar em produção. Documentar mudanças significativas no esquema para o time entender o impacto. Muitos problemas em produção surgem de negligência nessas práticas, especialmente em projetos que crescem rápido ou com múltiplos colaboradores.

Próximas etapas no desenvolvimento do back-end

Com banco de dados, modelos e migrações estruturados, o próximo nível é implementar autenticação e autorização robustas, adicionar testes automatizados para garantir que mudanças não quebrem endpoints, e otimizar queries para evitar N+1 problems e outras armadilhas de performance. Também é recomendável estudar padrões de cache, implementação de transações ACID e estratégias de backup em produção.