VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
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:
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:
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:
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: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:
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 umenv.py já preparado para um engine assíncrono:
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:
alembic/env.py para importar os modelos, para que o autogenerate consiga vê-los:
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:
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: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 usamysql+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. Oenv.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
- Usando MySQL com ORMs: Django, Rails e Prisma — a mesma configuração de charset e modo estrito se aplica ao SQLAlchemy
- Pool de Conexões no MySQL — ajustando o tamanho do pool para um engine assíncrono sob requisições FastAPI concorrentes