Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
O tratamento assíncrono de requisições do FastAPI só compensa se as chamadas ao banco de dados por baixo dele também forem assíncronas. O SQLAlchemy 2.0 suporta isso com um estilo de ORM tipado e um engine assíncrono, mas conectar os dois com o MySQL tem alguns passos de configuração fáceis de errar na primeira tentativa.

Escolhendo um Driver Assíncrono

O SQLAlchemy 2.0 traz dialetos para dois drivers MySQL assíncronos: asyncmy e aiomysql. Nenhum dos dois é documentado como a recomendação oficial sobre o outro. O asyncmy é um driver compilado escrito em Cython e distribui wheels pré-compilados para as versões atuais do Python, e é por isso que ele é usado neste guia:
Instalar o sqlalchemy puro em vez de sqlalchemy[asyncio] é a primeira armadilha real. A camada ORM assíncrona do SQLAlchemy faz a ponte entre código assíncrono e síncrono com a biblioteca greenlet, e ela não é uma dependência do pacote base. Pular o extra [asyncio] produz este erro na primeira vez que você toca no engine assíncrono:
A correção é pip install greenlet ou, melhor, sempre instalar o SQLAlchemy com o extra [asyncio], para que ela seja incluída automaticamente. A segunda armadilha é o cryptography. O MySQL 8 e o VillageSQL usam por padrão o plugin de autenticação caching_sha2_password para contas novas, que precisa de uma troca de chaves RSA para enviar a senha na primeira vez que uma dada conta se autentica a partir de uma dada biblioteca cliente. O asyncmy não inclui uma implementação de RSA, então uma conexão que precisa fazer esse handshake completo falha com:
Depois que uma conta completa uma autenticação completa (a partir de qualquer cliente, incluindo a CLI mysql), o servidor armazena o resultado em cache e as conexões seguintes usam um caminho mais rápido que pula a etapa RSA, e é por isso que esse erro pode parecer ir e voltar dependendo de quem se conectou à conta mais recentemente. Instalar o cryptography desde o início remove por completo a dependência desse cache e é a correção confiável.

Criando o Banco de Dados e o Usuário

Crie um banco de dados dedicado e um usuário de aplicação em vez de se conectar como root:
O usuário tem escopo em 127.0.0.1, não em localhost. A string de conexão deste guia se conecta via TCP a 127.0.0.1, então a concessão precisa corresponder a esse host; uma conexão por socket Unix é comparada com localhost em vez disso, independentemente das concessões baseadas em IP da conta.

Estrutura do Projeto

requirements.txt:

O Engine Assíncrono e a Sessão

app/database.py cria o engine assíncrono, uma fábrica de sessões e a base declarativa usada por todos os modelos:
expire_on_commit=False importa para o FastAPI. Com o padrão expire_on_commit=True, todo atributo de um objeto commitado é marcado como obsoleto, e a próxima leitura desse atributo emite um novo SELECT para atualizá-lo. Disparada fora de um await, essa atualização falha com:
e, depois que a sessão foi totalmente fechada, a mesma leitura de atributo falha, em vez disso, com:
expire_on_commit=False mantém os valores já carregados no objeto utilizáveis após o commit, o que evita os dois. get_session() é uma função geradora, o que permite ao Depends() do FastAPI fechar a sessão automaticamente depois que a requisição termina, seja com sucesso ou com uma exceção.

O Modelo

app/models.py define uma tabela Post usando o estilo declarativo tipado do SQLAlchemy 2.0, Mapped e mapped_column, em vez do estilo legado apenas com Column:
server_default=func.now() delega o valor padrão do timestamp ao próprio MySQL, então ele é definido corretamente mesmo para linhas inseridas fora da aplicação.

Configurando o Alembic

Inicialize o Alembic com o template assíncrono, que gera um env.py já preparado para um engine assíncrono:
Execute isso de dentro do diretório do projeto. O Alembic grava o alembic.ini no diretório de trabalho atual, independentemente do caminho passado ao init, embora a pasta de scripts alembic/ em si seja criada no caminho informado. Executá-lo do diretório errado deixa um alembic.ini perdido em algum lugar inesperado. Aponte o alembic.ini para o banco de dados ativo:
Em seguida, edite alembic/env.py para importar os modelos, para que o autogenerate consiga vê-los:
Gere e execute a migração:
A etapa de autogenerate detectou a nova tabela e escreveu a migração:
Aplicá-la no VillageSQL teve sucesso:
Confirmando diretamente no servidor ativo:

Os Esquemas Pydantic

app/schemas.py define as formas de requisição e resposta separadamente do modelo ORM:
from_attributes=True permite que PostRead construa a sua resposta diretamente a partir de uma instância ORM Post, em vez de um dicionário.

As Rotas do FastAPI

app/main.py conecta a sessão a cada rota por meio de Depends(), de modo que cada requisição recebe a sua própria sessão em vez de compartilhar uma conexão global:
Uma sessão global compartilhada entre requisições acaba levando a consultas intercaladas chegando fora de ordem na mesma conexão sob carga concorrente. Uma sessão criada por requisição por meio de Depends() evita isso, já que cada requisição recebe a sua própria sessão e a sua própria conexão retirada do pool.

Executando e Verificando

Inicie a aplicação:
Uma tabela vazia retorna uma lista vazia:
Criando um post:
com um status HTTP 201. Listar novamente mostra a nova linha:
Consultar o banco de dados diretamente confirma que a escrita chegou, e não apenas a resposta da API:

Perguntas Frequentes

Por que o engine assíncrono precisa de uma string de conexão diferente de um engine síncrono?

O nome do driver na string de conexão informa ao SQLAlchemy qual DBAPI carregar. Uma configuração síncrona usa mysql+pymysql:// ou mysql+mysqldb://; uma configuração assíncrona precisa de um driver construído sobre asyncio, então a string usa mysql+asyncmy:// em vez disso. Usar o nome de um driver síncrono com create_async_engine falha imediatamente, já que esse driver não tem uma interface assíncrona que o SQLAlchemy possa chamar.

Preciso de expire_on_commit=False?

Não estritamente, mas se você pular isso, todo acesso a atributo em um objeto commitado dispara uma nova ida ao banco de dados para recarregá-lo, e essa ida só funciona se acontecer dentro de um contexto assíncrono ativo. Dependendo de exatamente onde o atributo é lido, isso aparece como MissingGreenlet ou, depois que a sessão foi fechada, DetachedInstanceError. O padrão mais seguro para uma aplicação web é expire_on_commit=False.

Ainda posso usar o fluxo síncrono de autogenerate do Alembic?

Sim. O env.py do template assíncrono ainda executa revision --autogenerate e upgrade pela linha de comando normal; a parte assíncrona afeta apenas como o env.py abre a sua própria conexão para inspecionar e modificar o esquema. Nada nos comandos da CLI do Alembic em si muda.

Solução de Problemas

Veja também