Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Elija un destino de conexión

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.

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()

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.

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-py

El 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)

Para obtener más información sobre atlas-local-lib-py, consulte el repositorio atlas-local-lib-py.

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)

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")

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 false como el valor del parámetro directConnection.

  • 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)

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.

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)

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.

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.

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, internalo corp.

  • 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",)

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,)

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.

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.

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 out

Esto 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.

Para aprender más sobre cómo crear un objeto MongoClient en PyMongo, consulta la siguiente documentación de API: