Remover Coleção MongoDB em Python

Remover uma coleção MongoDB exclui permanentemente todos os documentos nela contidos e remove a própria coleção. A operação é imediata e não pode ser revertida, por isso vale a pena entender exatamente o que o PyMongo oferece, como verificar se uma coleção existe antes de agir sobre ela e qual método escolher em diferentes situações.

Este capítulo aborda:

• As duas formas de remover uma coleção — Collection.drop() e Database.drop_collection()
• Como verificar se uma coleção existe antes de removê-la
• Tratamento de erros de forma adequada
• Padrões seguros de teardown para testes e migrações

Pré-requisitos: Python 3.8+, PyMongo instalado (pip install pymongo) e um servidor MongoDB em execução. Consulte MongoDB Get Started e MongoDB Create Database se precisar configurá-los primeiro.

Conectando ao MongoDB

Toda operação começa com um MongoClient. Passe a string de conexão do seu servidor:

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["mydatabase"]

Se o seu servidor exigir autenticação, inclua as credenciais no URI:

client = pymongo.MongoClient("mongodb://username:password@localhost:27017/")

Consulte MongoDB Create Database para uma discussão completa sobre as opções de conexão.

Removendo uma Coleção com drop()

A abordagem mais direta é chamar drop() em um objeto Collection:

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["mydatabase"]
col = db["mycollection"]

col.drop()
print("Collection dropped.")

drop() retorna True se a coleção existia e foi removida, ou False se a coleção não existia. O PyMongo não lança um erro quando você tenta remover uma coleção inexistente — ele retorna False silenciosamente.

result = col.drop()
print(result)  # True if it existed, False if it was already gone

Removendo uma Coleção com drop_collection()

Você também pode remover uma coleção através do objeto Database usando drop_collection(). Isso é útil quando você só tem o nome da coleção como uma string e não quer criar um objeto Collection primeiro:

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["mydatabase"]

db.drop_collection("mycollection")
print("Collection dropped via database method.")

drop_collection() também aceita um objeto Collection diretamente, portanto os dois exemplos a seguir são equivalentes:

# By name (string)
db.drop_collection("mycollection")

# By Collection object
col = db["mycollection"]
db.drop_collection(col)

Qual método devo usar?

Verificando se uma Coleção Existe Primeiro

Como drop() tem sucesso silencioso em uma coleção inexistente, você pode querer confirmar que a coleção existe antes de removê-la — por exemplo, para registrar um aviso ou evitar saídas enganosas em um script:

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["mydatabase"]

collection_name = "mycollection"

if collection_name in db.list_collection_names():
    db.drop_collection(collection_name)
    print(f"'{collection_name}' was dropped.")
else:
    print(f"'{collection_name}' does not exist — nothing to drop.")

db.list_collection_names() retorna uma lista de strings, uma por coleção no banco de dados. A verificação com in é um simples teste de pertencimento.

Tratamento de Erros

A maioria das operações de remoção é bem-sucedida sem erros, mas duas situações podem causar falhas:

1. Permissões insuficientes — o usuário conectado não tem o privilégio dropCollection.
2. Erros de rede — a conexão com o MongoDB é perdida durante a operação.

O PyMongo lança pymongo.errors.OperationFailure para erros do lado do servidor (incluindo problemas de permissão) e pymongo.errors.ConnectionFailure para problemas de rede. Capture ambos:

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["mydatabase"]
col = db["mycollection"]

try:
    col.drop()
    print("Collection dropped successfully.")
except pymongo.errors.OperationFailure as e:
    print(f"Server error while dropping collection: {e}")
except pymongo.errors.ConnectionFailure as e:
    print(f"Connection error: {e}")

Exemplo Prático: Teardown Seguro em Testes

Um padrão comum no mundo real é remover uma coleção no final de um teste ou migração para deixar o banco de dados limpo. Este exemplo mostra um helper reutilizável que remove uma coleção somente quando ela existe, registra o resultado e nunca lança uma exceção que faria um teste não relacionado falhar:

import pymongo

def drop_if_exists(db, collection_name: str) -> bool:
    """
    Drop a collection if it exists. Returns True if dropped, False otherwise.
    Never raises on a missing collection.
    """
    if collection_name not in db.list_collection_names():
        print(f"[skip] '{collection_name}' does not exist.")
        return False

    try:
        db.drop_collection(collection_name)
        print(f"[ok]   '{collection_name}' dropped.")
        return True
    except pymongo.errors.OperationFailure as e:
        print(f"[err]  Could not drop '{collection_name}': {e}")
        return False


# --- usage ---
client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["testdb"]

# Seed some data so the collection exists
db["orders"].insert_one({"item": "pen", "qty": 100})

drop_if_exists(db, "orders")    # [ok]   'orders' dropped.
drop_if_exists(db, "orders")    # [skip] 'orders' does not exist.

Remover uma Coleção vs. Excluir Todos os Documentos

Estas são duas operações diferentes com resultados distintos:

Use drop() quando quiser começar completamente do zero — por exemplo, entre execuções de testes ou como parte de uma migração de esquema onde o layout dos índices também será alterado. Use delete_many({}) quando precisar manter os índices e a configuração da coleção intactos. Consulte MongoDB Delete para detalhes sobre delete_many().

Resumo

• Collection.drop() remove a coleção e retorna True/False. Nenhuma exceção é lançada para uma coleção inexistente.
• Database.drop_collection(name) obtém o mesmo resultado e é conveniente quando você só tem o nome da coleção como string.
• Use db.list_collection_names() para verificar a existência antes de remover quando precisar de lógica condicional.
• Capture pymongo.errors.OperationFailure para erros de permissão e pymongo.errors.ConnectionFailure para problemas de rede.
• Remover exclui tanto os documentos quanto os índices. Use delete_many({}) se quiser manter os índices.

Capítulos relacionados:

• MongoDB Create Collection — criando coleções com opções e validadores
• MongoDB Delete — excluindo documentos individuais com delete_one() e delete_many()
• MongoDB Get Started — instalando o PyMongo e conectando ao MongoDB