Quando o assunto é desenvolvimento backend com Python, a escolha do banco de dados é uma das decisões mais importantes do projeto. O MongoDB, banco NoSQL mais popular do mundo, tem se destacado como a opção preferida para aplicações que exigem flexibilidade, escalabilidade e performance. Neste guia completo, você vai aprender tudo sobre como integrar Python com MongoDB usando o driver oficial PyMongo, desde a instalação até um projeto prático completo.
O que é MongoDB?
MongoDB é um banco de dados NoSQL orientado a documentos. Diferente dos bancos relacionais tradicionais como MySQL ou PostgreSQL, que armazenam dados em tabelas com linhas e colunas fixas, o MongoDB armazena dados em documentos flexíveis no formato BSON (uma extensão binária do JSON). Cada documento pode ter uma estrutura diferente, o que torna o MongoDB ideal para aplicações com esquemas dinâmicos, prototipação rápida e integração com dados de fontes variadas.
Entre os casos de uso mais comuns do MongoDB estão: sistemas de catálogo de produtos, plataformas de e-commerce, sistemas de gerenciamento de conteúdo, aplicações IoT, análise de dados em tempo real e armazenamento de logs. Grandes empresas como Forbes, Uber e EA Sports utilizam MongoDB em produção. Você pode conferir mais detalhes sobre o banco na documentação oficial do MongoDB.
Por que usar Python com MongoDB?
A combinação Python + MongoDB é natural e poderosa por vários motivos. Primeiro, a estrutura de documentos do MongoDB se assemelha aos dicionários do Python, o que torna a conversão entre os dois praticamente automática. Segundo, o driver PyMongo é maduro, bem documentado e segue as melhores práticas da linguagem. Terceiro, a flexibilidade do esquema do MongoDB permite que você evolua sua aplicação sem precisar migrar bancos de dados inteiros.
Além disso, o ecossistema Python oferece bibliotecas complementares que se integram perfeitamente ao MongoDB, como pandas para análise de dados e Flask ou FastAPI para construção de APIs. Se você está começando agora com Python, recomendo conferir nosso guia sobre gerenciamento de dependências com pip antes de prosseguir.
Instalação e Configuração
Instalando o MongoDB
Antes de escrever qualquer código, você precisa ter o MongoDB instalado. Existem duas formas principais: instalar localmente ou usar uma instância na nuvem com o MongoDB Atlas. Para desenvolvimento local, acesse o download do MongoDB Community Server e escolha a versão para seu sistema operacional. No Windows, o instalador inclui o MongoDB como serviço do Windows. No Linux, você pode instalar via gerenciador de pacotes. No macOS, o Homebrew facilita a instalação com brew install mongodb-community.
Se preferir não instalar nada localmente, o MongoDB Atlas oferece uma camada gratuita (M0) com 512 MB de armazenamento, perfeita para aprendizado e projetos pessoais. Basta criar uma conta, configurar um cluster gratuito e obter a string de conexão.
Instalando o PyMongo
Com o Python e o MongoDB prontos, instale o driver oficial PyMongo usando pip:
pip install pymongoPara instalar com suporte a compressão e criptografia TLS/SSL, use:
pip install pymongo[snappy,gssapi,srv,tls]A biblioteca está disponível no PyPI, e a documentação completa pode ser encontrada na página oficial do PyMongo.
Verificando a Instalação
Para confirmar que tudo está funcionando, abra um terminal Python e execute:
import pymongo
print(pymongo.__version__)Se o comando retornar a versão instalada (ex: 4.9.1), a instalação foi bem-sucedida.
Conectando ao MongoDB
A conexão com o MongoDB é feita através da classe MongoClient. A string de conexão varia conforme o ambiente:
from pymongo import MongoClient
Conexão local (padrão)
cliente = MongoClient("mongodb://localhost:27017/")
Conexão com MongoDB Atlas
cliente = MongoClient("mongodb+srv://usuario:[email protected]/")
Acessando um banco de dados
db = cliente["meu_banco"]
Acessando uma coleção
colecao = db["minha_colecao"]
O MongoDB é lazy: a conexão só é estabelecida de fato quando a primeira operação é executada. O objeto MongoClient gerencia automaticamente o pool de conexões, então você deve criar uma única instância global e reutilizá-la em toda a aplicação, em vez de criar uma nova conexão para cada operação.
É importante tratar exceções de conexão. Use try/except para capturar pymongo.errors.ConnectionFailure e pymongo.errors.ServerSelectionTimeoutError:
from pymongo.errors import ConnectionFailure, ServerSelectionTimeoutError
try:
cliente.admin.command("ping")
print("Conectado ao MongoDB!")
except (ConnectionFailure, ServerSelectionTimeoutError) as e:
print(f"Erro de conexão: {e}")
Operações CRUD com PyMongo
As operações CRUD (Create, Read, Update, Delete) são a base de qualquer aplicação que interage com um banco de dados. Vamos explorar cada uma delas com exemplos práticos.
Create: Inserindo Documentos
Para inserir um documento, use os métodos insert_one ou insert_many:
# Inserindo um único documento
usuario = {
"nome": "Ana Silva",
"email": "[email protected]",
"idade": 28,
"habilidades": ["Python", "MongoDB", "FastAPI"],
"ativo": True
}
resultado = colecao.insert_one(usuario)
print(f"ID do documento inserido: {resultado.inserted_id}")
Inserindo múltiplos documentos
usuarios = [
{"nome": "Carlos", "email": "[email protected]", "idade": 35},
{"nome": "Maria", "email": "[email protected]", "idade": 42},
{"nome": "João", "email": "[email protected]", "idade": 25}
]
resultados = colecao.insert_many(usuarios)
print(f"IDs inseridos: {resultados.inserted_ids}")
Se você não especificar um campo _id, o MongoDB gera automaticamente um ObjectId único. Você também pode definir seu próprio _id se precisar de um identificador personalizado.
Read: Consultando Documentos
Para consultar dados, use find_one (retorna um documento) ou find (retorna um cursor iterável):
# Buscar um documento por campo
usuario = colecao.find_one({"email": "[email protected]"})
print(usuario["nome"])
Buscar todos os documentos com filtro
usuarios_ativos = colecao.find({"ativo": True})
for usuario in usuarios_ativos:
print(usuario["nome"])
Projeção: selecionar campos específicos
usuarios = colecao.find(
{"idade": {"$gte": 30}},
{"nome": 1, "email": 1, "_id": 0}
)
Ordenação
usuarios_ordenados = colecao.find().sort("nome", 1) # 1 para ascendente, -1 para descendente
Limitar e pular resultados
pagina = colecao.find().sort("nome", 1).skip(0).limit(10)
O MongoDB oferece uma vasta gama de operadores de consulta como $gt, $lt, $in, $regex, $exists e muitos outros. Consulte o guia de aggregation do MongoDB para consultas mais avançadas.
Update: Atualizando Documentos
Para atualizar documentos, use update_one ou update_many:
# Atualizar um documento específico
colecao.update_one(
{"email": "[email protected]"},
{"$set": {"idade": 29, "ativo": True}}
)
Incrementar um valor numérico
colecao.update_one(
{"nome": "Carlos"},
{"$inc": {"idade": 1}}
)
Adicionar item a um array
colecao.update_one(
{"nome": "Ana Silva"},
{"$push": {"habilidades": "Docker"}}
)
Atualizar múltiplos documentos
colecao.update_many(
{"ativo": False},
{"$set": {"ativo": True}}
)
Os operadores de atualização como $set, $unset, $inc, $push, $pull e $addToSet permitem manipular documentos de forma precisa sem precisar reenviar o documento inteiro.
Delete: Removendo Documentos
Para remover documentos, use delete_one ou delete_many:
# Remover um documento
colecao.delete_one({"email": "[email protected]"})
Remover múltiplos documentos
colecao.delete_many({"ativo": False})
Remover todos os documentos de uma coleção (cuidado!)
colecao.delete_many({})
Remover a coleção inteira
colecao.drop()
Aggregation Pipeline
O Aggregation Pipeline é um dos recursos mais poderosos do MongoDB. Ele permite processar documentos em estágios sequenciais, similar ao pipeline de comandos no Unix. Cada estágio transforma os documentos de entrada e passa o resultado para o próximo estágio.
pipeline = [
{"$match": {"idade": {"$gte": 25}}},
{"$group": {
"_id": "$cidade",
"total": {"$sum": 1},
"media_idade": {"$avg": "$idade"}
}},
{"$sort": {"total": -1}},
{"$limit": 5}
]
resultados = colecao.aggregate(pipeline)
for resultado in resultados:
print(f"Cidade: {resultado['_id']}, Total: {resultado['total']}")
Os estágios mais comuns incluem $match (filtragem), $group (agrupamento), $sort (ordenação), $project (projeção/transformação), $lookup (join entre coleções) e $unwind (desconstrução de arrays).Dominar o aggregation pipeline é essencial para extrair insights avançados dos seus dados.
Índices e Performance
Índices são fundamentais para manter a performance do banco de dados à medida que os dados crescem. Sem índices, o MongoDB precisa fazer uma varredura completa em toda a coleção (collection scan) para encontrar os documentos, o que se torna inviável em coleções com milhões de documentos.
# Criar um índice simples em um campo
colecao.create_index("email")
Criar um índice composto
colecao.create_index([("cidade", 1), ("idade", -1)])
Criar um índice único
colecao.create_index("email", unique=True)
Criar um índice texto para busca textual
colecao.create_index([("nome", "text"), ("biografia", "text")])
Listar todos os índices da coleção
for indice in colecao.list_indexes():
print(indice)
Remover um índice
colecao.drop_index("email_1")
Use o método explain() para analisar como o MongoDB está executando suas consultas e verificar se os índices estão sendo utilizados. A documentação oficial de índices do MongoDB explica em detalhes cada tipo de índice disponível.
Boas Práticas com PyMongo
1. Pool de Conexões
Crie uma única instância de MongoClient e reutilize-a em toda a aplicação. O cliente gerencia internamente um pool de conexões. Configure maxPoolSize e minPoolSize conforme a carga esperada da sua aplicação.
2. Tratamento de Exceções
Sempre encapsule operações com o banco em blocos try/except. Além das exceções de conexão, capture DuplicateKeyError para violações de índice único e BulkWriteError para operações em lote.
3. Projeção de Campos
Sempre utilize projeção para retornar apenas os campos necessários. Isso reduz a quantidade de dados trafegados pela rede e melhora a performance das consultas.
# Em vez de trazer o documento inteiro...
usuario = colecao.find_one({"email": "[email protected]"})
...projete apenas os campos necessários
usuario = colecao.find_one(
{"email": "[email protected]"},
{"nome": 1, "email": 1}
)
4. Use bulk_write para Operações em Lote
Quando precisar inserir, atualizar ou deletar muitos documentos, prefira operações em lote com bulk_write em vez de chamadas individuais dentro de um loop. Isso reduz drasticamente o número de idas ao banco.
5. Índices Adequados
Analise suas consultas mais frequentes e crie índices que as cubram. Use o explain() para identificar consultas lentas e o MongoDB Compass para monitorar a performance visualmente.
Modelagem de Dados com MongoDB
Uma das decisões mais importantes ao trabalhar com MongoDB é como modelar seus dados. Diferente dos bancos relacionais, onde a normalização é a regra, o MongoDB incentiva a embedding (incorporação) de documentos relacionados dentro de um único documento sempre que possível. Isso reduz a necessidade de joins e melhora a performance de leitura.
Por exemplo, em um sistema de e-commerce, em vez de ter uma tabela de pedidos e outra de itens separadas, você pode incorporar os itens diretamente no documento do pedido:
pedido = {
"_id": ObjectId(),
"cliente": "Maria Souza",
"data": datetime.now(),
"total": 250.00,
"itens": [
{"produto": "Teclado Mecânico", "quantidade": 1, "preco": 200.00},
{"produto": "Mousepad", "quantidade": 1, "preco": 50.00}
],
"endereco_entrega": {
"rua": "Av. Paulista",
"numero": 1000,
"cidade": "São Paulo",
"cep": "01310-100"
}
}A regra geral é: incorpore quando a relação é do tipo "contém" (um-para-poucos) e referencie quando a relação é muitos-para-muitos ou quando os dados relacionados são grandes e acessados independentemente. O MongoDB também suporta $lookup para fazer joins entre coleções quando necessário.
Transações e Atomicidade
Embora o MongoDB seja conhecido por sua flexibilidade, ele também suporta transações multi-documento para cenários que exigem atomicidade. Uma transação garante que várias operações sejam executadas como uma única unidade: ou todas são aplicadas, ou nenhuma delas. Isso é essencial em sistemas financeiros, reservas e qualquer aplicação que exija consistência rigorosa.
Com o PyMongo, você pode usar transações em réplicas ou clusters sharded a partir da versão 4.0 do MongoDB:
from pymongo import MongoClient
cliente = MongoClient()
db = cliente["banco"]
contas = db["contas"]
transacoes = db["transacoes"]
with cliente.start_session() as sessao:
with sessao.start_transaction():
contas.update_one(
{"conta": "A"}, {"$inc": {"saldo": -100}}, session=sessao
)
contas.update_one(
{"conta": "B"}, {"$inc": {"saldo": 100}}, session=sessao
)
transacoes.insert_one({
"origem": "A", "destino": "B", "valor": 100
}, session=sessao)
Se qualquer operação falhar, todas são revertidas automaticamente
Transações devem ser usadas com moderação, pois têm custo de performance. Prefira operações atômicas em um único documento sempre que possível. O MongoDB garante atomicidade a nível de documento por padrão, o que cobre a maioria dos casos de uso.
Ferramentas do Ecossistema MongoDB
O ecossistema MongoDB oferece diversas ferramentas que facilitam o desenvolvimento e a administração do banco de dados. O MongoDB Compass é a interface gráfica oficial que permite visualizar e manipular dados, criar índices e analisar performance de consultas visualmente. O MongoDB Shell (mongosh) é o terminal interativo para administração avançada. Para testes locais durante o desenvolvimento, o mongod é o servidor de banco de dados, enquanto o mongos gerencia clusters sharded em produção.
Para projetos maiores, ferramentas como MongoDB Charts permitem criar visualizações de dados diretamente do banco, e o MongoDB Realm oferece sincronização em tempo real para aplicações mobile. Em ambientes de produção, é essencial configurar monitoramento com MongoDB Ops Manager ou Atlas Monitoring para acompanhar métricas como uso de memória, operações por segundo e latência de consultas.
Além do PyMongo, existem outras bibliotecas Python que abstraem a interação com MongoDB. O MongoEngine é um ODM (Object Document Mapper) que funciona de forma similar a um ORM, permitindo definir schemas com classes Python. O Beanie é um ODM assíncrono baseado em Pydantic que se integra perfeitamente com FastAPI. Para análise de dados, o pandas pode ler diretamente de coleções MongoDB usando pd.DataFrame(list(colecao.find())).
# Exemplo de integração MongoDB com pandas
import pandas as pd
from pymongo import MongoClient
cliente = MongoClient()
db = cliente["vendas"]
colecao = db["pedidos"]
Carregar dados do MongoDB para um DataFrame
df = pd.DataFrame(list(colecao.find({"status": "entregue"})))
print(f"Total de vendas: R$ {df['total'].sum():.2f}")
print(f"Média por pedido: R$ {df['total'].mean():.2f}")
Projeto Prático: Sistema de Biblioteca
Vamos consolidar tudo que aprendemos com um projeto prático: um sistema simples de gerenciamento de biblioteca. O sistema terá operações para adicionar livros, registrar empréstimos e gerar relatórios.
import pymongo
from pymongo import MongoClient
from datetime import datetime, timedelta
class Biblioteca:
def init(self):
self.cliente = MongoClient("mongodb://localhost:27017/")
self.db = self.cliente["biblioteca"]
self.livros = self.db["livros"]
self.emprestimos = self.db["emprestimos"]
self._criar_indices()
def _criar_indices(self):
self.livros.create_index("isbn", unique=True)
self.livros.create_index([("titulo", "text"), ("autor", "text")])
self.emprestimos.create_index("livro_id")
def adicionar_livro(self, titulo, autor, isbn, ano, copias=1):
livro = {
"titulo": titulo,
"autor": autor,
"isbn": isbn,
"ano": ano,
"copias_disponiveis": copias,
"copias_total": copias
}
try:
self.livros.insert_one(livro)
return f"Livro '{titulo}' adicionado com sucesso."
except pymongo.errors.DuplicateKeyError:
return f"ISBN {isbn} já existe no sistema."
def registrar_emprestimo(self, isbn, usuario):
livro = self.livros.find_one({"isbn": isbn})
if not livro or livro["copias_disponiveis"] <= 0:
return "Livro indisponível para empréstimo."
emprestimo = {
"livro_id": livro["_id"],
"usuario": usuario,
"data_emprestimo": datetime.now(),
"data_devolucao": datetime.now() + timedelta(days=14),
"devolvido": False
}
self.emprestimos.insert_one(emprestimo)
self.livros.update_one(
{"_id": livro["_id"]},
{"$inc": {"copias_disponiveis": -1}}
)
return f"Empréstimo registrado para {usuario}. Devolução em 14 dias."
def livros_mais_emprestados(self, limite=5):
pipeline = [
{"$group": {
"_id": "$livro_id",
"total_emprestimos": {"$sum": 1}
}},
{"$sort": {"total_emprestimos": -1}},
{"$limit": limite},
{"$lookup": {
"from": "livros",
"localField": "_id",
"foreignField": "_id",
"as": "livro"
}},
{"$unwind": "$livro"},
{"$project": {
"titulo": "$livro.titulo",
"autor": "$livro.autor",
"total_emprestimos": 1
}}
]
return list(self.emprestimos.aggregate(pipeline))
Exemplo de uso
biblio = Biblioteca()
biblio.adicionar_livro("Python para Dados", "Wes McKinney", "978-1-449-35901-7", 2023, 3)
biblio.adicionar_livro("MongoDB: The Definitive Guide", "Kristina Chodorow", "978-1-449-34480-9", 2022, 2)
print(biblio.registrar_emprestimo("978-1-449-35901-7", "Carlos"))
print(biblio.livros_mais_emprestados())
Conclusão
A integração entre Python e MongoDB com PyMongo é uma combinação poderosa e versátil para construir aplicações modernas. Neste guia, você aprendeu desde a instalação até um projeto completo, passando por operações CRUD, aggregation pipeline, índices e boas práticas. O ecossistema MongoDB é vasto e oferece recursos como Change Streams, Transações e GridFS para arquivos grandes. Para se aprofundar, recomendo fazer os cursos gratuitos da MongoDB University e acompanhar o blog oficial do MongoDB.
Se você ainda não configurou seu ambiente Python, confira nosso tutorial sobre ambientes virtuais com venv para manter suas dependências organizadas. Com esses conhecimentos, você está pronto para construir aplicações Python escaláveis e flexíveis com MongoDB!