连接指南

在此页面上

Overview

连接 URI
一个连接 URI 的组成部分
Laravel 数据库连接配置
连接示例
连接 MongoDB 的其他方式
连接到本地计算机上的 MongoDB Server
连接到副本集

Overview

在本指南中，您可以了解如何使用 Laravel MongoDB 将 Laravel 应用程序连接到 MongoDB 实例或副本集部署。

本指南包括以下部分：

连接 URI ，解释了连接 URI 及其组成部分
Laravel 数据库连接配置，解释了如何为 Laravel 应用设置MongoDB database连接。
连接示例，其中举例说明了如何使用MongoDB Atlas连接连接到string 。
连接到 MongoDB 的其他方式描述了连接到非 Atlas 托管的 MongoDB 部署的方法。

连接 URI

连接 URI （也称为连接string ）指定 Laravel 集成如何连接到MongoDB以及连接时的行为方式。

一个连接 URI 的组成部分

下图解释了示例连接 URI 的各个部分：

在此连接 URI 中， mongodb+srv是协议，它使用DNS 种子列表连接格式，提高部署的灵活性，并且能够轮流更改服务器，而无需重新配置客户端。

如果托管MongoDB部署的计算机不支持此功能，请改用标准连接string格式的协议。

如果您使用基于密码的身份验证，则协议之后的连接string部分将包含您的用户名和密码。将user占位符替换为用户名，并将pass占位符替换为密码。如果使用不需要用户名和密码的身份验证机制，请忽略连接 URI 的这一部分。

凭证之后的连接string部分指定MongoDB实例的主机名或IP地址和端口。前面的示例使用sample.host作为主机名， 27017作为端口。替换这些值以指向您的 MongoDB 实例。

连接string的最后一部分指定连接和身份验证选项。在此示例中，我们设置了以下连接选项和值：

maxPoolSize=20
w=majority

要学习；了解有关连接选项的更多信息，请参阅连接选项。

Laravel 数据库连接配置

Laravel 集成允许您在config/database.php Laravel应用程序文件中配置MongoDB 数据库连接。您可以在此文件中指定以下连接详细信息：

default，指定在以下情况下要使用的数据库连接：未指定
connections，其中包含用于从应用程序访问一个或多个数据库的数据库连接信息

您可以使用配置文件中的以下代码将默认连接设置为connections数组中相应的mongodb条目：

'default' => 'mongodb',

对于MongoDB database连接，您可以指定以下详细信息：

设置

说明

driver

指定用于连接的数据库驱动程序。

dsn

指定 MongoDB 连接 URI 的数据源名称 (DSN)。

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'],

注意

此选项不接受使用 DNS 种子列表连接格式的主机。

database

指定要读取和写入的MongoDB database的名称。

username

指定数据库用户的用户名凭证，以便与 MongoDB 进行身份验证。

password

指定数据库用户的密码档案，以便与 MongoDB 进行身份验证。

options

指定要传递给 MongoDB 以确定连接行为的连接选项。要了解有关连接选项的更多信息，请参阅连接和身份验证选项。

driver_options

指定特定于传递给 MongoDB PHP 库的选项，该库确定该连接的驱动程序行为。要了解有关驱动程序选项的更多信息，请参阅驱动程序连接选项。

注意

您可以将 dsn 配置中的以下设置指定为MongoDB连接string中的参数，而不是数组项：

host
username
password
options 和driver_options ，由选项名称指定

以下示例显示如何在connections数组项中指定 MongoDB 连接详细信息：

示例 config/database.php MongoDB 连接配置

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

以下部分提供了指定 MongoDB 连接的常用方法。

连接示例

本部分介绍如何使用MongoDB Atlas连接string配置 Laravel 应用程序的 DSN。

要将 MongoDB DSN 添加到 Laravel 应用程序，请进行以下更改：

将 DSN 作为环境变量添加到项目的.env环境配置文件中。将变量值设置为Atlas连接string 。
在config/database.php配置文件的connections数组中为 MongoDB 连接添加一个连接条目。将连接条目的dsn值设置为引用包含 DSN 的环境变量。

以下示例展示如何在相关配置文件中将 "mongodb+srv://myUser:myPass123@mongodb0.example.com/" 指定为连接string ：

示例 .env 环境配置

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

示例 config/database.php 连接条目

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

提示

要检索Atlas连接string ，请按照快速入门教程的创建连接string步骤进行操作。

连接 MongoDB 的其他方式

以下部分向您展示如何连接到单个 MongoDB Server 实例或未托管在 MongoDB Atlas 上的副本集。

连接到本地计算机上的 MongoDB Server

本部分展示了从同一台计算机（例如本地开发环境）运行string Laravel 应用程序和MongoDB 服务器时可以使用的示例连接。

要将应用程序连接到同一计算机上托管的 MongoDB 实例，您必须完成以下任务：

下载、安装并运行 MongoDB 服务器。
获取运行 MongoDB Server 的 IP 地址和端口。如果使用本地安装的 MongoDB 服务器的默认设置，则 IP 地址为127.0.0.1 ，端口为27017 。
设置config/database.php连接以引用环境变量DB_URI作为dsn的值，如连接示例部分所示。

以下示例显示了一个示例连接string .env，如果您的应用程序连接到在默认MongoDB IP地址和端口上运行的 Server，则可以将其添加到文件中：

示例 .env 环境配置以连接到本地 MongoDB 服务器。

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

要了解如何下载和安装MongoDB Server，请参阅 MongoDB Community EditionMongoDB Server手册中的安装。

连接到副本集

MongoDB 副本集部署是一组连接的实例或节点，其中的节点存储相同的数据集。这种实例配置提供了数据冗余和高数据可用性。

要连接到副本集部署，请指定每个节点的主机名和端口号（以逗号分隔），并将副本集名称指定为连接string中 replicaSet 参数的值。

此示例显示了可以添加到 Laravel 应用程序的 .env 文件以连接到副本集的连接string ，该示例使用以下示例值：

host1、 host2和host3作为 MongoDB 节点的主机名
27017 作为 MongoDB 在这些主机上运行的端口
myRS 作为副本集的配置名称
myUser 和myPass123作为数据库用户的档案

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

连接到副本集时，除非另有说明，否则 Laravel 集成用于管理与MongoDB的连接的库会执行以下操作：

在给定任一节点的地址时发现所有副本集节点。
向相应成员发送操作，例如针对主节点进行写入的指令。要了解有关副本集主节点的更多信息，请参阅 MongoDB Server手册中的副本集主节点。

提示

您只需指定一台主机即可连接到副本集。但是，为了在所选主机不可用时确保连接，请提供完整的主机列表。

要了解有关设置MongoDB 副本集的更多信息，请参阅 MongoDB Server手册中的部署副本集。

DirectConnection

要强制操作在MongoDB副本集中的特定节点上运行，请在连接string和具有 true 值的 directConnection 参数中指定该节点的连接信息。

直接连接有以下限制：

无法使用 DNS 种子列表连接格式连接字符串。
当指定主机不是主节点时，写入操作会失败。
当主机不是主节点时，必须在连接选项中指定secondary读取偏好。要了解有关此限制的更多信息，请参阅 MongoDB Server手册中的从节点读取偏好条目。

以下示例显示了可以添加到 Laravel 应用程序的 .env 文件中的连接string ，以建立与MongoDB副本集中从节点的直接连接。该示例使用以下样本值：

host2 作为从节点的主机名
27017 作为 MongoDB 节点侦听的端口

示例 .env 环境配置以启用直接连接

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

后退

连接

来年

连接选项