译：Rich MongoDB Driver for Go

目录

1. Highlights(强调)

1.1. Cluster discovery and communication(集群发现和通信)

mgo offers automated cluster topology(拓扑) discovery and maintenance(维护). Even if provided the address to a single server in the cluster, mgo will figure out(找出) the cluster topology and communicate with any of the servers as necessary.

译：mgo 提供自动化的集群拓扑发现和维护。 即使将地址提供给集群中的单个服务器，mgo也会根据需要找出集群拓扑结构并于任何服务器通信。

1.2. Failover management(故障转移管理)

mgo will automatically failover in the event that the master server changes.

1.3. Synchronous and concurrent(同步和并发)

mgo offers a synchronous interface, with a concurrent backend. Concurrent operations on the same socket do not wait for the previous operation’s roundtrip before being delivered. Documents may also start being processed as soon as the first document is received from the network, and will continue being received in the background so that the connection is unblocked for further requests.

译：mgo提供了一个同步接口，并发后端。 在传递之前，同一个套接字上的并发操作不会等待上一个操作的往返。 一旦从网络接收到第一个文件，文件也可能开始处理，并且将继续在后台接收，以便这个连接对未来的请求不会阻塞掉。

1.4. Result pre-fecthing(结果预取)

mgo offers configurable pre-fetching of documents, so that the next batch of results are requested automatically when an established percentage of the current batch has been processed.

译：mgo 提供可配置的文档预取功能，一边当当前批已经被处理建立百分比的时候可以使下一批的结果自动被请求。

1.5. Flexible serialization(灵活的序列化)

mgo supports flexible marshalling and unmarshalling of documents through gobson, a brand new BSON package written specifically to support mgo.

1.6. Trivial consistency-level management(普通的一致性级别管理)

mgo offers trivial(普通的) consistency-level selection to tweak resource usage vs. read/write ordering guarantees.(保证)

Strong consistency uses a unique connection with the master so that all reads and writes are as up-to-date(最新) as possible and consistent with each other.

Monotonic consistency will start reading from a slave if possible, so that the load is better distributed, and once the first write happens the connection is switched to the master. This offers consistent reads and writes, but may not show the most up-to-date data on reads which precede the first write.

Eventual consistency offers the best resource usage, distributing reads across multiple slaves and writes across multiple connections to the master, but consistency isn’t guaranteed.

Note that this mechanism(机制) works both when connecting through a mongos server and when connecting directly to a replica set.

译：

  • mgo提供简单的一致性级别选择来调整资源使用与 读/写 顺序保证。
  • 强一致性使用与主控制器的独特连接，以便所有的读写操作都尽可能地保持最新，并且彼此保持一致。
  • 如果可能的话，单调一致性将开始从一个从机读取，这样负载分配就会更好，一旦发生第一次写入，连接就切换到主机。 这提供了一致的读取和写入，但可能不会显示第一次写入之前的最新读取到的数据。
  • 最终的一致性提供了最佳的资源利用率，将读取分布在多个从服务器上，并通过多个连接写入主服务器，但是不能保证一致性。
  • 请注意，这种机制在通过mongos服务器连接和直接连接到副本集时都起作用。

1.7. Authentication support with pooling integration(身份验证支持与池集成)

mgo offers authentication support, with great connection pooling integration.

This enables mgo to talk to protected servers and replica sets in a very comfortable way. Even with a straightforward(简单的) API, the authentication is internally cached in a secure way to avoid constant(不断的) roundtrips to the database. The use of nonces is also optimized so that logins are usually performed(履行) with a single roundtrip to the database.

译：这使得mgo能够以非常舒适的方式与受保护的服务器和副本集进行对话。 即使使用简单的API，身份验证也会以一种安全的方式进行内部缓存，以避免往返于数据库。 随机数的使用也进行了优化，以便登录通常是单向往返数据库。

1.8. GridFS support

mgo can be used to send and receive files to MongoDB using the standard GridFS specification(规范) for file storage. This means that it may share the same database collections used for file storage with drivers for other languages, and also the command line tools provided with MongoDB itself (e.g. mongofiles).

In addition to a selection(选择) of relevant(相应的) methods, the *mgo.GridFile type implements support for both io.Reader and io.Writer interfaces, which means it integrates nicely with the standard library.

译：

  • mgo可以用来发送和接收文件到MongoDB使用标准的GridFS规范的文件存储。 这意味着它可以与其他语言的驱动程序共享用于文件存储的相同数据库集合，也可以共享MongoDB本身提供的命令行工具（如mongofiles）。
  • 除了选择相关的方法之外，* mgo.GridFile类型实现了对io.Reader和io.Writer接口的支持，这意味着它与标准库很好地集成。

返回目录

2. API documentation

3. Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

package main

import (
    "fmt"
    "log"
    "gopkg.in/mgo.v2"
    "gopkg.in/mgo.v2/bson"
)

type Person struct {
    Name  string
    Phone string
}

func main() {
    session, err := mgo.Dial("server1.example.com, server2.example.com")
    if err != nil {
        panic(err)
    }
    defer session.Close()

    // Optional. Switch the session to a monotonic(单调的) behavior(行为).
    session.SetMode(mgo.Monotonic, true)

    c := session.DB.("test").C("people")
    err := c.Insert(
        &Person{"Ale", "+55 53 8116 9639"},
        &Person{"Cla", "+55 53 8402 8510"},
    )
    if err != nil {
        log.Fatal(err)
    }

    result := Person{}
    err := c.Find(bson.M{"name": "Ale"}).One(&result)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Phone:", result.Phone)
}

返回目录

4. Session and Pool

Dial方法和MongoDB数据库建立了链接后会返回一个mgo.Session对象；可以用该对象管理所有的CRUD操作, 且 session 能够和 mongodb 集群中的所有Server通讯。

Session管理MongoDB服务器群的连接池， 一个连接池是数据库链接的缓存，所以当新的请求连接数据库的操作会重用已用的连接。

在一个独立的http请求的生命周期，New(), Copy(), Clone()方法会创建Session，会获取Dial方法创建的Session。

  • New(): 创建新的Session对象，和已创建Session有同样的参数；
  • Copy(): 保留原有的Session信息；
  • Clone(): 和Copy()函数一样，但会重用原来的Session建立的Socket连接。

4.1. Session mode

mgo 的 session.SetMode函数说明

1
2
3

// SetMode changes the consistecy mode for the session.
// SetMode 函数用来变换 session 的一致性模式
func (s *Session) SetMode(consistency mode, refresh bool)

4.1.1. Strong

In the Strong consistency mode reads and writes will always be made to the primary server using a unique connection so that reads and writes are fully consistent, ordered, and observing the most up-to-date data. This offers the least benefits in terms of distributing load, but the most guarantees. See also Monotonic and Eventual.

译：在强一致模式下，读写都是在主节点上通过一个唯一的连接实现，这样读写时完全一致，有序并且呈现最新的数据。这种模式在分布式负载架构下没有多少益处，但是保证了读写数据的一致性。

4.1.2. Monotonic(单一的)

In the Monotonic consistency mode reads may not be entirely up-to-date, but they will always see the history of changes moving forward, the data read will be consistent across sequential queries in the same session, and modifications made within the session will be observed in following queries (read-your-writes).

译：在 Monotonic 一致性模式下，读到的数据不一定时最新的，但是在同一个session中的一系列读保持着数据的一致性，而session中的修改在其后的查询中可以得到体现。

Note: session 的读操作开始时向其他服务器发起(且通过一个唯一的连接)， 只要出现了一次写操作，session的连接就会切换至主服务器。由此可见此模式下，能够分散一些读操作到其他服务器，但是读操作不一定能够获得最新的数据。

4.1.3. Eventual

session 的读操作会向任意的其他服务器发起，多次读操作并不一定使用相同的连接，也就是读操作不一定有序。session 的写操作总是向主服务器发起，但是可能使用不同的连接，也就是写操作也不一定有序。

4.1.4. Summary

Strong Monotonic Eventual
read read to primary read to arbitrary（随机的）primary read to any secondary
write write to primary write to primary wirte to primary
connection unique unique independent
guarantee the most some useful the least

返回目录

4.2. Session 的拷贝和并发

5. mgo.DialInfo

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

// DialInfo holds options for establishing a session with a MongoDB cluster.
// To use a URL, see the Dial function.
type DialInfo struct {
	// Addrs holds the addresses for the seed servers.
	Addrs []string

	// Direct informs whether to establish connections only with the
	// specified seed servers, or to obtain information for the whole
	// cluster and establish connections with further servers too.
	Direct bool

	// Timeout is the amount of time to wait for a server to respond when
	// first connecting and on follow up operations in the session. If
	// timeout is zero, the call may block forever waiting for a connection
	// to be established. Timeout does not affect logic in DialServer.
	Timeout time.Duration

	// FailFast will cause connection and query attempts to fail faster when
	// the server is unavailable, instead of retrying until the configured
	// timeout period. Note that an unavailable server may silently drop
	// packets instead of rejecting them, in which case it's impossible to
	// distinguish it from a slow server, so the timeout stays relevant.
	FailFast bool

	// Database is the default database name used when the Session.DB method
	// is called with an empty name, and is also used during the initial
	// authentication if Source is unset.
	Database string

	// ReplicaSetName, if specified, will prevent the obtained session from
	// communicating with any server which is not part of a replica set
	// with the given name. The default is to communicate with any server
	// specified or discovered via the servers contacted.
	ReplicaSetName string

	// Source is the database used to establish credentials and privileges
	// with a MongoDB server. Defaults to the value of Database, if that is
	// set, or "admin" otherwise.
	Source string

	// Service defines the service name to use when authenticating with the GSSAPI
	// mechanism. Defaults to "mongodb".
	Service string

	// ServiceHost defines which hostname to use when authenticating
	// with the GSSAPI mechanism. If not specified, defaults to the MongoDB
	// server's address.
	ServiceHost string

	// Mechanism defines the protocol for credential negotiation.
	// Defaults to "MONGODB-CR".
	Mechanism string

	// Username and Password inform the credentials for the initial authentication
	// done on the database defined by the Source field. See Session.Login.
	Username string
	Password string

	// PoolLimit defines the per-server socket pool limit. Defaults to 4096.
	// See Session.SetPoolLimit for details.
	PoolLimit int

	// DialServer optionally specifies the dial function for establishing
	// connections with the MongoDB servers.
	DialServer func(addr *ServerAddr) (net.Conn, error)

	// WARNING: This field is obsolete. See DialServer above.
	Dial func(addr net.Addr) (net.Conn, error)
}

6. Index

索引时一种特殊的数据结构，索引存储在一个易于遍历读取的数据集合中，索引是对数据库表中一列或者多列的值进行排序的一种结构。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

type Index struct {
	Key        []string // Index key fields; prefix name with dash (-) for descending order
	Unique     bool     // Prevent two documents from having the same index key
	DropDups   bool     // Drop documents with the same index key as a previously indexed one
	Background bool     // Build index in background and return immediately
	Sparse     bool     // Only index documents containing the Key fields

	// If ExpireAfter is defined the server will periodically delete
	// documents with indexed time.Time older than the provided delta.
	ExpireAfter time.Duration

	// Name holds the stored index name. On creation if this field is unset it is
	// computed by EnsureIndex based on the index key.
	Name string
	// ...
}

Note:

  • Key []string: 索引字段(默认升序排序)，其前缀加 - 表示按降序排序

  • Unique bool: 设置建立的索引是否唯一(默认为false)。

  • DropDups bool: 在建立唯一索引时是否删除重复记录，指定为true则创建唯 一索引。(默认为false)

  • Backgroud bool 建立索引过程会阻塞其他数据库操作，backgroud指定在后台创建索引，完成后立即返回。(默认值为false)

  • Sparse bool: 对文档中不存在的字段数据不启用索引；这个参数要特别注意，如果设置为true的话，在索引字段中不会查询出不包含对应的字段的文档。(默认值为false)

  • Name string； 索引的名称，如果未指定，MongoDB通过连接索引的字段名称和排序顺序生成一个索引名称。

  • ExpireAfterSeconds time.Duration: 如果定义了ExpireAfter，则服务器将定期删除索引时间早于提供的增量的文档。

6.1. 关于Index的一些理解

7. 故障排除和性能调优

8. See Also

Thanks to the authors 🙂

返回目录