Crear una base de datos MongoDB en Python con PyMongo

MongoDB no crea una base de datos hasta que realmente se escribe información en ella. Este comportamiento de "creación diferida" es intencional y es una de las primeras cosas con las que los nuevos usuarios se topan. Este capítulo te guía a través de la conexión a un servidor MongoDB con el driver pymongo de Python, la comprensión de cuándo se crea realmente una base de datos, la verificación de que existe y la limpieza de bases de datos de prueba.

Requisitos previos

Python 3.8 o posterior instalado
Un servidor MongoDB en ejecución (local o remoto). Si aún no has instalado MongoDB, sigue primero el capítulo Primeros pasos con MongoDB.
El driver pymongo instalado:

pip install pymongo

Cómo funciona la creación de bases de datos en MongoDB

A diferencia de las bases de datos relacionales, en MongoDB nunca se ejecuta una instrucción CREATE DATABASE. En cambio:

Se referencia una base de datos por nombre a través del objeto cliente.
MongoDB mantiene esa referencia en memoria, pero aún no crea nada en disco.
La base de datos se crea físicamente la primera vez que se inserta un documento o se crea explícitamente una colección.

Esto significa que client["mydb"] siempre tiene "éxito" — devuelve un objeto Database tanto si mydb existe como si no.

Conexión a MongoDB

Importa MongoClient y abre una conexión. Cuando MongoDB se ejecuta en la misma máquina con la configuración predeterminada (host localhost, puerto 27017), puedes llamar a MongoClient() sin argumentos:

from pymongo import MongoClient

# Connect to the local MongoDB server (localhost:27017)
client = MongoClient()

Para conectarte a un servidor remoto o a un puerto no predeterminado, pasa un URI de conexión:

# Generic URI form
client = MongoClient("mongodb://hostname:port")

# Example: remote host on port 27017
client = MongoClient("mongodb://db.example.com:27017")

# Example: with authentication
client = MongoClient("mongodb://username:[email protected]:27017")

MongoClient utiliza un pool de conexiones internamente — se crea un único cliente por aplicación y se reutiliza en todas las operaciones de base de datos.

Obtener una referencia a la base de datos

Accede a una base de datos mediante el nombre de atributo o la notación de clave de diccionario:

# Both lines do exactly the same thing
db = client.my_database
db = client["my_database"]

Usa el estilo de diccionario (client["name"]) cuando el nombre de la base de datos contenga caracteres que no sean identificadores Python válidos, como guiones.

En este punto la base de datos todavía no existe en el servidor. Imprime la lista de bases de datos del cliente para confirmarlo:

print(client.list_database_names())
# Typical output: ['admin', 'config', 'local']
# 'my_database' is NOT listed yet

Crear la base de datos insertando un documento

La forma más sencilla de materializar la base de datos es insertar un documento. El ejemplo siguiente crea una base de datos llamada bookstore y una colección llamada books:

from pymongo import MongoClient

client = MongoClient()

db = client["bookstore"]
books = db["books"]

# Inserting the first document triggers physical database creation
result = books.insert_one({
    "title": "The Pragmatic Programmer",
    "author": "David Thomas",
    "year": 1999
})

print("Inserted document id:", result.inserted_id)
print("Databases now:", client.list_database_names())

Después de ejecutar este script deberías ver una salida similar a:

Inserted document id: 64a1e3b2c9f1234567890abc
Databases now: ['admin', 'bookstore', 'config', 'local']

bookstore aparece ahora en la lista porque existe al menos un documento en ella.

Verificar si una base de datos existe

Dado que una base de datos referenciada puede existir o no, la comprobación requiere inspeccionar la lista devuelta por list_database_names():

from pymongo import MongoClient

client = MongoClient()

def database_exists(client, name):
    return name in client.list_database_names()

print(database_exists(client, "bookstore"))   # True (if created above)
print(database_exists(client, "no_such_db"))  # False

Eliminar una base de datos de prueba

Cuando quieras eliminar una base de datos (por ejemplo, después de realizar pruebas), llama a drop_database() en el cliente:

from pymongo import MongoClient

client = MongoClient()
client.drop_database("bookstore")

print("bookstore" in client.list_database_names())  # False

Esto elimina permanentemente la base de datos y todas sus colecciones y documentos. No hay ningún mensaje de confirmación.

Errores comunes

Los errores tipográficos son silenciosos

Debido a que MongoDB crea bases de datos bajo demanda, un error tipográfico en el nombre de la base de datos crea silenciosamente una segunda base de datos en lugar de lanzar un error:

# Intended: 'bookstore'
# Actual:   'bookstoree'  — a new empty database that never gets data
db = client["bookstoree"]

Define siempre los nombres de las bases de datos como constantes al inicio de tu módulo para evitar esto:

DB_NAME = "bookstore"
db = client[DB_NAME]

Las bases de datos vacías son invisibles

Si referencias una base de datos pero nunca insertas datos, list_database_names() no la incluirá. Esto puede hacer que la depuración sea confusa — la base de datos "existe" como objeto Python pero no en disco.

Los errores de conexión aparecen tarde

MongoClient() tiene éxito incluso cuando MongoDB no está en ejecución. El error de conexión solo aparece cuando realizas una petición real (insertar, buscar, etc.). Envuelve las operaciones reales en un bloque try/except:

from pymongo import MongoClient
from pymongo.errors import ConnectionFailure

client = MongoClient(serverSelectionTimeoutMS=3000)

try:
    # This forces a real network round-trip
    client.admin.command("ping")
    print("Connected to MongoDB")
except ConnectionFailure as e:
    print("Could not connect:", e)

Ejemplo completo funcional

El siguiente script autocontenido demuestra todos los pasos tratados en este capítulo:

from pymongo import MongoClient
from pymongo.errors import ConnectionFailure

DB_NAME = "demo_bookstore"

def main():
    client = MongoClient(serverSelectionTimeoutMS=3000)

    # Verify the connection
    try:
        client.admin.command("ping")
    except ConnectionFailure as e:
        print("MongoDB is not reachable:", e)
        return

    # Before any insert, the database does not appear in the list
    print("Before insert:", DB_NAME in client.list_database_names())

    db = client[DB_NAME]
    books = db["books"]

    # Insert a document — this creates the database
    books.insert_one({"title": "Clean Code", "author": "Robert C. Martin"})

    # Now the database is visible
    print("After insert: ", DB_NAME in client.list_database_names())
    print("Databases:    ", client.list_database_names())

    # Clean up
    client.drop_database(DB_NAME)
    print("After drop:   ", DB_NAME in client.list_database_names())

if __name__ == "__main__":
    main()

Salida esperada (el id del documento será diferente):

Before insert: False
After insert:  True
Databases:     ['admin', 'config', 'demo_bookstore', 'local']
After drop:    False

Próximos pasos

Crear una colección en MongoDB — aprende a crear colecciones y a entender la creación diferida a nivel de colección.
Insertar en MongoDB — inserta uno o varios documentos en una colección.
Buscar en MongoDB — consulta documentos de una colección.