O MySQL é um dos bancos de dados relacionais mais populares do mundo, e quando combinado com Python, forma uma dupla imbatível para aplicações web, análise de dados e sistemas empresariais. Se você está construindo uma API REST, um sistema de gestão ou qualquer aplicação que precise armazenar dados de forma confiável, dominar a integração entre Python e MySQL é uma habilidade essencial.
Neste guia completo, você aprenderá desde a instalação dos conectores até técnicas avançadas como connection pooling, uso de ORMs e boas práticas de segurança. Todos os exemplos são funcionais e testados com Python 3.12+ e MySQL 8.0+.
Por que usar MySQL com Python?
O ecossistema Python oferece múltiplas formas de se conectar ao MySQL, cada uma com vantagens específicas. O mysql-connector-python é o driver oficial mantido pela Oracle, enquanto o PyMySQL é uma alternativa puramente Python que não depende de bibliotecas C externas. Ambos seguem a especificação PEP 249 — Python Database API Specification, que padroniza a interface de bancos de dados em Python.
Antes de começarmos, se você ainda não tem um ambiente Python configurado, recomendo nosso guia sobre instalação e configuração do ambiente Python para preparar tudo corretamente.
Instalação dos Conectores
mysql-connector-python (Oficial Oracle)
pip install mysql-connector-pythonO driver oficial da Oracle é a escolha mais segura para ambientes corporativos, com suporte completo a todos os recursos do MySQL 8.0+, incluindo autenticação caching_sha2_password, conexões SSL/TLS e protocolo X DevAPI.
PyMySQL (Alternativa Pura Python)
pip install pymysqlO PyMySQL é uma excelente opção quando você precisa de uma instalação leve e portável, sem dependências de bibliotecas C. Ele é particularmente útil em ambientes de desenvolvimento ou em containers Docker onde o tamanho da imagem é uma preocupação.
SQLAlchemy (ORM + Core)
pip install sqlalchemy pymysqlO SQLAlchemy é o ORM (Object-Relational Mapper) mais maduro do ecossistema Python. Ele abstrai as diferenças entre bancos de dados e oferece uma camada de alto nível para trabalhar com MySQL, PostgreSQL, SQLite e outros. Se você prefere uma abordagem mais produtiva, o SQLAlchemy é o caminho.
Conexão Básica com MySQL
Com mysql-connector-python
import mysql.connector
config = {
"host": "localhost",
"user": "root",
"password": "sua_senha",
"database": "meu_banco"
}
conexao = mysql.connector.connect(**config)
print(f"Conectado ao MySQL versão {conexao.get_server_info()}")
conexao.close()
Com PyMySQL
import pymysql
conexao = pymysql.connect(
host="localhost",
user="root",
password="sua_senha",
database="meu_banco",
charset="utf8mb4",
cursorclass=pymysql.cursors.DictCursor
)
with conexao.cursor() as cursor:
cursor.execute("SELECT VERSION()")
resultado = cursor.fetchone()
print(f"Versão: {resultado}")
conexao.close()
Note o uso de DictCursor no PyMySQL. Esse cursor retorna resultados como dicionários, onde as colunas são as chaves — muito mais legível que tuplas numéricas.
Operações CRUD com Python e MySQL
Vamos criar uma tabela de exemplo e executar as quatro operações fundamentais: Create (inserir), Read (ler), Update (atualizar) e Delete (remover).
1. CREATE — Inserindo Dados
import mysql.connector
conexao = mysql.connector.connect(
host="localhost", user="root", password="sua_senha", database="meu_banco"
)
cursor = conexao.cursor()
sql = "INSERT INTO usuarios (nome, email, idade) VALUES (%s, %s, %s)"
valores = ("Maria Silva", "[email protected]", 28)
cursor.execute(sql, valores)
conexao.commit()
print(f"Usuário inserido com ID: {cursor.lastrowid}")
cursor.close()
conexao.close()
Importante: Nunca use f-strings ou concatenação para montar SQL. O uso de %s como placeholder protege contra injeção SQL, um dos ataques mais comuns em aplicações web. A Real Python possui um guia aprofundado sobre segurança em MySQL com Python que vale a pena consultar.
2. READ — Consultando Dados
cursor = conexao.cursor(dictionary=True)
sql = "SELECT id, nome, email, idade FROM usuarios WHERE idade > %s"
cursor.execute(sql, (18,))
for usuario in cursor.fetchall():
print(f"{usuario['nome']} — {usuario['email']} — {usuario['idade']} anos")
O parâmetro dictionary=True no mysql-connector-python (equivalente ao DictCursor do PyMySQL) faz com que cada linha seja retornada como um dicionário, facilitando o acesso pelos nomes das colunas.
3. UPDATE — Atualizando Registros
sql = "UPDATE usuarios SET email = %s WHERE id = %s"
cursor.execute(sql, ("[email protected]", 1))
conexao.commit()
print(f"Linhas afetadas: {cursor.rowcount}")
4. DELETE — Removendo Registros
sql = "DELETE FROM usuarios WHERE id = %s"
cursor.execute(sql, (10,))
conexao.commit()
print(f"Linhas removidas: {cursor.rowcount}")
Para cenários mais complexos, como operações que envolvem múltiplas tabelas, confira nosso guia sobre SQLite com Python — os fundamentos de SQL se aplicam igualmente ao MySQL, e os conceitos de transação e commit são idênticos.
Connection Pooling em Python com MySQL
Em aplicações reais, abrir e fechar conexões a cada requisição é ineficiente. O connection pooling mantém um conjunto de conexões reutilizáveis, reduzindo drasticamente a latência e o consumo de recursos.
import mysql.connector.pooling
pool = mysql.connector.pooling.MySQLConnectionPool(
pool_name="meu_pool",
pool_size=10,
pool_reset_session=True,
host="localhost",
user="root",
password="sua_senha",
database="meu_banco"
)
def buscar_usuario(user_id):
conexao = pool.get_connection()
cursor = conexao.cursor(dictionary=True)
cursor.execute("SELECT * FROM usuarios WHERE id = %s", (user_id,))
usuario = cursor.fetchone()
cursor.close()
conexao.close()
return usuario
O pool gerencia automaticamente a criação e destruição de conexões. Em aplicações web com FastAPI ou Django, você configura o pool uma vez na inicialização e reutiliza em todos os endpoints. A documentação oficial de connection pooling do MySQL detalha todos os parâmetros disponíveis.
Trabalhando com SQLAlchemy e MySQL
Para projetos de médio e grande porte, o SQLAlchemy oferece uma abstração que simplifica drasticamente o trabalho com MySQL. Com ele, você define modelos Python e o ORM gera automaticamente as tabelas e consultas SQL.
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import declarative_base, sessionmaker
engine = create_engine(
"mysql+pymysql://root:sua_senha@localhost:3306/meu_banco",
pool_size=10,
max_overflow=20
)
Base = declarative_base()
class Usuario(Base):
tablename = "usuarios"
id = Column(Integer, primary_key=True, autoincrement=True)
nome = Column(String(100), nullable=False)
email = Column(String(150), unique=True, nullable=False)
idade = Column(Integer)
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
sessao = Session()
Inserir
novo = Usuario(nome="João", email="[email protected]", idade=32)
sessao.add(novo)
sessao.commit()
Consultar
usuarios = sessao.query(Usuario).filter(Usuario.idade > 25).all()
for u in usuarios:
print(f"{u.nome} - {u.email}")
sessao.close()
O SQLAlchemy suporta migration com Alembic, lazy loading, eager loading, joins automatizados e muito mais. Se você está migrando de SQLite para MySQL, a mudança é quase transparente — basta alterar a string de conexão.
Tratamento de Erros e Transações
Toda aplicação robusta precisa lidar com falhas de banco de dados. Em Python, o tratamento é feito com try/except, e as transações garantem a consistência dos dados.
import mysql.connector
from mysql.connector import Error
try:
conexao = mysql.connector.connect(**config)
cursor = conexao.cursor()
conexao.start_transaction()
cursor.execute("UPDATE contas SET saldo = saldo - 100 WHERE id = 1")
cursor.execute("UPDATE contas SET saldo = saldo + 100 WHERE id = 2")
conexao.commit()
print("Transferência realizada com sucesso!")
except Error as e:
conexao.rollback()
print(f"Erro na transação: {e}")
finally:
if conexao.is_connected():
cursor.close()
conexao.close()
O método start_transaction() inicia uma transação explícita. Se qualquer operação falhar, o rollback() reverte todas as alterações, mantendo a integridade dos dados. O tutorial da DigitalOcean sobre MySQL com Python oferece exemplos adicionais de tratamento de erros em cenários reais.
Migrações de Schema com Alembic
Conforme sua aplicação evolui, o schema do banco de dados precisa acompanhar as mudanças. O Alembic é a ferramenta de migração oficial do SQLAlchemy e permite versionar cada alteração na estrutura das tabelas.
pip install alembic
alembic init migrations
Criar uma migração
alembic revision --autogenerate -m "criar_tabela_usuarios"
Aplicar migrações
alembic upgrade head
Com o Alembic, você pode reverter migrações (alembic downgrade), gerar automaticamente scripts a partir dos modelos SQLAlchemy e manter o histórico completo de alterações do banco em arquivos versionados no Git. É uma prática indispensável em projetos mantidos por equipes, pois elimina o problema de schemas divergentes entre ambientes de desenvolvimento, staging e produção.
Usando MySQL com FastAPI de Forma Assíncrona
Para aplicações modernas que exigem alta concorrência, o driver aiomysql oferece operações assíncronas com MySQL, integrando-se perfeitamente com o ecossistema asyncio do Python.
import asyncio
import aiomysql
async def main():
pool = await aiomysql.create_pool(
host="localhost", user="root", password="sua_senha",
db="meu_banco", minsize=5, maxsize=20
)
async with pool.acquire() as conn:
async with conn.cursor() as cursor:
await cursor.execute("SELECT COUNT(*) FROM usuarios")
total = await cursor.fetchone()
print(f"Total de usuários: {total[0]}")
pool.close()
await pool.wait_closed()
asyncio.run(main())
Combinado com FastAPI, esse padrão permite atender centenas de requisições simultâneas sem bloquear o loop de eventos. Cada requisição adquire uma conexão do pool, executa a consulta e devolve a conexão ao pool de forma eficiente.
Boas Práticas de Segurança
- Nunca armazene credenciais no código: Use variáveis de ambiente ou arquivos
.env. A bibliotecapython-dotenvfacilita o gerenciamento de configurações. - Sempre use placeholders:
%sou?nos SQL statements evitam injeção SQL. Nunca concatene strings com dados do usuário. - SSL/TLS em produção: Configure certificados SSL para criptografar a comunicação entre Python e MySQL, especialmente em conexões remotas.
- Princípio do menor privilégio: Crie usuários MySQL com permissões específicas para cada aplicação, evitando o uso do usuário root.
- Valide dados antes de inserir: Use type hints e bibliotecas como Pydantic para validar os dados antes de enviá-los ao banco.
Se você trabalha com múltiplos bancos de dados, nosso guia sobre MongoDB com Python mostra como integrar bancos NoSQL ao lado do MySQL em aplicações híbridas.
Performance e Otimização
Para aplicações com alto volume de requisições, algumas estratégias de performance são essenciais:
- Connection pooling: Reutilize conexões em vez de criar novas a cada operação.
- Batch inserts: Use
executemany()para inserir múltiplos registros em uma única operação. - Índices: Crie índices MySQL nas colunas usadas em cláusulas WHERE e JOIN.
- Fetch size: Use
cursor.fetchmany(tamanho)para processar grandes resultados em lotes. - Prepared statements: Reutilize planos de execução para consultas repetitivas.
# Batch insert com executemany
dados = [
("Ana", "[email protected]", 25),
("Pedro", "[email protected]", 32),
("Carla", "[email protected]", 29),
]
cursor.executemany(
"INSERT INTO usuarios (nome, email, idade) VALUES (%s, %s, %s)",
dados
)
conexao.commit()
print(f"{cursor.rowcount} registros inseridos.")Ferramentas e Recursos Adicionais
Além dos conectores padrão, o ecossistema Python oferece ferramentas complementares para trabalhar com MySQL:
- Alembic: Sistema de migração de schemas que funciona com SQLAlchemy, ideal para versionar alterações no banco de dados.
- mysqlclient: Driver alternativo baseado em C, mais rápido que PyMySQL em benchmarks de operações intensivas.
- aiomysql: Versão assíncrona do PyMySQL para uso com asyncio, perfeita para aplicações FastAPI de alta concorrência.
- SQLAlchemy 2.0: A versão mais recente do ORM traz suporte nativo a async/await e type hints integrados.
Para se aprofundar, recomendamos a leitura da documentação oficial do MySQL, que cobre desde administração até tuning de performance. O tutorial interativo da W3Schools sobre MySQL com Python também é um ótimo recurso para iniciantes praticarem os conceitos básicos.
Conclusão
A integração entre Python e MySQL é robusta, flexível e bem documentada. Neste guia, você aprendeu desde a instalação dos conectores até técnicas avançadas como connection pooling, ORM com SQLAlchemy e boas práticas de segurança. Com esses conhecimentos, você está preparado para construir aplicações Python escaláveis e seguras que utilizam o MySQL como base de dados.
O próximo passo natural é explorar tópicos como migrações de schema com Alembic, replicação MySQL para alta disponibilidade e integração com frameworks web como FastAPI e Django. Continue explorando o Universo Python e aprofunde seus conhecimentos em bancos de dados relacionais e NoSQL com nossos guias gratuitos.
Links internos recomendados: