/ /

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

Un URI de conexión, también conocido como cadena de conexión, especifica cómo la Integración de Laravel se conecta a MongoDB y cómo debe comportarse durante la conexión.

Partes de un URI de conexión

Una cadena de conexión incluye los siguientes elementos:

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 la opción `database` no está especificada en el arreglo de configuración de base de datos.
`?<options>`	opcional. Una string del query que especifica las opciones específicas de la conexión como pares `<name>=<value>`. Consulta 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'],

Nota

Esta opción no acepta hosts que utilizan el formato de conexión DNS lista de nodos iniciales.

database

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

username

Especifica el nombre de usuario de tu base de datos usado como credencial para autenticarte 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 deben pasar a MongoDB para determinar el comportamiento de la conexión. Para obtener más información sobre las opciones de conexión, consulta 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

Puedes especificar la siguiente configuración en la configuración de dsn como parámetros en tu cadena de conexión de MongoDB en lugar de como elementos de arreglo:

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.
Agrega una entrada de conexión para tu conexión de MongoDB en el arreglo connections de tu archivo de configuración config/database.php. Establezca el valor de dsn de la entrada de conexión para hacer 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:

Muestra .env configuración del entorno

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 tu cadena de conexión de Atlas, sigue el paso Crear una cadena de conexión del tutorial de inicio rápido.

Otras formas de conectarse a MongoDB

Las siguientes secciones te muestran cómo conectarte a una única instancia de servidor de MongoDB o a un set de réplicas que no se alojan 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.
Obtén la dirección IP y el puerto en el que está ejecutándose tu servidor MongoDB. Si utilizas la configuración por defecto de una instalación local del servidor de 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 añadir al archivo .env si su aplicación se conecta a un servidor MongoDB ejecutándose en la dirección IP y puerto por defecto:

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 set de réplicas, especifique el nombre de host y el número de puerto de cada nodo, separados por comas, y el nombre del set 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 nodos del conjunto de réplicas cuando se le proporciona la dirección de cualquiera de los nodos.
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

Se requiere que especifiques solo un host para conectarte a un set 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