MongoClient::__construct
(PECL mongo >=1.3.0)
MongoClient::__construct — 创建一个新的数据库连接对象
说明
public MongoClient::__construct
([ string $server
= "mongodb://localhost:27017"
[, array $options
= array("connect" => TRUE
)
]] )
server
应该是这样的形式:
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
连接字符串总是以 mongodb://
开头,表示它是一个连接字符串。
如果指定了 username
和 password
,构造器会在返回前尝试验证连接数据库。
用户名和密码是可选的,需要指定时必须紧随一个 @
。
至少指定一个主机(端口可选,默认总是 27017),并且可以连接到想要数量的主机。
主机名由逗号分隔,构造器会成功返回,如果连接到了至少一个主机。
如果无法连接到任何主机,它将会抛出一个异常 MongoConnectionException。
如果你指定了一个用户名和密码,你可以指定一个要验证的数据库。
如果没有指定 db
,将会使用 "admin"。
可选的查询字符串可以用于指定额外的选项。
同样参数也支持 options
数组。
选项的一部分指示了驱动在集群环境下对备份节点如何读取。
关于读取首选项运行的额外信息可以查找 读取首选项 文档页面。
参数
-
server
-
服务器名。
-
options
-
此连接的数组选项。当前有效的选项包括了:
-
"connect"
构造器是否应该在返回前连接。
默认为 TRUE
。当设置为 FALSE
,驱动会在有查询必要时
自动 连接到服务器。
另外,你也可以用
MongoClient::connect() 手动运行。
Warning
这个选项不支持通过连接字符串来设置。
-
"db"
要验证的数据库能在这里指定,而不是在主机列表中包含它。
能够重载主机列表中指定的数据库。
-
"password"
能在这里指定密码,而不是在主机列表中指定。
当密码里有一个 "@" 的时候尤其有用。
此参数会覆盖主机列表中设置的密码。
-
"readPreference"
指定读取首选项类型。
读取首选项提供了对备份数据读取的控制。
允许的值有: MongoClient::RP_PRIMARY
、
MongoClient::RP_PRIMARY_PREFERRED
、
MongoClient::RP_SECONDARY
、
MongoClient::RP_SECONDARY_PREFERRED
和
MongoClient::RP_NEAREST
。
更多信息参见读取首选项文档。
-
"readPreferenceTags"
以字符串的数组指定读取选项标签。
标签能够控制 readPreference
选项来进一步控制从备份节点数据的读取。
更多信息参见读取首选项文档。
-
"replicaSet"
要连接的集群名称。
如果指定了,活跃节点能够自动检测到。
这意味着驱动能够最终甚至能够连接到未列出的服务器。
更多细节参见集群的例子。
-
"connectTimeoutMS"
打开连接超时的时间。
-
"timeout"
"connectTimeoutMS" 废弃的别名。
-
"socketTimeoutMS"
在套接字上发送或接收超时的时间。
Note:
这是客户端的超时时间。如果一个 insert
达到了 socketTimeoutMS,
将无法得知服务器是否确实已写入。
-
"username"
能在这里指定用户名,而不是在主机列表中指定。
当用户名包括一个「:」时尤其有用。
它会覆盖主机列表中的设置。
-
"w"
选项 w
指定了驱动的
Write Concern,决定了驱动在写入时阻塞的时间。
默认值是 1
。
此选项适用于单台服务器或者是集群。
一个正数值控制了在驱动继续之前,有多少个节点必须应答写入的指令。
值 1
将让单台服务器或者活跃节点(在集群里)应答写入操作。
值 3
将阻塞驱动直至写入到活跃节点和其他两个备份节点服务器(在集群里)。
一个字符串的值用于控制考虑 write concerns 的标签集。
"majority"
是特殊用于确保写入操作被应用于大多数(大于 50%)参与的节点。
-
"wTimeout"
此选项用于和 "w"
参数组合使用。
它控制了服务器等待多少毫秒来满足 write concern。
如果超时了,驱动会抛出 MongoCursorException 异常。
范例
Example #1 MongoClient::__construct() 集群例子
这个例子显示了如何连接本驱动到一个集群。
它假设了有三个服务器的集群: sf1.example.com、sf2.example.com 和 ny1.example.com。
活跃节点可能是其中任意一个。
<?php
// 传递逗号分隔的服务器名称列表到构造器
// 注意我们不需要传入集群的所有成员,驱动能够获取完整的列表
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
?>
如果当前活跃节点连接失败,驱动会计算出备用节点服务器作为新的活跃节点,并自动启用该连接。
如果没有指定 replicaSet
,自动容错移转将无法正常工作。
在驱动连接的集群种子列表里,起码要有一个种子是在线的。
如果你包含的种子位于两个独立的集群,后面的行为将不可预测。
Example #2 连接到一个域套接字(domain socket)
在 1.0.9+ 版本中,你可以使用一个 UNIX 域套接字来连接到一个本地的 MongoDB 实例。
这可能会比使用网络连接稍微快一点。
在版本 1.5.0,MongoDB 服务器会自动打开 /tmp/mongodb-<port>.sock 上的套接字。
你可以在连接字符串中指定位置:
<?php
// MongoDB 服务器运行在本地 20000 端口上
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");
?>
<?php
// 尝试连接到套接字,失败时使用 localhost 连接
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
Example #3 MongoClient::__construct() 验证的例子
在尝试验证时,用户必须存在于 admin 数据库。
你可以通过终端,用 Mongo 创建一个:
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
创建一个用户后,上面的例子里用户名为 "testUser" 并且密码为
"testPass",你可以创建一个验证后的连接:
<?php
$m = new MongoClient("mongodb://testUser:testPass@localhost");
?>
Example #4 MongoClient::__construct() 读取选项例子
<?php
// 首选 "east" 数据中心最近的服务器
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));