/ /

Guía de Conexión

Overview

En esta guía, puedes aprender a conectar tu aplicación Laravel a una instancia o set de réplicas de MongoDB implementación usando 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 a la base de datos de Laravel, que explica cómo configurar la conexión a su 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 string en el formato de conexión estándar (`mongodb://`) o en el formato de conexión SRV (`mongodb+srv://`). Para más información, consulta Formatos de cadenas de conexión.
`username:password`	opcional. Indica el nombre de usuario y la contraseña de tu base de datos para la autenticación utilizando el formato `<username>:<password>`. Omite esta sección si tu 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 especificar el número de puerto sólo es compatible al utilizar el formato de conexión estándar. Si está utilizando el formato de conexión SRV, omite 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 un URI de conexión completo 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. Puede especificar los siguientes detalles de conexión en este archivo:

defaultque especifica la conexión a la base de datos a usar cuando no se especifica
connectionsque contiene información de conexión a la base de datos para acceder a una o más bases de datos desde su aplicación

Puedes usar el siguiente código en el archivo de configuración para establecer la conexión por defecto a una entrada de mongodb correspondiente en el arreglo 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 para la conexión.

dsn

El nombre de la fuente de datos (DSN) que especifica el 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 las opciones concretas que se deben pasar a MongoDB PHP librería y que determinan el comportamiento del driver para esa conexión. Para obtener más información sobre las opciones de driver, consulte Opciones de conexión de driver.

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 por el nombre de la opción

Importante

La integración de Laravel no admite los ajustes de conexión prefix y prefix_indexes.

El siguiente ejemplo muestra cómo se pueden especificar los detalles de conexión de MongoDB en el elemento de arreglo 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 tu MongoDB DSN a tu aplicación Laravel, realiza los siguientes cambios:

Agrega el DSN como una variable de entorno en el archivo de configuración del entorno .env de tu proyecto. Establezca el valor de la variable a su cadena de conexión 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/"

Entrada de conexión de muestra en 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 tu aplicación a una instancia de MongoDB alojada en la misma máquina, debes completar las siguientes tareas:

Descarga, instala y ejecuta el servidor de 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 conexión config/database.php para hacer referencia a la variable de entorno DB_URI como el valor de dsn, 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:

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

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

Para aprender cómo descargar e instalar el servidor de MongoDB, consulta Instalar MongoDB Community Edition en el manual del servidor.

Conectarse a un set de réplicas

Una implementación de conjunto de réplicas de MongoDB es un grupo de instancias conectadas, o nodos, donde los nodos almacenan el mismo conjunto de datos. Esta configuración de instancias proporciona redundancia de datos 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 puedes añadir al archivo .env de tu aplicación Laravel para conectarte a un set 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 MongoDB se ejecuta en esos hosts
myRS como el nombre configurado del set de réplicas
myUser y myPass123 como las 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 set de réplicas, la librería que Laravel Integration utiliza para gestionar 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 nodo apropiado, como instrucciones para realizar escrituras sobre el nodo primario. Para aprender más sobre el primario del set de réplicas, consulta Primario del set de réplicas 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 aprender más sobre cómo configurar un set de réplicas de MongoDB, consulte implementar un set de réplicas en el manual del servidor.

directConnection

Para forzar que las operaciones se ejecuten en un nodo específico en un set de réplicas de MongoDB, especifique la información de conexión para el 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 las cadenas de conexión en formato de conexión de lista de nodos iniciales DNS.
Las operaciones de guardar fallan cuando el host especificado no es el primario.
Cuando el host no es el principal, debes especificar la preferencia de lectura secondary en tus opciones de conexión. Para obtener más información sobre esta limitación, consulte la entrada de preferencia de lectura secundaria en el manual del servidor.

El siguiente ejemplo muestra la cadena de conexión que puedes añadir al archivo .env de tu aplicación Laravel para establecer una conexión directa con un secundario en un set 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 escucha el nodo de MongoDB

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

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

Volver

Tutorial: Compila una aplicación full-pila

Opciones de conexión