Overview
En esta guía, puedes aprender a usar una cadena de conexión y el objeto MongoClient para conectarte a diferentes tipos de implementaciones de MongoDB.
Atlas
Para conectarte a una implementación de MongoDB en Atlas, incluye los siguientes elementos en tu cadena de conexión:
URL de tu clúster de Atlas
Nombre de usuario de MongoDB
Contraseña de MongoDB
Luego, pasa tu cadena de conexión al constructor de MongoClient.
Tip
Siga la guía de conexión del driver Atlas para recuperar su cadena de conexión.
Cuando se conecte a Atlas, se recomienda utilizar la opción de cliente de Stable API para evitar cambios disruptivos al actualizar a una nueva versión de MongoDB Server en Atlas. Para obtener más información sobre la funcionalidad de API estable, consulte la página de API estable.
El siguiente código muestra cómo utilizar PyMongo para conectarse a un clúster de Atlas. El código también utiliza la opción server_api para especificar una Stable API. Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:
from pymongo import MongoClientfrom pymongo.server_api import ServerApi
# Replace the placeholder with your Atlas connection stringuri = "<connection string>"
# Create a MongoClient with a MongoClientOptions object to set the Stable API versionclient = MongoClient(uri, server_api=ServerApi( version='1', strict=True, deprecation_errors=True))
try: # Connect the client to the server (optional starting in v4.7) client.connect()
# Send a ping to confirm a successful connection client.admin.command({'ping': 1}) print("Pinged your deployment. You successfully connected to MongoDB!")
finally: # Ensures that the client will close when you finish/error client.close()import asynciofrom pymongo import AsyncMongoClientfrom pymongo.server_api import ServerApi
async def main(): # Replace the placeholder with your Atlas connection string uri = "<connection string>"
# Create a MongoClient with a MongoClientOptions object to set the Stable API version client = AsyncMongoClient(uri, server_api=ServerApi( version='1', strict=True, deprecation_errors=True))
try: # Send a ping to confirm a successful connection await client.admin.command({'ping': 1}) print("Pinged your deployment. You successfully connected to MongoDB!")
finally: # Ensures that the client will close when you finish/error await client.close()
asyncio.run(main())Implementaciones locales
Para conectarse a una implementación local de MongoDB, use localhost como el nombre de host. Por defecto, el proceso mongod se ejecuta en el puerto 27017, aunque puedes personalizarlo para tu implementación.
Librería de Python para implementaciones locales de Atlas
Para las implementaciones locales de Atlas, puede utilizar la librería atlas-local-lib-py para crear, gestionar y conectarse mediante programación a implementaciones locales a través de Docker. Este enfoque simplifica la gestión de la implementación y recupera automáticamente las cadenas de conexión.
Para instalar la librería, ejecute el siguiente comando:
pip install atlas-local-lib-pyEl siguiente código muestra cómo usar atlas-local-lib-py con PyMongo para crear o reutilizar una implementación local de Atlas y conectarse a ella. Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:
from pymongo import MongoClientfrom atlas_local import LocalDeployment
# Create or reuse a local Atlas deploymentdeployment = LocalDeployment.get_or_create( name="my-local-deployment")
# Get the connection string and connecturi = deployment.connection_string()client = MongoClient(uri)from pymongo import AsyncMongoClientfrom atlas_local import LocalDeployment
# Create or reuse a local Atlas deploymentdeployment = LocalDeployment.get_or_create( name="my-local-deployment")
# Get the connection string and connecturi = deployment.connection_string()client = AsyncMongoClient(uri)Para obtener más información sobre atlas-local-lib-py, consulte el repositorio atlas-local-lib-py.
Conexión manual a la implementación local
Alternativamente, puede conectarse manualmente a una implementación local de MongoDB especificando la cadena de conexión directamente.
El siguiente código muestra cómo usar PyMongo para conectarse a una implementación local de MongoDB que se ejecuta en el puerto por defecto. Seleccione la pestaña Synchronous o Asynchronous para ver el código correspondiente:
from pymongo import MongoClient
uri = "mongodb://localhost:27017/"client = MongoClient(uri)from pymongo import AsyncMongoClient
uri = "mongodb://localhost:27017/"client = AsyncMongoClient(uri)Sets de réplicas
Para conectar a un set de réplicas, especifique los nombres de host (o direcciones IP) y los números de puerto de los miembros del set de réplicas en su cadena de conexión.
El siguiente código muestra cómo usar PyMongo para conectarse a un set de réplicas que contiene tres hosts. Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:
from pymongo import MongoClient
client = MongoClient("mongodb://host1:27017,host2:27017,host3:27017")from pymongo import AsyncMongoClient
client = AsyncMongoClient("mongodb://host1:27017,host2:27017,host3:27017")Si no puedes proporcionar una lista completa de hosts en el set de réplicas, puedes especificar uno o varios de los hosts en el set de réplicas y ordenar a PyMongo que realice el descubrimiento automático para encontrar los otros. Para indicar al controlador que realice el descubrimiento automático, realice una de las siguientes acciones:
Especifique el nombre del set de réplicas como el valor del parámetro
replicaSet.Especifique
falsecomo el valor del parámetrodirectConnection.Especifica más de un host en el conjunto de réplicas.
En el siguiente ejemplo, el driver utiliza un URI de conexión de muestra para conectarse al set de réplicas de MongoDB sampleRS, que se ejecuta en el puerto 27017 de tres hosts diferentes, incluido host1. Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:
from pymongo import MongoClient
uri = "mongodb://host1:27017/?replicaSet=sampleRS"client = MongoClient(uri)from pymongo import AsyncMongoClient
uri = "mongodb://host1:27017/?replicaSet=sampleRS"client = AsyncMongoClient(uri)Nota
Set de réplicas en Docker
Cuando un set de réplicas se ejecuta en Docker, se podría exponer solo un punto final de MongoDB. En este caso, el set de réplicas no se puede detectar. Si se especifica directConnection=false en la URI de conexión, o se deja esta opción sin configurar, puedes evitar que tu aplicación se conecte a ella.
En un entorno de prueba o desarrollo, se puede conectar al set de réplicas especificando directConnection=true. En un entorno de producción, se recomienda configurar el clúster para que cada instancia de MongoDB sea accesible fuera de la red virtual de Docker.
PyMongo equilibra uniformemente las operaciones entre las implementaciones que se pueden alcanzar dentro del valor localThresholdMS del cliente. Para obtener más información sobre cómo PyMongo distribuye las operaciones entre varias implementaciones de MongoDB, consulta la guía Personalizar la selección de servidores.
Nota
El constructor MongoClient es no bloqueante. Al conectarse a un set de réplicas, el constructor devuelve el control inmediatamente mientras el cliente utiliza hilos en segundo plano para conectarse al set de réplicas.
Si construye un MongoClient e imprime inmediatamente la representación de cadena de su atributo nodes, la lista podría estar vacía mientras el cliente se conecta a los miembros del set de réplicas.
Inicialización
Para inicializar un set de réplicas, debe conectarse directamente a un único nodo. Para ello, establece la opción de conexión directConnection en True. Para ello, puede pasar un argumento al constructor MongoClient o a través de un parámetro en su cadena de conexión.
from pymongo import MongoClient
client = MongoClient("mongodb://<hostname>:<port>", directConnection=True)from pymongo import MongoClient
uri = ("mongodb://<hostname>:<port>/?" "directConnection=true")client = MongoClient(uri)from pymongo import AsyncMongoClient
client = AsyncMongoClient("mongodb://<hostname>:<port>", directConnection=True)from pymongo import AsyncMongoClient
uri = ("mongodb://<hostname>:<port>/?" "directConnection=true")client = AsyncMongoClient(uri)Detección de servicios DNS
Para utilizar el descubrimiento de servicios DNS para buscar el registro DNS SRV del servicio al que te estás conectando, deber especificar el formato de conexión SRV en tu cadena de conexión. Además, si habilitas el formato de conexión SRV, PyMongo vuelve a buscar automáticamente nuevos hosts sin necesidad de cambiar la configuración del cliente.
El siguiente código muestra una cadena de conexión que utiliza el formato de conexión SRV:
uri = "mongodb+srv://<hostname>/"Para aprender más sobre el formato de conexión SRV, consulta la entrada Formato de conexión SRV en el manual de MongoDB Server.
Validación de dominio SRV
Una cadena de conexión mongodb+srv:// contiene un único nombre de host, llamado nombre de host semilla. PyMongo consulta un registro DNS SRV para ese nombre de host para descubrir los hosts en tu despliegue. Por defecto, PyMongo acepta un host devuelto solo si comparte el mismo dominio principal que el nombre de host semilla.
Algunas implementaciones devuelven hosts que la comprobación predeterminada rechaza. Para conectarse a estas implementaciones, sustituya la comprobación predeterminada configurando la opción srvAllowedHostsSuffix o srv_host_validator .
Configura solo una de estas opciones. Si configuras ambas opciones, PyMongo eleva una ConfigurationError. Ambas opciones son válidas solo con mongodb+srv:// cadenas de conexión.
Advertencia
Modificar la validación predeterminada del nombre de dominio SRV puede crear vulnerabilidades. Define la regla más estrecha que acepte únicamente los hosts en tu despliegue.
srvAllowedHostsSuffix
Cuando configuras la opción srvAllowedHostsSuffix , PyMongo acepta un host si su nombre termina con el sufijo especificado. Usa esta opción cuando un único sufijo cubra todos los hosts de tu despliegue. Puedes configurar esta opción en el constructor MongoClient o AsyncMongoClient , o como opción de URI.
PyMongo valida el sufijo de la siguiente manera:
El sufijo debe contener al menos dos etiquetas separadas por puntos. Si el sufijo contiene una sola etiqueta, debe reservarse para uso privado o especial, como
localhost,test,internalocorp.El sufijo no debe ser un sufijo público, tal como se indica en la Lista de Sufijos Públicos.
Los siguientes ejemplos se conectan a una implementación cuyo registro SRV devuelve hosts en el dominio internal.example.com . Seleccione la pestaña MongoClient, MongoClient (Asynchronous)o Connection String para ver el código correspondiente:
client = pymongo.MongoClient( "mongodb+srv://cluster.test.internal.example.com/", srvAllowedHostsSuffix=".internal.example.com",)client = pymongo.AsyncMongoClient( "mongodb+srv://cluster.test.internal.example.com/", srvAllowedHostsSuffix=".internal.example.com",)uri = ("mongodb+srv://cluster.test.internal.example.com/" "?srvAllowedHostsSuffix=.internal.example.com")client = pymongo.MongoClient(uri)srv_host_validator
Cuando configuras la opción srv_host_validator , PyMongo acepta un host si la callback especificada devuelve True para ese host. Utiliza esta opción cuando los hosts en tu implementación no puedan describirse con un único sufijo, como cuando abarcan varios dominios.
Solo puedes configurar esta opción en el constructor MongoClient o AsyncMongoClient .
Los siguientes ejemplos se conectan a una implementación cuyo registro SRV devuelve hosts en los dominios a.example.com y b.example.com . Seleccione la pestaña Synchronous o Asynchronous para ver el código correspondiente:
def validator(host: str) -> bool: return host.endswith((".a.example.com", ".b.example.com"))
client = pymongo.MongoClient( "mongodb+srv://cluster.example.com/", srv_host_validator=validator,)def validator(host: str) -> bool: return host.endswith((".a.example.com", ".b.example.com"))
client = pymongo.AsyncMongoClient( "mongodb+srv://cluster.example.com/", srv_host_validator=validator,)Solución de problemas
El servidor informa la versión del protocolo X, PyMongo requiere Y
Si intentas conectar con MongoDB Server v3.6 o anterior, PyMongo podría mostrar el siguiente error:
pymongo.errors.ConfigurationError: Server at localhost:27017 reports wire version 6, but this version of PyMongo requires at least 7 (MongoDB 4.0).Esto ocurre cuando la versión del controlador es demasiado nueva para el servidor al que se está conectando. Para resolver este problema, puede realizar una de las siguientes acciones:
Actualiza tu implementación de MongoDB a la v4.0 o posterior.
Haz el downgrade a PyMongo 4.10 o una versión anterior, que admite MongoDB Server v3.6 y posteriores.
Haz downgrade a PyMongo v3.x, que es compatible con MongoDB Server v2.6 y posteriores.
Reconexión automática
Una excepción AutoReconnect indica que ha ocurrido un failover. Esto significa que PyMongo ha perdido su conexión con el miembro principal original del set de réplicas, y que su última operación podría haber fallado.
Cuando ocurre este error, PyMongo intenta automáticamente encontrar el nuevo nodo primario para las operaciones posteriores. Para gestionar el error, tu aplicación debe realizar una de las siguientes acciones:
Reintentar la operación que podría haber fallado
Siga ejecutando, con la comprensión de que la operación podría haber fallado
Importante
PyMongo arroja un error AutoReconnect en todas las operaciones hasta que el set de réplicas elige un nuevo miembro primario.
Tiempo de espera agotado al acceder a MongoDB desde PyMongo con tunelización
Si intentas conectar a un set de réplicas de MongoDB a través de un túnel SSH, recibirás el siguiente error:
File "/Library/Python/2.7/site-packages/pymongo/collection.py", line 1560, in count return self._count(cmd, collation, session) File "/Library/Python/2.7/site-packages/pymongo/collection.py", line 1504, in _count with self._socket_for_reads() as (connection, slave_ok): File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/contextlib.py", line 17, in __enter__ return self.gen.next() File "/Library/Python/2.7/site-packages/pymongo/mongo_client.py", line 982, in _socket_for_reads server = topology.select_server(read_preference) File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 224, in select_server address)) File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 183, in select_servers selector, server_timeout, address) File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 199, in _select_servers_loop self._error_message(selector))pymongo.errors.ServerSelectionTimeoutError: localhost:27017: timed outEsto ocurre porque PyMongo descubre los miembros del set de réplicas utilizando la respuesta del comando isMaster, que contiene las direcciones y los puertos de los otros miembros del set de réplicas. Sin embargo, no puedes acceder a estas direcciones y puertos a través del túnel SSH.
En su lugar, puedes conectarte directamente a un solo nodo de MongoDB utilizando la opción directConnection=True con tunelización SSH.
Documentación de la API
Para aprender más sobre cómo crear un objeto MongoClient en PyMongo, consulta la siguiente documentación de API: