/ /

Guía de Conexión

Overview

En esta guía, puede aprender cómo conectar su aplicación Laravel a una instancia de MongoDB o una implementación de conjunto de réplicas mediante Laravel MongoDB.

Esta guía incluye las siguientes secciones:

URI de conexión, que explica los URI de conexión y sus partes constitutivas
Configuración de la conexión de la base de datos de Laravel, que explica cómo configurar su conexión de base de datos MongoDB para su aplicación Laravel.
Ejemplo de conexión, que proporciona ejemplos que muestran cómo conectarse a MongoDB mediante una cadena de conexión Atlas.
Otras formas de conectarse a MongoDB describe formas de conectarse a implementaciones de MongoDB que no están alojadas en Atlas.

URI de conexión

Una URI de conexión, también conocida como cadena de conexión, especifica cómo la integración de Laravel se conecta a MongoDB y cómo comportarse mientras está conectado.

Partes de una URI de conexión

Una cadena de conexión incluye los siguientes componentes:

Componente	Descripción
`mongodb://` or `mongodb+srv://`	Obligatorio. Un prefijo que identifica el URI como una cadena en el formato de conexión estándar `mongodb://`() o en el formato de conexión SRV `mongodb+srv://`(). Para obtener más información, consulte Formatos de cadena de conexión.
`username:password`	Opcional. Especifica el nombre de usuario y la contraseña de la base de datos para la autenticación utilizando el formato `<username>:<password>`. Omita esta sección si su implementación no requiere autenticación.
`host[:port]`	Requerido. El host y el número de puerto opcional donde se ejecuta MongoDB. Si no incluyes el número de puerto, el controlador utiliza el puerto por defecto, `27017`. Tenga en cuenta que solo se puede especificar el número de puerto al usar el formato de conexión estándar. Si usa el formato de conexión SRV, omita el número de puerto.
`/defaultauthdb`	Opcional. La base de datos de autenticación que se debe usar si la cadena de conexión incluye las credenciales de autenticación `username:password@` pero no la opción `authSource`. Si no incluyes este componente, el cliente autentica al usuario contra la base de datos `admin`. También puede ser la base de datos de la aplicación si y solo si no se especifica la opción `database` en la matriz de configuración de base de datos.
`?<options>`	Opcional. Una cadena de consulta que especifica opciones específicas de la conexión como `<name>=<value>` pares. Consulte la guía de opciones de conexión para obtener una descripción completa de estas opciones.

El siguiente ejemplo muestra una URI de conexión completa que especifica el protocolo, las credenciales, el nombre de host y el puerto, y las opciones de conexión:

mongodb://myUser:myPass123@localhost:27017/?w=majority&retryWrites=true

Para obtener más información sobre las cadenas de conexión, consulte Cadenas de conexión en el manual del servidor.

Configuración de la conexión a la base de datos de Laravel

La integración de Laravel te permite configurar tu conexión a la base de datos MongoDB en el archivo de aplicación config/database.php de Laravel. Puedes especificar los siguientes detalles de conexión en este archivo:

default, que especifica la conexión de base de datos que se utilizará cuando no se especifique
connections, que contiene información de conexión de base de datos para acceder a una o más bases de datos desde su aplicación

Puede utilizar el siguiente código en el archivo de configuración para establecer la conexión predeterminada a una entrada mongodb correspondiente en la matriz connections:

'default' => 'mongodb',

Para una conexión de base de datos MongoDB, puede especificar los siguientes detalles:

Configuración

Descripción

driver

Especifica el controlador de base de datos que se utilizará para la conexión.

dsn

El nombre de la fuente de datos (DSN) que especifica la URI de conexión de MongoDB.

host

Specifies the network address and port of one or more MongoDB nodes in a deployment. You can use this setting instead of the dsn setting.

To specify a single host, pass the hostname and port as a string as shown in the following example:

'host' => 'myhost.example.com:27017',

To specify multiple hosts, pass them in an array as shown in the following example::

'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'],

This option does not accept hosts that use the DNS seedlist connection format.

database

Especifica el nombre de la base de datos MongoDB para leer y escribir.

username

Especifica las credenciales de nombre de usuario de su base de datos para autenticarse con MongoDB.

password

Especifica la credencial de contraseña de tu usuario de base de datos para autenticarte con MongoDB.

options

Especifica las opciones de conexión que se pasan a MongoDB y que determinan el comportamiento de la conexión. Para obtener más información sobre las opciones de conexión, consulte Opciones de conexión y autenticación.

driver_options

Especifica opciones específicas para pasar a la biblioteca PHP de MongoDB que determinan el comportamiento del controlador para esa conexión. Para obtener más información sobre las opciones del controlador, consulte Opciones de conexión del controlador.

Nota

Puede especificar las siguientes configuraciones en la configuración dsn como parámetros en su cadena de conexión MongoDB en lugar de como elementos de la matriz:

host
username
password
options y driver_options, que se especifican mediante el nombre de la opción

Importante

La integración de Laravel no admite las configuraciones de conexión prefix y prefix_indexes.

El siguiente ejemplo muestra cómo puede especificar los detalles de su conexión MongoDB en el elemento de la matriz connections:

Ejemplo de configuración/configuración de conexión a base de datos MongoDB en database.php

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb+srv//myUser:myPass123@sample.host/',
        'database' => 'sample_mflix',
        'options' => [
            'w' => 'majority',
        ],
        'driver_options' => [
            'serverApi' => 1,
        ],
    ],
    // ...
],

Las siguientes secciones proporcionan formas comunes de especificar conexiones MongoDB.

Ejemplo de conexión

Esta sección muestra cómo configurar el DSN de su aplicación Laravel utilizando una cadena de conexión de MongoDB Atlas.

Para agregar su DSN MongoDB a su aplicación Laravel, realice los siguientes cambios:

Agregue el DSN como variable de entorno en el archivo de configuración del entorno .env de su proyecto. Establezca el valor de la variable en la cadena de conexión de Atlas.
Agregue una entrada de conexión para su conexión de MongoDB en la matriz connections de su archivo de configuración config/database.php. Establezca el valor dsn de la entrada de conexión para que haga referencia a la variable de entorno que contiene su DSN.

Los siguientes ejemplos muestran cómo especificar "mongodb+srv://myUser:myPass123@mongodb0.example.com/" como la cadena de conexión en los archivos de configuración relevantes:

Ejemplo de configuración del entorno .env

DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/"

Ejemplo de entrada de conexión config/database.php

'connections' => [
    'mongodb' => [
        'dsn' => env('DB_URI'), // uses the value of the DB_URI environment variable
        'driver' => 'mongodb',
        'database' => 'sample_mflix',
        // ...
    ],
  // ...
]

Tip

Para recuperar la cadena de conexión de Atlas, siga el paso Crear una cadena de conexión del tutorial de Inicio rápido.

Otras formas de conectarse a MongoDB

Las siguientes secciones le muestran cómo conectarse a una única instancia de servidor MongoDB o a un conjunto de réplicas no alojado en MongoDB Atlas.

Realizar la conexión a MongoDB Server en la máquina local

Esta sección muestra un ejemplo de cadena de conexión que puedes usar al ejecutar una aplicación de Laravel y un servidor MongoDB desde la misma máquina, como tu entorno de desarrollo local.

Para conectar su aplicación a una instancia de MongoDB alojada en la misma máquina, debe completar las siguientes tareas:

Descargue, instale y ejecute el servidor MongoDB.
Obtenga la dirección IP y el puerto donde se ejecuta su servidor MongoDB. Si utiliza la configuración predeterminada de una instalación local del servidor MongoDB, la dirección IP es 127.0.0.1 y el puerto es 27017.
Configure su config/database.php conexión para hacer referencia a la variable de entorno DB_URI para el valor dsn de, como se muestra en la sección Ejemplo de conexión.

El siguiente ejemplo muestra una cadena de conexión de muestra que puede agregar al archivo .env si su aplicación se conecta a un servidor MongoDB que se ejecuta en la dirección IP y el puerto predeterminados:

Ejemplo de configuración del entorno .env para conectarse a un servidor MongoDB local.

DB_URI="mongodb://127.0.0.1:27017/";

Para saber cómo descargar e instalar el servidor MongoDB, consulte Instalar MongoDB Community Edition en el manual del servidor.

Conectarse a un set de réplicas

Una implementación de un conjunto de réplicas de MongoDB es un grupo de instancias conectadas, o nodos, que almacenan el mismo conjunto de datos. Esta configuración de instancias proporciona redundancia y alta disponibilidad de datos.

Para conectarse a una implementación de conjunto de réplicas, especifique el nombre de host y el número de puerto de cada nodo, separados por comas, y el nombre del conjunto de réplicas como el valor del parámetro replicaSet en la cadena de conexión.

Este ejemplo, que muestra la cadena de conexión que puede agregar al archivo .env de su aplicación Laravel para conectarse a un conjunto de réplicas, utiliza los siguientes valores de muestra:

host1, host2 y host3 como los nombres de host de los nodos de MongoDB
27017 como el puerto en el que se ejecuta MongoDB en esos hosts
myRS como el nombre configurado del set de réplicas
myUser y myPass123 como credenciales de un usuario de base de datos

DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS"

Al conectarse a un conjunto de réplicas, la biblioteca que utiliza la integración de Laravel para administrar las conexiones con MongoDB realiza las siguientes acciones a menos que se especifique lo contrario:

Descubre todos los miembros del conjunto de réplicas cuando se le proporciona la dirección de cualquiera de los miembros.
Envía operaciones al miembro correspondiente, como instrucciones para escribir en el nodo principal. Para obtener más información sobre el conjunto de réplicas principal, consulte "Conjunto de réplicas principal" en el manual del servidor.

Tip

Debe especificar solo un host para conectarse a un conjunto de réplicas. Sin embargo, para garantizar la conectividad cuando el host seleccionado no esté disponible, proporcione la lista completa de hosts.

Para obtener más información sobre cómo configurar un conjunto de réplicas de MongoDB, consulte Implementar un conjunto de réplicas en el manual del servidor.

Conexión directa

Para forzar la ejecución de operaciones en un nodo específico en un conjunto de réplicas de MongoDB, especifique la información de conexión del nodo en la cadena de conexión y el parámetro directConnection con un valor true.

Las conexiones directas incluyen las siguientes limitaciones:

No se pueden utilizar cadenas de conexión del formato de conexión de la lista de semillas DNS.
Las operaciones de escritura fallan cuando el host especificado no es el principal.
Si el host no es el principal, debe especificar la secondary preferencia de lectura en las opciones de conexión. Para obtener más información sobre esta limitación, consulte la sección sobre la preferencia de lectura secundaria en el manual del servidor.

El siguiente ejemplo muestra la cadena de conexión que puede agregar al archivo .env de su aplicación Laravel para establecer una conexión directa con un nodo secundario en un conjunto de réplicas de MongoDB. El ejemplo utiliza los siguientes valores de muestra:

host2 como el nombre de host del nodo secundario
27017 como el puerto en el que el nodo MongoDB escucha

Ejemplo de configuración del entorno .env para habilitar una conexión directa

DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary"

Volver

Ejecute un comando

Opciones de conexión