Aula 5 – Curso de FastAPI 2025

O que é ORM e por que usar SQLAlchemy

Nesta aula, o instrutor Eduardo Mendes aprofunda o conhecimento sobre Object-Relational Mapping (ORM), uma abstração fundamental para trabalhar com bancos de dados em aplicações modernas. O SQLAlchemy é a biblioteca mais poderosa e adotada no ecossistema Python para esse fim. Uma ORM transforma tabelas de banco de dados em classes Python, permitindo que o desenvolvedor trabalhe com dados de forma orientada a objetos, sem escrever SQL bruto em muitos casos. Essa abordagem traz segurança contra injeção SQL, tipo de dados garantido e um código mais limpo e manutenível.

O SQLAlchemy oferece dois modos principais de operação: o Core, mais direto e próximo do SQL, e o ORM, que abstrai completamente a estrutura relacional. A escolha entre eles depende da complexidade e necessidade do projeto, mas o modo ORM é especialmente útil em aplicações web como as construídas com FastAPI, pois reduz drasticamente a quantidade de código repetitivo e aumenta a produtividade.

Criando modelos de dados com SQLAlchemy

A criação de modelos é o ponto de partida para qualquer aplicação que use SQLAlchemy. Um modelo é uma classe Python que herda de `Base`, a classe declarativa fornecida pela biblioteca. Cada atributo da classe corresponde a uma coluna no banco de dados, e o SQLAlchemy detecta automaticamente o tipo de dado, as restrições e outras propriedades. Nesta aula, o processo de definição de modelos é explicado na prática, mostrando como declarar tabelas, relacionamentos, índices e validações direto na classe.

Os modelos criados servem como ponte entre o código Python e o banco de dados. Ao usar SQLAlchemy, não é necessário criar manualmente as tabelas em SQL; a biblioteca pode gerar automaticamente o esquema do banco com base nos modelos definidos. Isso traz consistência entre o código e o banco de dados, facilitando manutenção e evolução da aplicação. Além disso, os modelos podem incluir métodos customizados que encapsulam lógica de negócio relacionada aos dados.

Testando modelos com pytest

Os testes são essenciais para garantir que os modelos funcionem corretamente e que as operações no banco de dados não quebrem sob diferentes cenários. O pytest é o framework de testes mais popular em Python, oferecendo uma sintaxe clara e poderosas fixtures para configurar ambientes de teste isolados. Nesta aula, aprendem-se as boas práticas para testar modelos SQLAlchemy, incluindo como criar instâncias, persistir dados em um banco de testes, validar relacionamentos e verificar se as constraints estão funcionando.

Os testes devem cobrir não apenas o caminho feliz (dados válidos), mas também casos extremos e erros. Por exemplo, testar se um campo obrigatório de fato rejeita `null`, se um índice único previne duplicatas, ou se um relacionamento cascata deleta registros dependentes conforme esperado. Usar um banco de dados em memória (SQLite) durante testes torna a execução rápida e isolada, sem depender de um banco externo.

Sistema de migrações com Alembic

Alembic é a ferramenta padrão para controle de versão de esquema em projetos SQLAlchemy. Migrações permitem rastrear e aplicar mudanças no banco de dados de forma controlada, similar ao Git para código-fonte. Quando um modelo muda (novo campo, mudança de tipo, etc.), uma migração é criada para refletir essa mudança no banco de produção sem perder dados. Nesta aula, o fundamento do Alembic é introduzido: como inicializar migrações em um projeto, gerar migrações automaticamente e aplicá-las.

O fluxo típico envolve modificar o modelo, usar `alembic revision --autogenerate` para criar um arquivo de migração, revisar o arquivo gerado, e então aplicar com `alembic upgrade head`. Essa abordagem garante que todas as máquinas (desenvolvimento, staging, produção) tenham o mesmo esquema de banco e que o histórico de mudanças seja transparente e auditável. Migrações manuais também são suportadas, úteis para operações complexas que a geração automática não cobre.

Integração com FastAPI

Integrar SQLAlchemy em uma aplicação FastAPI requer configurar uma conexão com o banco, criar uma sessão para cada requisição e passar os dados do banco para os endpoints. FastAPI fornece mecanismos de dependency injection que tornam isso limpo e testável. A sessão de banco deve ser criada, usada dentro do endpoint e fechada automaticamente, um padrão facilitado pela fixture de contexto.

Os modelos SQLAlchemy servem como camada de persistência, enquanto modelos Pydantic (schemas) servem como camada de validação de entrada e serialização de saída. Essa separação é uma boa prática que evita acoplamento e permite que o banco evoluam independentemente das APIs expostas.

Boas práticas e padrões em produção

Ao trabalhar com ORMs em produção, alguns padrões são críticos. Conexões devem ser gerenciadas com cuidado para evitar vazamentos de recursos. Índices devem ser criados em colunas frequentemente consultadas. Relacionamentos devem ser lazy-loaded ou eager-loaded conforme a necessidade, para evitar queries N+1. Transações devem ser usadas para garantir consistência em operações multi-passo.

O SQLAlchemy fornece ferramentas para otimização, como `selectinload`, `joinedload` e `contains_eager`, que controlam como relacionamentos são carregados. A monitoramento de queries executadas é importante para identificar gargalos. Em resumo, o domínio de SQLAlchemy em FastAPI é fundamental para construir aplicações escaláveis e mantíveis.

Próximos passos na evolução do projeto

Ao final desta aula, o aluno possui uma base sólida sobre persistência de dados em FastAPI. O curso continua com operações CRUD completas, validações de negócio, relacionamentos complexos e consultas avançadas. Compreender ORM, testes e migrações neste estágio garante que a arquitetura do projeto seja robusta desde o início.