Elija un destino de conexión

Overview

En esta guía, puedes aprender cómo utilizar una cadena de conexión y MongoDB\Client objeto para conectarse 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:

• URI de tu clúster de Atlas

• Nombre de usuario de la base de datos

• Contraseña del usuario de base de datos

Luego, pasa tu cadena de conexión al constructor de MongoDB\Client.

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 Stable API, consulta Página de Stable API.

El siguiente código muestra cómo usar la librería PHP para conectarse a un clúster Atlas. El código también utiliza la opción serverApi para especificar una versión estable de la API.

<?php
// Replace the placeholder with your Atlas connection string
$uri = '<connection string>';
// Create a MongoDB client with server API options
$client = new MongoDB\Client($uri, [], [
    'serverApi' => new MongoDB\Driver\ServerApi('1'),
]);
// Ping the server to verify that the connection works
$admin = $client->admin;
$command = new MongoDB\Driver\Command(['ping' => 1]);
$result = $admin->command($command)->toArray();
echo json_encode($result), PHP_EOL;
echo 'Pinged your deployment. You successfully connected to MongoDB!\n';

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.

El siguiente código muestra cómo utilizar la librería PHP para conectarse a una implementación local de MongoDB:

<?php
$uri = 'mongodb://localhost:27017';
$uriOptions = ['serverSelectionTimeoutMS' => 10000];
$client = new MongoDB\Client($uri, $uriOptions);

Sets de réplicas

Para conectarse 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.

Si no puedes proporcionar una lista completa de hosts en el set de réplicas, puedes especificar uno o más de los hosts en el set de réplicas e instruir a la librería de PHP para que realice un descubrimiento automático y encuentre los demás. Para indicar al controlador que realice un descubrimiento automático, elige 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 controlador utiliza un URI de conexión de muestra para conectarse al conjunto de réplicas de MongoDB sampleRS, que está funcionando en el puerto 27017 de tres hosts diferentes, incluyendo host1:

<?php
$uri = 'mongodb://host1:27017/?replicaSet=sampleRS';
// Create a MongoDB client
$client = new MongoDB\Client($uri);

<?php
// Replace the placeholders with your actual hostname and port
$uri = 'mongodb://<hostname>:<port>/?directConnection=true';
// Create a MongoDB client
$client = new MongoDB\Client($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, especifica el formato de conexión SRV en la cadena de conexión. Si especificas este formato, la librería PHP vuelve a analizar automáticamente la presencia de nuevos hosts. La implementación puede añadir hosts a su topología sin requerir cambios en 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 obtener más información sobre el formato de conexión SRV, consulta el Formato de conexión SRV entrada en el manual de MongoDB Server.

Errores de selección del servidor

El siguiente código muestra posibles mensajes de error de selección de servidor que tu aplicación podría generar:

No suitable servers found (`serverSelectionTryOnce` set):
  [connection refused calling hello on 'a.example.com:27017']
  [connection refused calling hello on 'b.example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [socket timeout calling hello on 'example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [connection timeout calling hello on 'a.example.com:27017']
  [connection timeout calling hello on 'b.example.com:27017']
  [TLS handshake failed: -9806 calling hello on 'c.example.com:27017']
No suitable servers found: `serverselectiontimeoutms` timed out:
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'a.example.com:27017']
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'b.example.com:27017']

La extensión PHP normalmente representa estos errores como MongoDB\Driver\Exception\ConnectionTimeoutException excepciones. Sin embargo, los mensajes de excepción provienen de libmongoc, que es la librería de sistema subyacente utilizada por la extensión. Dado que estos mensajes pueden adoptar múltiples formas, se recomienda desglosar la estructura del mensaje para poder diagnosticar mejor los errores de la aplicación.

Los mensajes normalmente comienzan con una advertencia de "No se han encontrado servidores adecuados". La siguiente parte del mensaje indica cómo falló la selección del servidor. La extensión evita un bucle de selección de servidor y realiza un solo intento por defecto, de acuerdo con la opción de cadena de conexión serverSelectionTryOnce. Si la extensión está configurada para usar un bucle, un mensaje que incluya la frase "serverSelectionTimeoutMS expired" indica que ha agotado su límite de tiempo.

El último componente del mensaje nos indica por qué falló la selección del servidor e incluye uno o más errores directamente del escáner de topología, que es el servicio responsable de conectar y monitorear cada host. Cualquier host que haya experimentado previamente un error durante la supervisión será incluido en esta lista. Estos mensajes suelen originarse a partir de funciones de socket o TLS de bajo nivel.

La siguiente lista describe los significados posibles de frases comunes en el último componente del mensaje de error:

• "Conexión rechazada": Es posible que el host remoto no esté escuchando en el puerto esperado.

• "Tiempo de espera de conexión": Podría haber un problema de enrutamiento, un error de firewall o un tiempo de espera debido a la latencia.

• "Tiempo de espera del socket": Probablemente estableciste una conexión inicial que se descartó o expiró debido a la latencia.

• "Fallo en el handshake TLS": la verificación TLS u OCSP no tuvo éxito, y es posible que estés utilizando certificados TLS mal configurados.

En caso de fallo de la conexión, puedes utilizar la herramienta connect para obtener más información sobre la solución de problemas. Esta herramienta intenta conectarse a cada host en una cadena de conexión utilizando funciones de socket y luego intenta interactuar con los datos. Si utilizaste Composer para instalar la librería, puedes usar el siguiente comando para iniciar la herramienta connect:

php vendor/mongodb/mongodb/tools/connect.php <connection URI>

Si el servidor al que te estás conectando no acepta conexiones, la salida se parecerá al siguiente código:

Looking up MongoDB at <connection URI>
Found 1 host(s) in the URI. Will attempt to connect to each.
Could not connect to <host>:<port>: Connection refused

Documentación de la API

Para obtener más información sobre cómo usar la clase MongoDB\Client, consulte la siguiente documentación de API:

• MongoDB\Client