laravel-mongodb 连接配置完全指南:从 `config/database.php` 到底层连接池真相
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 的初始化流程是:
getDsn($config)组装连接字符串;- 取
$config['options'] ?? []直接透传给 MongoDB 构造器(appName等所有 URI 之外的驱动选项都在这里); getDefaultDatabaseName($dsn, $config)解析数据库名;createConnection()创建MongoDB\Client;$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 路径(getHostDsnL422-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 下的查询构建器、模型、事务与安装指南等参考文档。