laravel-mongodb 连接配置完全指南:从 `config/database.php` 到底层连接池真相

原创2026-10-14 21:11:031,447 阅读
文章标签:后端数据库

laravel-mongodb 连接配置完全指南:从 config/database.php 到底层连接池真相

mongodb/laravel-mongodb 是 Laravel 官方的 MongoDB 驱动,它把 mongodb 注册为 Laravel 数据库管理器中的一个连接驱动,让你的 Eloquent 模型与查询构建器直接读写 MongoDB。本文聚焦"连接"这一层:如何配置 config/database.php 与 .env、如何通过 DB Facade 拿到底层 MongoDB\Client 与 MongoDB\Database 对象、如何设置超时与 TLS,以及 maxPoolSize 为什么在这里不生效。读完你将能独立完成本地开发、Atlas 生产环境的连接配置,并准确排查连接类故障。

环境前提:ext-mongodb 扩展与包安装

配置连接前,请确认 PHP 已安装 ext-mongodb 扩展(本包在 composer.json 中要求 ext-mongodb: ^1.21|^2,PHP 要求 ^8.2)。扩展装好后,通过 Composer 引入包:

composer require mongodb/laravel-mongodb

包通过 composer.json 中的 extra.laravel.providers 声明了 MongoDB\Laravel\MongoDBServiceProvider 与 MongoDB\Laravel\MongoDBBusServiceProvider,因此默认会被 Laravel 包自动发现机制(auto-discovery)自动注册,无需手动操作。

第一步:在 config/database.php 中声明 mongodb 连接

打开 config/database.php,在 connections 数组中添加一个 mongodb 连接。这是原文档给出的标准模板:

<?php

return [
    'default' => env('DB_CONNECTION', 'mongodb'),

    'connections' => [
        'mongodb' => [
            'driver'   => 'mongodb',
            'dsn'      => env('MONGODB_URI', 'mongodb://localhost:27017'),
            'database' => env('MONGODB_DATABASE', 'laravel'),
            'options'  => [
                'appName' => env('APP_NAME', 'laravel'),
            ],
        ],

        'mysql' => [
            'driver' => 'mysql',
            // ...
        ],
    ],
];

结合 src/Connection.php 的构造函数(L67-L97)可以看到,Connection 的初始化流程是:

  1. getDsn($config) 组装连接字符串;
  2. 取 $config['options'] ?? [] 直接透传给 MongoDB 构造器(appName 等所有 URI 之外的驱动选项都在这里);
  3. getDefaultDatabaseName($dsn, $config) 解析数据库名;
  4. createConnection() 创建 MongoDB\Client;
  5. $this->connection->getDatabase($this->database) 选定数据库。

几个关键配置项说明:

配置键 作用 默认值
driver 必须是 mongodb,对应服务提供者注册的驱动名 —
dsn 连接字符串(推荐方式) mongodb://localhost:27017
database 默认数据库名 laravel
options 透传给 MongoDB\Client 的构造选项,如 appName、connectTimeoutMS、serverSelectionTimeoutMS []
host / port 免 DSN 的备选写法,支持多主机与 IPv6(见下文) —
username / password 当 credentials 未写入 options 时自动补入(见 createConnection,L268-L275) —
prefix 集合名前缀,见 getCollection()(L131-L134) ''
rename_embedded_id_field 是否将内嵌文档的 id 字段改名为 _id,见构造函数 L96 true

如果既没有 dsn 也没有 host,构造会直接抛出 InvalidArgumentException('MongoDB connection configuration requires "dsn" or "host" key.')(getDsn,L430-L441),这同样由 tests/ConnectionTest.php 中的测试用例验证。

数据库名的两种解析方式

如果 config<a href="https://link.gitcode.com/i/625a62af1ed873c4794e7bf0ace3cda5" target="_blank">'database'] 为空,包会尝试从 DSN 中自动提取数据库名(getDefaultDatabaseName,L238-L249):用正则 ^mongodb(?:[+]srv)?:\/\/.+?\/([^?&]+) 抓取第一个路径段;抓不到就抛出 Database is not properly configured.。例如 mongodb://some-host:12345/tests 会自动得到数据库 tests——[tests/ConnectionTest.php 与 L194-L198(含 TLS 查询参数)都验证了这条路径。若你希望连接后查询参数里同时携带 ?tls=true&tlsCAFile=/path/to/ca.pem&retryWrites=false,同样支持。

第二步:在 .env 中配置环境变量

对应地,.env 中写入(原文档示例):

DB_CONNECTION=mongodb
MONGODB_URI="mongodb+srv://user:pass@cluster0.mongodb.net/?retryWrites=true&w=majority"
MONGODB_DATABASE=laravel

需要强调一个实践要点(来自原文档):池大小、超时与 TLS 全部放进 URI。也就是说,这类参数不要在 options 与 URI 两处各写一份,而是统一以 URI 查询参数的形式给出;连接 Atlas 时使用 mongodb+srv:// 前缀(对应 DNS seed list 与 Atlas 推荐的 TLS 加密)。DB_CONNECTION 指向 database.php 里的 default,决定 Laravel 默认使用哪个连接。

第三步:Service Provider 注册(包自动发现与手动注册)

包默认通过 Laravel 包发现机制自动注册 MongoDBServiceProvider。如果你的应用关闭了包发现(package-discovery),就需要手动把服务提供者加入 bootstrap/providers.php(Laravel 11+ 的位置;旧版为 config/app.php 的 providers 数组):

return [
    MongoDB\Laravel\MongoDBServiceProvider::class,
];

这个提供者做了几件关键的事(见 src/MongoDBServiceProvider.php):

  • 在 db 容器解析时调用 $db->extend('mongodb', ...),把配置数组包装成 new Connection($config),这就是 driver => 'mongodb' 得以生效的机制;
  • 注册 MongoDB 的 Session 处理器(session.connection 默认取 mongodb 连接);
  • 注册 MongoDB 的 Cache / Lock 驱动;
  • 向 Queue 管理器注册 mongodb 连接器(MongoConnector);
  • 注册 GridFS 文件系统适配器与 Laravel Scout 的 mongodb 搜索引擎。

换言之,只要连接配置正确,队列、缓存、会话、全文搜索等多个模块都能复用同一条 MongoDB 连接。若你的某个连接启用了 Queryable Encryption(driver_options.autoEncryption),boot() 阶段还会自动注册对应的加密管理命令(L47-L64)。

第四步:在代码中使用连接

配置完成后,就可以通过 Illuminate\Support\Facades\DB 使用这条连接了(原文档核心代码):

use Illuminate\Support\Facades\DB;

// 通过查询构建器写日志集合
DB::connection('mongodb')->table('logs')->insert(['msg' => 'hi']);

// 拿到底层 MongoDB\Database 对象(MongoDB\Driver 库的 Database)
$db     = DB::connection('mongodb')->getDatabase();   // MongoDB\Database
// 拿到底层 MongoDB\Client 对象
$client = DB::connection('mongodb')->getClient();     // MongoDB\Client
// 已废弃(5.2 起): getMongoDB() → getDatabase(), getMongoClient() → getClient()

// 直接获取 MongoDB\Collection(注意集合名会叠加 prefix)
$collection = DB::connection('mongodb')->getCollection('logs');
// 注意:->collection() 这个方法并不存在;需要查询构建器时请用 ->table()

几个 API 的源码依据:

  • getDatabase(?string $name = null)(src/Connection.php):不传参返回默认数据库的 Database 实例;传入其他库名则返回该库的实例。
  • getClient()(L190-L193):返回 MongoDB\Client,可用于调用 listDatabases() 等原生驱动方法。
  • getCollection($name)(L131-L134):等价于 $db->getCollection($this->tablePrefix . $name),会应用 prefix 配置。
  • table($table, $as = null)(L117-L122):返回本包自定义的 MongoDB\Laravel\Query\Builder,$as 参数被忽略(MongoDB 不支持表别名)。
  • 废弃方法 getMongoDB() / getMongoClient()(L150-L155、L180-L185)会触发 E_USER_DEPRECATED 提示,请迁移到 getDatabase() / getClient()。
  • 其他未显式定义的方法会通过 __call(L501-L504)动态代理到 Database 对象上。

连接对象本身还继承了 Laravel Connection 的全部能力:DB::connection('mongodb')->getDriverName() 返回 mongodb、getDriverTitle() 返回 MongoDB(L444-L454)。tests/ConnectionTest.php 的 testConnection(L26-L33)断言了这一点。

集合名与 ->collection() 的常见误区

原文档特别强调:不存在 ->collection() 方法。想用原生驱动 API 时用 getCollection('logs'),想走 Laravel 查询构建器时用 table('logs')。这两者返回的对象完全不同(MongoDB\Collection vs MongoDB\Laravel\Query\Builder),混用会踩坑。tests/ConnectionTest.php::testCollection(L266-L273)与 testPrefix(L275-L287)分别验证了两种返回类型以及 prefix_ 前缀对两种入口都生效。

连接的生命周期管理:purge、disconnect 与 ping

Laravel 的数据库连接管理器对 mongodb 同样适用:

  • 连接复用:同一请求内多次 DB::connection('mongodb') 返回同一个 Connection 实例;调用 DB::purge('mongodb') 后才会重建(见 tests/ConnectionTest.php 的 testReconnect)。
  • 主动断开:$connection->disconnect()(src/Connection.php)会先关闭查询日志,再把内部 $connection 置空;此时 getClient() 返回 null,DB::purge() 后可重新创建(testDisconnectAndCreateNewConnection,L47-L61)。
  • 连通性检测:ping()(L368-L371)用 ReadPreference::PRIMARY_PREFERRED 选择服务器,连不上会抛 ConnectionTimeoutException。testPingMethod(L390-L413)演示了正常 ping 与指向 wrong-host 时的超时异常。
  • 服务器版本:getServerVersion()(L524-L527)执行 buildInfo 命令返回 MongoDB 服务器版本;threadCount()(L486-L491)通过 serverStatus 命令返回当前连接数。
  • 查询日志:enableQueryLog()(L197-L205)会注册一个 CommandSubscriber 到驱动层,把 MongoDB 命令记录为 Laravel 查询日志(DB::getQueryLog()),命令以 JSON 形式呈现,例如 {"find":"items","filter":{}}(见 testQueryLog,L289-L323)。排查问题时这比 toSql()(MongoDB 没有 SQL)更有效。

超时与连接池的真相

原文档给出了一段关键的超时配置示例,全部通过 URI 查询参数传递:

mongodb+srv://.../db?serverSelectionTimeoutMS=5000&socketTimeoutMS=30000

参数含义:

URI 参数 作用 典型值
serverSelectionTimeoutMS 服务器选择超时(毫秒),即找不到可用服务器(如副本集主节点、网络不通)时最多等待多久 5000
socketTimeoutMS 单个套接字读写超时(毫秒),长时间无响应的操作会在此后中断 30000
connectTimeoutMS 建立 TCP 连接的超时 取决于环境
retryWrites 是否启用可重试写入(Atlas 默认推荐 true) true

测试配置 tests/config/database.php 中也采用了 connectTimeoutMS => 1000 与 serverSelectionTimeoutMS => 6000 的组合,是这套参数的实战参考。

maxPoolSize / minPoolSize 为什么无效?

原文档明确指出:maxPoolSize 和 minPoolSize 在这里没有任何效果。原因在于:

PHP 扩展(ext-mongodb)以单线程模式驱动 libmongoc,每个服务器最多只持有一个套接字,并且不实现连接池。

也就是说,虽然 URI 里可以写这两个参数(libmongoc 的通用 URI 选项),但在 PHP 的 libmongoc 单线程调度下它们不会带来任何池化行为。调大 maxPoolSize 不会改善并发吞吐——PHP-FPM / 异步模型的并发连接数由进程数决定。生产环境想要更多并行连接,应从应用进程/协程数量层面规划,而不是依赖池化参数。

进阶:不使用 DSN,用 host / port 配置多主机

除 DSN 外,包还支持传统的 host / port 配置(见 getHostDsn,src/Connection.php),适合不想维护长 URI 的场景:

'connections' => [
    'mongodb' => [
        'driver'   => 'mongodb',
        'host'     => ['host-1', 'host-2'],   // 多主机副本集成员
        'port'     => 27017,
        'database' => 'laravel',
    ],
],

其行为由 tests/ConnectionTest.php 的 dataConnectionConfig 数据提供器全面覆盖,值得注意的规则有:

  • 单主机可写作 host => 'some-host',多主机写作数组,生成 mongodb://host-1,host-2;
  • port 会对所有主机统一追加端口(mongodb://host-1:12345,host-2:12345);
  • 主机字符串内自带端口时(host => 'some-host:12345')优先于 port 配置;
  • IPv6 地址会被自动加上方括号,例如 mongodb://[2001:db8:3333:4444:5555:6666:7777:8888]:1234;
  • DSN 优先级高于 host/port:同时给出 dsn 与 host 时以 dsn 为准(L177-L186);
  • options.database 非空时会被当作认证数据库拼入 URI 路径(getHostDsn L422-L424)。

需要认证时,可在配置中提供 username / password,createConnection(L268-L275)会在 options 未显式包含凭据时自动补入。

常见问题速查

现象 原因与对策
MongoDB connection configuration requires "dsn" or "host" key. 连接配置里两个键都缺失,补上其一即可
Database is not properly configured. 未配置 database 且 DSN 中无法提取库名,检查 URI 是否包含 /数据库名
连 Atlas 报 TLS 或 DNS 解析错误 使用 mongodb+srv:// 前缀,并把 tls、tlsCAFile、retryWrites 等放进 URI
服务器选择迟迟不报错 设置 serverSelectionTimeoutMS(如 5000),避免长时间阻塞
想调大并发连接却发现 maxPoolSize 无效 PHP 扩展为单线程 libmongoc、每服务器单 socket、无连接池,从进程/协程数层面规划
->collection() 报方法不存在 该方法不存在;原生集合用 getCollection(),查询构建器用 table()
查询日志为空或想调试生成的命令 使用 DB::enableQueryLog() 后查看 DB::getQueryLog(),或对 Eloquent 查询使用 ->dump() / ->dd()

连接配置是 laravel-mongodb 一切能力(Eloquent 模型、聚合查询、事务、队列、缓存、会话、加密)的地基。掌握 config/database.php、.env、Service Provider 注册与底层 Client/Database 的访问方式后,你就可以放心地在多连接、Atlas 生产环境与复杂应用场景中正确接线;而理解"单线程 libmongoc、无连接池"这一底层事实,则能帮助你在设计高并发架构时避开对 maxPoolSize 的无效依赖。更多深入主题可继续阅读本仓库 resources/boost/skills/laravel-mongodb/references 下的查询构建器、模型、事务与安装指南等参考文档。

登录后查看全文
laravel-mongodb