mgo

package
v0.7.0-23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 22, 2016 License: BSD-2-Clause, Apache-2.0 Imports: 20 Imported by: 0

README

The MongoDB driver for Go

Please go to http://labix.org/mgo for all project details.

Documentation

Overview

Package mgo offers a rich MongoDB driver for Go.

Details about the mgo project (pronounced as "mango") are found in its web page: 

http://labix.org/mgo

Usage of the driver revolves around the concept of sessions. To get started, obtain a session using the Dial function: 

session, err := mgo.Dial(url)

This will establish one or more connections with the cluster of servers defined by the url parameter. From then on, the cluster may be queried with multiple consistency rules (see SetMode) and documents retrieved with statements such as: 

c := session.DB(database).C(collection)
err := c.Find(query).One(&result)

New sessions are typically created by calling session.Copy on the initial session obtained at dial time. These new sessions will share the same cluster information and connection pool, and may be easily handed into other methods and functions for organizing logic. Every session created must have its Close method called at the end of its life time, so its resources may be put back in the pool or collected, depending on the case.

For more details, see the documentation for the types and methods.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotFound = errors.New("not found")
	ErrCursor   = errors.New("invalid cursor")
)

Functions

func IsDup 

func IsDup(err error) bool

IsDup returns whether err informs of a duplicate key error because a primary key index or a secondary unique index already has an entry with the given value.

func ResetStats 

func ResetStats()

func SetDebug 

func SetDebug(debug bool)

Enable the delivery of debug messages to the logger. Only meaningful if a logger is also set.

func SetLogger 

func SetLogger(logger log_Logger)

Specify the *log.Logger object where log messages should be sent to.

func SetStats 

func SetStats(enabled bool)

Types

type BuildInfo 

type BuildInfo struct {
	Version        string
	VersionArray   []int  `bson:"versionArray"` // On MongoDB 2.0+; assembled from Version otherwise
	GitVersion     string `bson:"gitVersion"`
	OpenSSLVersion string `bson:"OpenSSLVersion"`
	SysInfo        string `bson:"sysInfo"` // Deprecated and empty on MongoDB 3.2+.
	Bits           int
	Debug          bool
	MaxObjectSize  int `bson:"maxBsonObjectSize"`
}

The BuildInfo type encapsulates details about the running MongoDB server.

Note that the VersionArray field was introduced in MongoDB 2.0+, but it is internally assembled from the Version information for previous versions. In both cases, VersionArray is guaranteed to have at least 4 entries.

func (*BuildInfo) VersionAtLeast 

func (bi *BuildInfo) VersionAtLeast(version ...int) bool

VersionAtLeast returns whether the BuildInfo version is greater than or equal to the provided version number. If more than one number is provided, numbers will be considered as major, minor, and so on.

type Bulk 

type Bulk struct {
	// contains filtered or unexported fields
}

Bulk represents an operation that can be prepared with several orthogonal changes before being delivered to the server.

Relevant documentation: 

http://blog.mongodb.org/post/84922794768/mongodbs-new-bulk-api

func (*Bulk) Insert 

func (b *Bulk) Insert(docs ...interface{})

Insert queues up the provided documents for insertion.

func (*Bulk) Remove 

func (b *Bulk) Remove(selectors ...interface{})

Remove queues up the provided selectors for removing matching documents. Each selector will remove only a single matching document.

func (*Bulk) RemoveAll 

func (b *Bulk) RemoveAll(selectors ...interface{})

RemoveAll queues up the provided selectors for removing all matching documents. Each selector will remove all matching documents.

func (*Bulk) Run 

func (b *Bulk) Run() (*BulkResult, error)

Run runs all the operations queued up.

If an error is reported on an unordered bulk operation, the error value may be an aggregation of all issues observed. As an exception to that, Insert operations running on MongoDB versions prior to 2.6 will report the last error only due to a limitation in the wire protocol.

func (*Bulk) Unordered 

func (b *Bulk) Unordered()

Unordered puts the bulk operation in unordered mode.

In unordered mode the indvidual operations may be sent out of order, which means latter operations may proceed even if prior ones have failed.

func (*Bulk) Update 

func (b *Bulk) Update(pairs ...interface{})

Update queues up the provided pairs of updating instructions. The first element of each pair selects which documents must be updated, and the second element defines how to update it. Each pair matches exactly one document for updating at most.

func (*Bulk) UpdateAll 

func (b *Bulk) UpdateAll(pairs ...interface{})

UpdateAll queues up the provided pairs of updating instructions. The first element of each pair selects which documents must be updated, and the second element defines how to update it. Each pair updates all documents matching the selector.

func (*Bulk) Upsert 

func (b *Bulk) Upsert(pairs ...interface{})

Upsert queues up the provided pairs of upserting instructions. The first element of each pair selects which documents must be updated, and the second element defines how to update it. Each pair matches exactly one document for updating at most.

type BulkResult 

type BulkResult struct {
	Matched  int
	Modified int // Available only for MongoDB 2.6+
	// contains filtered or unexported fields
}

BulkResult holds the results for a bulk operation.

type Change 

type Change struct {
	Update    interface{} // The update document
	Upsert    bool        // Whether to insert in case the document isn't found
	Remove    bool        // Whether to remove the document found rather than updating
	ReturnNew bool        // Should the modified document be returned rather than the old one
}

Change holds fields for running a findAndModify MongoDB command via the Query.Apply method.

type ChangeInfo 

type ChangeInfo struct {
	Updated    int         // Number of existing documents updated
	Removed    int         // Number of documents removed
	UpsertedId interface{} // Upserted _id field, when not explicitly provided
}

ChangeInfo holds details about the outcome of an update operation.

type Collection 

type Collection struct {
	Database *Database
	Name     string // "collection"
	FullName string // "db.collection"
}

func (*Collection) Bulk 

func (c *Collection) Bulk() *Bulk

Bulk returns a value to prepare the execution of a bulk operation.

func (*Collection) Count 

func (c *Collection) Count() (n int, err error)

Count returns the total number of documents in the collection.

func (*Collection) Create 

func (c *Collection) Create(info *CollectionInfo) error

Create explicitly creates the c collection with details of info. MongoDB creates collections automatically on use, so this method is only necessary when creating collection with non-default characteristics, such as capped collections.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/createCollection+Command
http://www.mongodb.org/display/DOCS/Capped+Collections

func (*Collection) DropCollection 

func (c *Collection) DropCollection() error

DropCollection removes the entire collection including all of its documents.

func (*Collection) DropIndex 

func (c *Collection) DropIndex(key ...string) error

DropIndex drops the index with the provided key from the c collection.

See EnsureIndex for details on the accepted key variants.

For example: 

err1 := collection.DropIndex("firstField", "-secondField")
err2 := collection.DropIndex("customIndexName")

func (*Collection) DropIndexName 

func (c *Collection) DropIndexName(name string) error

DropIndexName removes the index with the provided index name.

For example: 

err := collection.DropIndex("customIndexName")

func (*Collection) EnsureIndex 

func (c *Collection) EnsureIndex(index Index) error

EnsureIndex ensures an index with the given key exists, creating it with the provided parameters if necessary. EnsureIndex does not modify a previously existent index with a matching key. The old index must be dropped first instead.

Once EnsureIndex returns successfully, following requests for the same index will not contact the server unless Collection.DropIndex is used to drop the same index, or Session.ResetIndexCache is called.

For example: 

index := Index{
    Key: []string{"lastname", "firstname"},
    Unique: true,
    DropDups: true,
    Background: true, // See notes.
    Sparse: true,
}
err := collection.EnsureIndex(index)

The Key value determines which fields compose the index. The index ordering will be ascending by default. To obtain an index with a descending order, the field name should be prefixed by a dash (e.g. []string{"-time"}). It can also be optionally prefixed by an index kind, as in "$text:summary" or "$2d:-point". The key string format is: 

[$<kind>:][-]<field name>

If the Unique field is true, the index must necessarily contain only a single document per Key. With DropDups set to true, documents with the same key as a previously indexed one will be dropped rather than an error returned.

If Background is true, other connections will be allowed to proceed using the collection without the index while it's being built. Note that the session executing EnsureIndex will be blocked for as long as it takes for the index to be built.

If Sparse is true, only documents containing the provided Key fields will be included in the index. When using a sparse index for sorting, only indexed documents will be returned.

If ExpireAfter is non-zero, the server will periodically scan the collection and remove documents containing an indexed time.Time field with a value older than ExpireAfter. See the documentation for details: 

http://docs.mongodb.org/manual/tutorial/expire-data

Other kinds of indexes are also supported through that API. Here is an example: 

index := Index{
    Key: []string{"$2d:loc"},
    Bits: 26,
}
err := collection.EnsureIndex(index)

The example above requests the creation of a "2d" index for the "loc" field.

The 2D index bounds may be changed using the Min and Max attributes of the Index value. The default bound setting of (-180, 180) is suitable for latitude/longitude pairs.

The Bits parameter sets the precision of the 2D geohash values. If not provided, 26 bits are used, which is roughly equivalent to 1 foot of precision for the default (-180, 180) index bounds.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Indexes
http://www.mongodb.org/display/DOCS/Indexing+Advice+and+FAQ
http://www.mongodb.org/display/DOCS/Indexing+as+a+Background+Operation
http://www.mongodb.org/display/DOCS/Geospatial+Indexing
http://www.mongodb.org/display/DOCS/Multikeys

func (*Collection) EnsureIndexKey 

func (c *Collection) EnsureIndexKey(key ...string) error

EnsureIndexKey ensures an index with the given key exists, creating it if necessary.

This example: 

err := collection.EnsureIndexKey("a", "b")

Is equivalent to: 

err := collection.EnsureIndex(mgo.Index{Key: []string{"a", "b"}})

See the EnsureIndex method for more details.

func (*Collection) Find 

func (c *Collection) Find(query interface{}) *Query

Find prepares a query using the provided document. The document may be a map or a struct value capable of being marshalled with bson. The map may be a generic one using interface{} for its key and/or values, such as bson.M, or it may be a properly typed map. Providing nil as the document is equivalent to providing an empty document such as bson.M{}.

Further details of the query may be tweaked using the resulting Query value, and then executed to retrieve results using methods such as One, For, Iter, or Tail.

In case the resulting document includes a field named $err or errmsg, which are standard ways for MongoDB to return query errors, the returned err will be set to a *QueryError value including the Err message and the Code. In those cases, the result argument is still unmarshalled into with the received document so that any other custom values may be obtained if desired.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Querying
http://www.mongodb.org/display/DOCS/Advanced+Queries

func (*Collection) FindId 

func (c *Collection) FindId(id interface{}) *Query

FindId is a convenience helper equivalent to: 

query := collection.Find(bson.M{"_id": id})

See the Find method for more details.

func (*Collection) Indexes 

func (c *Collection) Indexes() (indexes []Index, err error)

Indexes returns a list of all indexes for the collection.

For example, this snippet would drop all available indexes: 

indexes, err := collection.Indexes()
if err != nil {
    return err
}
for _, index := range indexes {
    err = collection.DropIndex(index.Key...)
    if err != nil {
        return err
    }
}

See the EnsureIndex method for more details on indexes.

func (*Collection) Insert 

func (c *Collection) Insert(docs ...interface{}) error

Insert inserts one or more documents in the respective collection. In case the session is in safe mode (see the SetSafe method) and an error happens while inserting the provided documents, the returned error will be of type *LastError.

func (*Collection) NewIter 

func (c *Collection) NewIter(session *Session, firstBatch []bson.Raw, cursorId int64, err error) *Iter

NewIter returns a newly created iterator with the provided parameters. Using this method is not recommended unless the desired functionality is not yet exposed via a more convenient interface (Find, Pipe, etc).

The optional session parameter associates the lifetime of the returned iterator to an arbitrary session. If nil, the iterator will be bound to c's session.

Documents in firstBatch will be individually provided by the returned iterator before documents from cursorId are made available. If cursorId is zero, only the documents in firstBatch are provided.

If err is not nil, the iterator's Err method will report it after exhausting documents in firstBatch.

NewIter must be called right after the cursor id is obtained, and must not be called on a collection in Eventual mode, because the cursor id is associated with the specific server that returned it. The provided session parameter may be in any mode or state, though.

func (*Collection) Pipe 

func (c *Collection) Pipe(pipeline interface{}) *Pipe

Pipe prepares a pipeline to aggregate. The pipeline document must be a slice built in terms of the aggregation framework language.

For example: 

pipe := collection.Pipe([]bson.M{{"$match": bson.M{"name": "Otavio"}}})
iter := pipe.Iter()

Relevant documentation: 

http://docs.mongodb.org/manual/reference/aggregation
http://docs.mongodb.org/manual/applications/aggregation
http://docs.mongodb.org/manual/tutorial/aggregation-examples

func (*Collection) Remove 

func (c *Collection) Remove(selector interface{}) error

Remove finds a single document matching the provided selector document and removes it from the database. If the session is in safe mode (see SetSafe) a ErrNotFound error is returned if a document isn't found, or a value of type *LastError when some other error is detected.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Removing

func (*Collection) RemoveAll 

func (c *Collection) RemoveAll(selector interface{}) (info *ChangeInfo, err error)

RemoveAll finds all documents matching the provided selector document and removes them from the database. In case the session is in safe mode (see the SetSafe method) and an error happens when attempting the change, the returned error will be of type *LastError.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Removing

func (*Collection) RemoveId 

func (c *Collection) RemoveId(id interface{}) error

RemoveId is a convenience helper equivalent to: 

err := collection.Remove(bson.M{"_id": id})

See the Remove method for more details.

func (*Collection) Repair 

func (c *Collection) Repair() *Iter

Repair returns an iterator that goes over all recovered documents in the collection, in a best-effort manner. This is most useful when there are damaged data files. Multiple copies of the same document may be returned by the iterator.

Repair is supported in MongoDB 2.7.8 and later.

func (*Collection) Update 

func (c *Collection) Update(selector interface{}, update interface{}) error

Update finds a single document matching the provided selector document and modifies it according to the update document. If the session is in safe mode (see SetSafe) a ErrNotFound error is returned if a document isn't found, or a value of type *LastError when some other error is detected.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Updating
http://www.mongodb.org/display/DOCS/Atomic+Operations

func (*Collection) UpdateAll 

func (c *Collection) UpdateAll(selector interface{}, update interface{}) (info *ChangeInfo, err error)

UpdateAll finds all documents matching the provided selector document and modifies them according to the update document. If the session is in safe mode (see SetSafe) details of the executed operation are returned in info or an error of type *LastError when some problem is detected. It is not an error for the update to not be applied on any documents because the selector doesn't match.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Updating
http://www.mongodb.org/display/DOCS/Atomic+Operations

func (*Collection) UpdateId 

func (c *Collection) UpdateId(id interface{}, update interface{}) error

UpdateId is a convenience helper equivalent to: 

err := collection.Update(bson.M{"_id": id}, update)

See the Update method for more details.

func (*Collection) Upsert 

func (c *Collection) Upsert(selector interface{}, update interface{}) (info *ChangeInfo, err error)

Upsert finds a single document matching the provided selector document and modifies it according to the update document. If no document matching the selector is found, the update document is applied to the selector document and the result is inserted in the collection. If the session is in safe mode (see SetSafe) details of the executed operation are returned in info, or an error of type *LastError when some problem is detected.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Updating
http://www.mongodb.org/display/DOCS/Atomic+Operations

func (*Collection) UpsertId 

func (c *Collection) UpsertId(id interface{}, update interface{}) (info *ChangeInfo, err error)

UpsertId is a convenience helper equivalent to: 

info, err := collection.Upsert(bson.M{"_id": id}, update)

See the Upsert method for more details.

func (*Collection) With 

func (c *Collection) With(s *Session) *Collection

With returns a copy of c that uses session s.

type CollectionInfo 

type CollectionInfo struct {
	// DisableIdIndex prevents the automatic creation of the index
	// on the _id field for the collection.
	DisableIdIndex bool

	// ForceIdIndex enforces the automatic creation of the index
	// on the _id field for the collection. Capped collections,
	// for example, do not have such an index by default.
	ForceIdIndex bool

	// If Capped is true new documents will replace old ones when
	// the collection is full. MaxBytes must necessarily be set
	// to define the size when the collection wraps around.
	// MaxDocs optionally defines the number of documents when it
	// wraps, but MaxBytes still needs to be set.
	Capped   bool
	MaxBytes int
	MaxDocs  int
}

The CollectionInfo type holds metadata about a collection.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/createCollection+Command
http://www.mongodb.org/display/DOCS/Capped+Collections

type Credential 

type Credential struct {
	// Username and Password hold the basic details for authentication.
	// Password is optional with some authentication mechanisms.
	Username string
	Password string

	// Source is the database used to establish credentials and privileges
	// with a MongoDB server. Defaults to the default database provided
	// during dial, or "admin" if that was unset.
	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
}

Credential holds details to authenticate with a MongoDB server.

type DBRef 

type DBRef struct {
	Collection string      `bson:"$ref"`
	Id         interface{} `bson:"$id"`
	Database   string      `bson:"$db,omitempty"`
}

The DBRef type implements support for the database reference MongoDB convention as supported by multiple drivers. This convention enables cross-referencing documents between collections and databases using a structure which includes a collection name, a document id, and optionally a database name.

See the FindRef methods on Session and on Database.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Database+References

type Database 

type Database struct {
	Session *Session
	Name    string
}

func (*Database) AddUser 

func (db *Database) AddUser(username, password string, readOnly bool) error

AddUser creates or updates the authentication credentials of user within the db database.

WARNING: This method is obsolete and should only be used with MongoDB 2.2 or earlier. For MongoDB 2.4 and on, use UpsertUser instead.

func (*Database) C 

func (db *Database) C(name string) *Collection

C returns a value representing the named collection.

Creating this value is a very lightweight operation, and involves no network communication.

func (*Database) CollectionNames 

func (db *Database) CollectionNames() (names []string, err error)

CollectionNames returns the collection names present in the db database.

func (*Database) DropDatabase 

func (db *Database) DropDatabase() error

DropDatabase removes the entire database including all of its collections.

func (*Database) FindRef 

func (db *Database) FindRef(ref *DBRef) *Query

FindRef returns a query that looks for the document in the provided reference. If the reference includes the DB field, the document will be retrieved from the respective database.

See also the DBRef type and the FindRef method on Session.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Database+References

func (*Database) GridFS 

func (db *Database) GridFS(prefix string) *GridFS

GridFS returns a GridFS value representing collections in db that follow the standard GridFS specification. The provided prefix (sometimes known as root) will determine which collections to use, and is usually set to "fs" when there is a single GridFS in the database.

See the GridFS Create, Open, and OpenId methods for more details.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/GridFS
http://www.mongodb.org/display/DOCS/GridFS+Tools
http://www.mongodb.org/display/DOCS/GridFS+Specification

func (*Database) Login 

func (db *Database) Login(user, pass string) error

Login authenticates with MongoDB using the provided credential. The authentication is valid for the whole session and will stay valid until Logout is explicitly called for the same database, or the session is closed.

func (*Database) Logout 

func (db *Database) Logout()

Logout removes any established authentication credentials for the database.

func (*Database) RemoveUser 

func (db *Database) RemoveUser(user string) error

RemoveUser removes the authentication credentials of user from the database.

func (*Database) Run 

func (db *Database) Run(cmd interface{}, result interface{}) error

Run issues the provided command on the db database and unmarshals its result in the respective argument. The cmd argument may be either a string with the command name itself, in which case an empty document of the form bson.M{cmd: 1} will be used, or it may be a full command document.

Note that MongoDB considers the first marshalled key as the command name, so when providing a command with options, it's important to use an ordering-preserving document, such as a struct value or an instance of bson.D. For instance: 

db.Run(bson.D{{"create", "mycollection"}, {"size", 1024}})

For privilleged commands typically run on the "admin" database, see the Run method in the Session type.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Commands
http://www.mongodb.org/display/DOCS/List+of+Database+CommandSkips

func (*Database) UpsertUser 

func (db *Database) UpsertUser(user *User) error

UpsertUser updates the authentication credentials and the roles for a MongoDB user within the db database. If the named user doesn't exist it will be created.

This method should only be used from MongoDB 2.4 and on. For older MongoDB releases, use the obsolete AddUser method instead.

Relevant documentation: 

http://docs.mongodb.org/manual/reference/user-privileges/
http://docs.mongodb.org/manual/reference/privilege-documents/

func (*Database) With 

func (db *Database) With(s *Session) *Database

With returns a copy of db that uses session s.

type DialInfo 

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 intial
	// 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)
}

DialInfo holds options for establishing a session with a MongoDB cluster. To use a URL, see the Dial function.

func ParseURL 

func ParseURL(url string) (*DialInfo, error)

ParseURL parses a MongoDB URL as accepted by the Dial function and returns a value suitable for providing into DialWithInfo.

See Dial for more details on the format of url.

type GridFS 

type GridFS struct {
	Files  *Collection
	Chunks *Collection
}

func (*GridFS) Create 

func (gfs *GridFS) Create(name string) (file *GridFile, err error)

Create creates a new file with the provided name in the GridFS. If the file name already exists, a new version will be inserted with an up-to-date uploadDate that will cause it to be atomically visible to the Open and OpenId methods. If the file name is not important, an empty name may be provided and the file Id used instead.

It's important to Close files whether they are being written to or read from, and to check the err result to ensure the operation completed successfully.

A simple example inserting a new file: 

func check(err error) {
    if err != nil {
        panic(err.String())
    }
}
file, err := db.GridFS("fs").Create("myfile.txt")
check(err)
n, err := file.Write([]byte("Hello world!"))
check(err)
err = file.Close()
check(err)
fmt.Printf("%d bytes written\n", n)

The io.Writer interface is implemented by *GridFile and may be used to help on the file creation. For example: 

file, err := db.GridFS("fs").Create("myfile.txt")
check(err)
messages, err := os.Open("/var/log/messages")
check(err)
defer messages.Close()
err = io.Copy(file, messages)
check(err)
err = file.Close()
check(err)

func (*GridFS) Find 

func (gfs *GridFS) Find(query interface{}) *Query

Find runs query on GridFS's files collection and returns the resulting Query.

This logic: 

gfs := db.GridFS("fs")
iter := gfs.Find(nil).Iter()

Is equivalent to: 

files := db.C("fs" + ".files")
iter := files.Find(nil).Iter()

func (*GridFS) Open 

func (gfs *GridFS) Open(name string) (file *GridFile, err error)

Open returns the most recently uploaded file with the provided name, for reading. If the file isn't found, err will be set to mgo.ErrNotFound.

It's important to Close files whether they are being written to or read from, and to check the err result to ensure the operation completed successfully.

The following example will print the first 8192 bytes from the file: 

file, err := db.GridFS("fs").Open("myfile.txt")
check(err)
b := make([]byte, 8192)
n, err := file.Read(b)
check(err)
fmt.Println(string(b))
check(err)
err = file.Close()
check(err)
fmt.Printf("%d bytes read\n", n)

The io.Reader interface is implemented by *GridFile and may be used to deal with it. As an example, the following snippet will dump the whole file into the standard output: 

file, err := db.GridFS("fs").Open("myfile.txt")
check(err)
err = io.Copy(os.Stdout, file)
check(err)
err = file.Close()
check(err)

func (*GridFS) OpenId 

func (gfs *GridFS) OpenId(id interface{}) (file *GridFile, err error)

OpenId returns the file with the provided id, for reading. If the file isn't found, err will be set to mgo.ErrNotFound.

It's important to Close files whether they are being written to or read from, and to check the err result to ensure the operation completed successfully.

The following example will print the first 8192 bytes from the file: 

func check(err error) {
    if err != nil {
        panic(err.String())
    }
}
file, err := db.GridFS("fs").OpenId(objid)
check(err)
b := make([]byte, 8192)
n, err := file.Read(b)
check(err)
fmt.Println(string(b))
check(err)
err = file.Close()
check(err)
fmt.Printf("%d bytes read\n", n)

The io.Reader interface is implemented by *GridFile and may be used to deal with it. As an example, the following snippet will dump the whole file into the standard output: 

file, err := db.GridFS("fs").OpenId(objid)
check(err)
err = io.Copy(os.Stdout, file)
check(err)
err = file.Close()
check(err)

func (*GridFS) OpenNext 

func (gfs *GridFS) OpenNext(iter *Iter, file **GridFile) bool

OpenNext opens the next file from iter for reading, sets *file to it, and returns true on the success case. If no more documents are available on iter or an error occurred, *file is set to nil and the result is false. Errors will be available via iter.Err().

The iter parameter must be an iterator on the GridFS files collection. Using the GridFS.Find method is an easy way to obtain such an iterator, but any iterator on the collection will work.

If the provided *file is non-nil, OpenNext will close it before attempting to iterate to the next element. This means that in a loop one only has to worry about closing files when breaking out of the loop early (break, return, or panic).

For example: 

gfs := db.GridFS("fs")
query := gfs.Find(nil).Sort("filename")
iter := query.Iter()
var f *mgo.GridFile
for gfs.OpenNext(iter, &f) {
    fmt.Printf("Filename: %s\n", f.Name())
}
if iter.Close() != nil {
    panic(iter.Close())
}

func (*GridFS) Remove 

func (gfs *GridFS) Remove(name string) (err error)

Remove deletes all files with the provided name from the GridFS.

func (*GridFS) RemoveId 

func (gfs *GridFS) RemoveId(id interface{}) error

RemoveId deletes the file with the provided id from the GridFS.

type GridFile 

type GridFile struct {
	// contains filtered or unexported fields
}

func (*GridFile) Abort 

func (file *GridFile) Abort()

Abort cancels an in-progress write, preventing the file from being automically created and ensuring previously written chunks are removed when the file is closed.

It is a runtime error to call Abort when the file was not opened for writing.

func (*GridFile) Close 

func (file *GridFile) Close() (err error)

Close flushes any pending changes in case the file is being written to, waits for any background operations to finish, and closes the file.

It's important to Close files whether they are being written to or read from, and to check the err result to ensure the operation completed successfully.

func (*GridFile) ContentType 

func (file *GridFile) ContentType() string

ContentType returns the optional file content type. An empty string will be returned in case it is unset.

func (*GridFile) GetMeta 

func (file *GridFile) GetMeta(result interface{}) (err error)

GetMeta unmarshals the optional "metadata" field associated with the file into the result parameter. The meaning of keys under that field is user-defined. For example: 

result := struct{ INode int }{}
err = file.GetMeta(&result)
if err != nil {
    panic(err.String())
}
fmt.Printf("inode: %d\n", result.INode)

func (*GridFile) Id 

func (file *GridFile) Id() interface{}

Id returns the current file Id.

func (*GridFile) MD5 

func (file *GridFile) MD5() (md5 string)

MD5 returns the file MD5 as a hex-encoded string.

func (*GridFile) Name 

func (file *GridFile) Name() string

Name returns the optional file name. An empty string will be returned in case it is unset.

func (*GridFile) Read 

func (file *GridFile) Read(b []byte) (n int, err error)

Read reads into b the next available data from the file and returns the number of bytes written and an error in case something wrong happened. At the end of the file, n will be zero and err will be set to io.EOF.

The parameters and behavior of this function turn the file into an io.Reader.

func (*GridFile) Seek 

func (file *GridFile) Seek(offset int64, whence int) (pos int64, err error)

Seek sets the offset for the next Read or Write on file to offset, interpreted according to whence: 0 means relative to the origin of the file, 1 means relative to the current offset, and 2 means relative to the end. It returns the new offset and an error, if any.

func (*GridFile) SetChunkSize 

func (file *GridFile) SetChunkSize(bytes int)

SetChunkSize sets size of saved chunks. Once the file is written to, it will be split in blocks of that size and each block saved into an independent chunk document. The default chunk size is 256kb.

It is a runtime error to call this function once the file has started being written to.

func (*GridFile) SetContentType 

func (file *GridFile) SetContentType(ctype string)

ContentType changes the optional file content type. An empty string may be used to unset it.

It is a runtime error to call this function when the file is not open for writing.

func (*GridFile) SetId 

func (file *GridFile) SetId(id interface{})

SetId changes the current file Id.

It is a runtime error to call this function once the file has started being written to, or when the file is not open for writing.

func (*GridFile) SetMeta 

func (file *GridFile) SetMeta(metadata interface{})

SetMeta changes the optional "metadata" field associated with the file. The meaning of keys under that field is user-defined. For example: 

file.SetMeta(bson.M{"inode": inode})

It is a runtime error to call this function when the file is not open for writing.

func (*GridFile) SetName 

func (file *GridFile) SetName(name string)

SetName changes the optional file name. An empty string may be used to unset it.

It is a runtime error to call this function when the file is not open for writing.

func (*GridFile) SetUploadDate 

func (file *GridFile) SetUploadDate(t time.Time)

SetUploadDate changes the file upload time.

It is a runtime error to call this function when the file is not open for writing.

func (*GridFile) Size 

func (file *GridFile) Size() (bytes int64)

Size returns the file size in bytes.

func (*GridFile) UploadDate 

func (file *GridFile) UploadDate() time.Time

UploadDate returns the file upload time.

func (*GridFile) Write 

func (file *GridFile) Write(data []byte) (n int, err error)

Write writes the provided data to the file and returns the number of bytes written and an error in case something wrong happened.

The file will internally cache the data so that all but the last chunk sent to the database have the size defined by SetChunkSize. This also means that errors may be deferred until a future call to Write or Close.

The parameters and behavior of this function turn the file into an io.Writer.

type Index 

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

	// Properties for spatial indexes.
	//
	// Min and Max were improperly typed as int when they should have been
	// floats.  To preserve backwards compatibility they are still typed as
	// int and the following two fields enable reading and writing the same
	// fields as float numbers. In mgo.v3, these fields will be dropped and
	// Min/Max will become floats.
	Min, Max   int
	Minf, Maxf float64
	BucketSize float64
	Bits       int

	// Properties for text indexes.
	DefaultLanguage  string
	LanguageOverride string

	// Weights defines the significance of provided fields relative to other
	// fields in a text index. The score for a given word in a document is derived
	// from the weighted sum of the frequency for each of the indexed fields in
	// that document. The default field weight is 1.
	Weights map[string]int
}

type Iter 

type Iter struct {
	// contains filtered or unexported fields
}

func (*Iter) All 

func (iter *Iter) All(result interface{}) error

All retrieves all documents from the result set into the provided slice and closes the iterator.

The result argument must necessarily be the address for a slice. The slice may be nil or previously allocated.

WARNING: Obviously, All must not be used with result sets that may be potentially large, since it may consume all memory until the system crashes. Consider building the query with a Limit clause to ensure the result size is bounded.

For instance: 

var result []struct{ Value int }
iter := collection.Find(nil).Limit(100).Iter()
err := iter.All(&result)
if err != nil {
    return err
}

func (*Iter) Close 

func (iter *Iter) Close() error

Close kills the server cursor used by the iterator, if any, and returns nil if no errors happened during iteration, or the actual error otherwise.

Server cursors are automatically closed at the end of an iteration, which means close will do nothing unless the iteration was interrupted before the server finished sending results to the driver. If Close is not called in such a situation, the cursor will remain available at the server until the default cursor timeout period is reached. No further problems arise.

Close is idempotent. That means it can be called repeatedly and will return the same result every time.

In case a resulting document included a field named $err or errmsg, which are standard ways for MongoDB to report an improper query, the returned value has a *QueryError type.

func (*Iter) Err 

func (iter *Iter) Err() error

Err returns nil if no errors happened during iteration, or the actual error otherwise.

In case a resulting document included a field named $err or errmsg, which are standard ways for MongoDB to report an improper query, the returned value has a *QueryError type, and includes the Err message and the Code.

func (*Iter) For 

func (iter *Iter) For(result interface{}, f func() error) (err error)

The For method is obsolete and will be removed in a future release. See Iter as an elegant replacement.

func (*Iter) Next 

func (iter *Iter) Next(result interface{}) bool

Next retrieves the next document from the result set, blocking if necessary. This method will also automatically retrieve another batch of documents from the server when the current one is exhausted, or before that in background if pre-fetching is enabled (see the Query.Prefetch and Session.SetPrefetch methods).

Next returns true if a document was successfully unmarshalled onto result, and false at the end of the result set or if an error happened. When Next returns false, the Err method should be called to verify if there was an error during iteration.

For example: 

iter := collection.Find(nil).Iter()
for iter.Next(&result) {
    fmt.Printf("Result: %v\n", result.Id)
}
if err := iter.Close(); err != nil {
    return err
}

func (*Iter) Timeout 

func (iter *Iter) Timeout() bool

Timeout returns true if Next returned false due to a timeout of a tailable cursor. In those cases, Next may be called again to continue the iteration at the previous cursor position.

type LastError 

type LastError struct {
	Err             string
	Code, N, Waited int
	FSyncFiles      int `bson:"fsyncFiles"`
	WTimeout        bool
	UpdatedExisting bool        `bson:"updatedExisting"`
	UpsertedId      interface{} `bson:"upserted"`
	// contains filtered or unexported fields
}

func (*LastError) Error 

func (err *LastError) Error() string

type MapReduce 

type MapReduce struct {
	Map      string      // Map Javascript function code (required)
	Reduce   string      // Reduce Javascript function code (required)
	Finalize string      // Finalize Javascript function code (optional)
	Out      interface{} // Output collection name or document. If nil, results are inlined into the result parameter.
	Scope    interface{} // Optional global scope for Javascript functions
	Verbose  bool
}

type MapReduceInfo 

type MapReduceInfo struct {
	InputCount  int            // Number of documents mapped
	EmitCount   int            // Number of times reduce called emit
	OutputCount int            // Number of documents in resulting collection
	Database    string         // Output database, if results are not inlined
	Collection  string         // Output collection, if results are not inlined
	Time        int64          // Time to run the job, in nanoseconds
	VerboseTime *MapReduceTime // Only defined if Verbose was true
}

type MapReduceTime 

type MapReduceTime struct {
	Total    int64 // Total time, in nanoseconds
	Map      int64 "mapTime"  // Time within map function, in nanoseconds
	EmitLoop int64 "emitLoop" // Time within the emit/map loop, in nanoseconds
}

type Mode 

type Mode int
const (
	// Relevant documentation on read preference modes:
	//
	//     http://docs.mongodb.org/manual/reference/read-preference/
	//
	Primary            Mode = 2 // Default mode. All operations read from the current replica set primary.
	PrimaryPreferred   Mode = 3 // Read from the primary if available. Read from the secondary otherwise.
	Secondary          Mode = 4 // Read from one of the nearest secondary members of the replica set.
	SecondaryPreferred Mode = 5 // Read from one of the nearest secondaries if available. Read from primary otherwise.
	Nearest            Mode = 6 // Read from one of the nearest members, irrespective of it being primary or secondary.

	// Read preference modes are specific to mgo:
	Eventual  Mode = 0 // Same as Nearest, but may change servers between reads.
	Monotonic Mode = 1 // Same as SecondaryPreferred before first write. Same as Primary after first write.
	Strong    Mode = 2 // Same as Primary.
)

type Pipe 

type Pipe struct {
	// contains filtered or unexported fields
}

func (*Pipe) All 

func (p *Pipe) All(result interface{}) error

All works like Iter.All.

func (*Pipe) AllowDiskUse 

func (p *Pipe) AllowDiskUse() *Pipe

AllowDiskUse enables writing to the "<dbpath>/_tmp" server directory so that aggregation pipelines do not have to be held entirely in memory.

func (*Pipe) Batch 

func (p *Pipe) Batch(n int) *Pipe

Batch sets the batch size used when fetching documents from the database. It's possible to change this setting on a per-session basis as well, using the Batch method of Session.

The default batch size is defined by the database server.

func (*Pipe) Explain 

func (p *Pipe) Explain(result interface{}) error

Explain returns a number of details about how the MongoDB server would execute the requested pipeline, such as the number of objects examined, the number of times the read lock was yielded to allow writes to go in, and so on.

For example: 

var m bson.M
err := collection.Pipe(pipeline).Explain(&m)
if err == nil {
    fmt.Printf("Explain: %#v\n", m)
}

func (*Pipe) Iter 

func (p *Pipe) Iter() *Iter

Iter executes the pipeline and returns an iterator capable of going over all the generated results.

func (*Pipe) One 

func (p *Pipe) One(result interface{}) error

One executes the pipeline and unmarshals the first item from the result set into the result parameter. It returns ErrNotFound if no items are generated by the pipeline.

type Query 

type Query struct {
	// contains filtered or unexported fields
}

func (*Query) All 

func (q *Query) All(result interface{}) error

All works like Iter.All.

func (*Query) Apply 

func (q *Query) Apply(change Change, result interface{}) (info *ChangeInfo, err error)

Apply runs the findAndModify MongoDB command, which allows updating, upserting or removing a document matching a query and atomically returning either the old version (the default) or the new version of the document (when ReturnNew is true). If no objects are found Apply returns ErrNotFound.

The Sort and Select query methods affect the result of Apply. In case multiple documents match the query, Sort enables selecting which document to act upon by ordering it first. Select enables retrieving only a selection of fields of the new or old document.

This simple example increments a counter and prints its new value: 

change := mgo.Change{
        Update: bson.M{"$inc": bson.M{"n": 1}},
        ReturnNew: true,
}
info, err = col.Find(M{"_id": id}).Apply(change, &doc)
fmt.Println(doc.N)

This method depends on MongoDB >= 2.0 to work properly.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/findAndModify+Command
http://www.mongodb.org/display/DOCS/Updating
http://www.mongodb.org/display/DOCS/Atomic+Operations

func (*Query) Batch 

func (q *Query) Batch(n int) *Query

Batch sets the batch size used when fetching documents from the database. It's possible to change this setting on a per-session basis as well, using the Batch method of Session.

The default batch size is defined by the database itself. As of this writing, MongoDB will use an initial size of min(100 docs, 4MB) on the first batch, and 4MB on remaining ones.

func (*Query) Comment 

func (q *Query) Comment(comment string) *Query

Comment adds a comment to the query to identify it in the database profiler output.

Relevant documentation: 

http://docs.mongodb.org/manual/reference/operator/meta/comment
http://docs.mongodb.org/manual/reference/command/profile
http://docs.mongodb.org/manual/administration/analyzing-mongodb-performance/#database-profiling

func (*Query) Count 

func (q *Query) Count() (n int, err error)

Count returns the total number of documents in the result set.

func (*Query) Distinct 

func (q *Query) Distinct(key string, result interface{}) error

Distinct unmarshals into result the list of distinct values for the given key.

For example: 

var result []int
err := collection.Find(bson.M{"gender": "F"}).Distinct("age", &result)

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Aggregation

func (*Query) Explain 

func (q *Query) Explain(result interface{}) error

Explain returns a number of details about how the MongoDB server would execute the requested query, such as the number of objects examined, the number of times the read lock was yielded to allow writes to go in, and so on.

For example: 

m := bson.M{}
err := collection.Find(bson.M{"filename": name}).Explain(m)
if err == nil {
    fmt.Printf("Explain: %#v\n", m)
}

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Optimization
http://www.mongodb.org/display/DOCS/Query+Optimizer

func (*Query) For 

func (q *Query) For(result interface{}, f func() error) error

The For method is obsolete and will be removed in a future release. See Iter as an elegant replacement.

func (*Query) Hint 

func (q *Query) Hint(indexKey ...string) *Query

Hint will include an explicit "hint" in the query to force the server to use a specified index, potentially improving performance in some situations. The provided parameters are the fields that compose the key of the index to be used. For details on how the indexKey may be built, see the EnsureIndex method.

For example: 

query := collection.Find(bson.M{"firstname": "Joe", "lastname": "Winter"})
query.Hint("lastname", "firstname")

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Optimization
http://www.mongodb.org/display/DOCS/Query+Optimizer

func (*Query) Iter 

func (q *Query) Iter() *Iter

Iter executes the query and returns an iterator capable of going over all the results. Results will be returned in batches of configurable size (see the Batch method) and more documents will be requested when a configurable number of documents is iterated over (see the Prefetch method).

func (*Query) Limit 

func (q *Query) Limit(n int) *Query

Limit restricts the maximum number of documents retrieved to n, and also changes the batch size to the same value. Once n documents have been returned by Next, the following call will return ErrNotFound.

func (*Query) LogReplay 

func (q *Query) LogReplay() *Query

LogReplay enables an option that optimizes queries that are typically made on the MongoDB oplog for replaying it. This is an internal implementation aspect and most likely uninteresting for other uses. It has seen at least one use case, though, so it's exposed via the API.

func (*Query) MapReduce 

func (q *Query) MapReduce(job *MapReduce, result interface{}) (info *MapReduceInfo, err error)

MapReduce executes a map/reduce job for documents covered by the query. That kind of job is suitable for very flexible bulk aggregation of data performed at the server side via Javascript functions.

Results from the job may be returned as a result of the query itself through the result parameter in case they'll certainly fit in memory and in a single document. If there's the possibility that the amount of data might be too large, results must be stored back in an alternative collection or even a separate database, by setting the Out field of the provided MapReduce job. In that case, provide nil as the result parameter.

These are some of the ways to set Out: 

nil
    Inline results into the result parameter.

bson.M{"replace": "mycollection"}
    The output will be inserted into a collection which replaces any
    existing collection with the same name.

bson.M{"merge": "mycollection"}
    This option will merge new data into the old output collection. In
    other words, if the same key exists in both the result set and the
    old collection, the new key will overwrite the old one.

bson.M{"reduce": "mycollection"}
    If documents exist for a given key in the result set and in the old
    collection, then a reduce operation (using the specified reduce
    function) will be performed on the two values and the result will be
    written to the output collection. If a finalize function was
    provided, this will be run after the reduce as well.

bson.M{...., "db": "mydb"}
    Any of the above options can have the "db" key included for doing
    the respective action in a separate database.

The following is a trivial example which will count the number of occurrences of a field named n on each document in a collection, and will return results inline: 

job := &mgo.MapReduce{
        Map:      "function() { emit(this.n, 1) }",
        Reduce:   "function(key, values) { return Array.sum(values) }",
}
var result []struct { Id int "_id"; Value int }
_, err := collection.Find(nil).MapReduce(job, &result)
if err != nil {
    return err
}
for _, item := range result {
    fmt.Println(item.Value)
}

This function is compatible with MongoDB 1.7.4+.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/MapReduce

func (*Query) One 

func (q *Query) One(result interface{}) (err error)

One executes the query and unmarshals the first obtained document into the result argument. The result must be a struct or map value capable of being unmarshalled into by gobson. This function blocks until either a result is available or an error happens. For example: 

err := collection.Find(bson.M{"a", 1}).One(&result)

In case the resulting document includes a field named $err or errmsg, which are standard ways for MongoDB to return query errors, the returned err will be set to a *QueryError value including the Err message and the Code. In those cases, the result argument is still unmarshalled into with the received document so that any other custom values may be obtained if desired.

func (*Query) Prefetch 

func (q *Query) Prefetch(p float64) *Query

Prefetch sets the point at which the next batch of results will be requested. When there are p*batch_size remaining documents cached in an Iter, the next batch will be requested in background. For instance, when using this: 

query.Batch(200).Prefetch(0.25)

and there are only 50 documents cached in the Iter to be processed, the next batch of 200 will be requested. It's possible to change this setting on a per-session basis as well, using the SetPrefetch method of Session.

The default prefetch value is 0.25.

func (*Query) Select 

func (q *Query) Select(selector interface{}) *Query

Select enables selecting which fields should be retrieved for the results found. For example, the following query would only retrieve the name field: 

err := collection.Find(nil).Select(bson.M{"name": 1}).One(&result)

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Retrieving+a+Subset+of+Fields

func (*Query) SetMaxScan 

func (q *Query) SetMaxScan(n int) *Query

SetMaxScan constrains the query to stop after scanning the specified number of documents.

This modifier is generally used to prevent potentially long running queries from disrupting performance by scanning through too much data.

func (*Query) SetMaxTime 

func (q *Query) SetMaxTime(d time.Duration) *Query

SetMaxTime constrains the query to stop after running for the specified time.

When the time limit is reached MongoDB automatically cancels the query. This can be used to efficiently prevent and identify unexpectedly slow queries.

A few important notes about the mechanism enforcing this limit:

  • Requests can block behind locking operations on the server, and that blocking time is not accounted for. In other words, the timer starts ticking only after the actual start of the query when it initially acquires the appropriate lock;

  • Operations are interrupted only at interrupt points where an operation can be safely aborted – the total execution time may exceed the specified value;

  • The limit can be applied to both CRUD operations and commands, but not all commands are interruptible;

  • While iterating over results, computing follow up batches is included in the total time and the iteration continues until the alloted time is over, but network roundtrips are not taken into account for the limit.

  • This limit does not override the inactive cursor timeout for idle cursors (default is 10 min).

This mechanism was introduced in MongoDB 2.6.

Relevant documentation: 

http://blog.mongodb.org/post/83621787773/maxtimems-and-query-optimizer-introspection-in

func (*Query) Skip 

func (q *Query) Skip(n int) *Query

Skip skips over the n initial documents from the query results. Note that this only makes sense with capped collections where documents are naturally ordered by insertion time, or with sorted results.

func (*Query) Snapshot 

func (q *Query) Snapshot() *Query

Snapshot will force the performed query to make use of an available index on the _id field to prevent the same document from being returned more than once in a single iteration. This might happen without this setting in situations when the document changes in size and thus has to be moved while the iteration is running.

Because snapshot mode traverses the _id index, it may not be used with sorting or explicit hints. It also cannot use any other index for the query.

Even with snapshot mode, items inserted or deleted during the query may or may not be returned; that is, this mode is not a true point-in-time snapshot.

The same effect of Snapshot may be obtained by using any unique index on field(s) that will not be modified (best to use Hint explicitly too). A non-unique index (such as creation time) may be made unique by appending _id to the index when creating it.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/How+to+do+Snapshotted+Queries+in+the+Mongo+Database

func (*Query) Sort 

func (q *Query) Sort(fields ...string) *Query

Sort asks the database to order returned documents according to the provided field names. A field name may be prefixed by - (minus) for it to be sorted in reverse order.

For example: 

query1 := collection.Find(nil).Sort("firstname", "lastname")
query2 := collection.Find(nil).Sort("-age")
query3 := collection.Find(nil).Sort("$natural")
query4 := collection.Find(nil).Select(bson.M{"score": bson.M{"$meta": "textScore"}}).Sort("$textScore:score")

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Sorting+and+Natural+Order

func (*Query) Tail 

func (q *Query) Tail(timeout time.Duration) *Iter

Tail returns a tailable iterator. Unlike a normal iterator, a tailable iterator may wait for new values to be inserted in the collection once the end of the current result set is reached, A tailable iterator may only be used with capped collections.

The timeout parameter indicates how long Next will block waiting for a result before timing out. If set to -1, Next will not timeout, and will continue waiting for a result for as long as the cursor is valid and the session is not closed. If set to 0, Next times out as soon as it reaches the end of the result set. Otherwise, Next will wait for at least the given number of seconds for a new document to be available before timing out.

On timeouts, Next will unblock and return false, and the Timeout method will return true if called. In these cases, Next may still be called again on the same iterator to check if a new value is available at the current cursor position, and again it will block according to the specified timeoutSecs. If the cursor becomes invalid, though, both Next and Timeout will return false and the query must be restarted.

The following example demonstrates timeout handling and query restarting: 

iter := collection.Find(nil).Sort("$natural").Tail(5 * time.Second)
for {
     for iter.Next(&result) {
         fmt.Println(result.Id)
         lastId = result.Id
     }
     if iter.Err() != nil {
         return iter.Close()
     }
     if iter.Timeout() {
         continue
     }
     query := collection.Find(bson.M{"_id": bson.M{"$gt": lastId}})
     iter = query.Sort("$natural").Tail(5 * time.Second)
}
iter.Close()

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Tailable+Cursors
http://www.mongodb.org/display/DOCS/Capped+Collections
http://www.mongodb.org/display/DOCS/Sorting+and+Natural+Order

type QueryError 

type QueryError struct {
	Code      int
	Message   string
	Assertion bool
}

func (*QueryError) Error 

func (err *QueryError) Error() string

type Role 

type Role string
const (
	// Relevant documentation:
	//
	//     http://docs.mongodb.org/manual/reference/user-privileges/
	//
	RoleRoot         Role = "root"
	RoleRead         Role = "read"
	RoleReadAny      Role = "readAnyDatabase"
	RoleReadWrite    Role = "readWrite"
	RoleReadWriteAny Role = "readWriteAnyDatabase"
	RoleDBAdmin      Role = "dbAdmin"
	RoleDBAdminAny   Role = "dbAdminAnyDatabase"
	RoleUserAdmin    Role = "userAdmin"
	RoleUserAdminAny Role = "userAdminAnyDatabase"
	RoleClusterAdmin Role = "clusterAdmin"
)

type Safe 

type Safe struct {
	W        int    // Min # of servers to ack before success
	WMode    string // Write mode for MongoDB 2.0+ (e.g. "majority")
	WTimeout int    // Milliseconds to wait for W before timing out
	FSync    bool   // Sync via the journal if present, or via data files sync otherwise
	J        bool   // Sync via the journal if present
}

See SetSafe for details on the Safe type.

type ServerAddr 

type ServerAddr struct {
	// contains filtered or unexported fields
}

ServerAddr represents the address for establishing a connection to an individual MongoDB server.

func (*ServerAddr) String 

func (addr *ServerAddr) String() string

String returns the address that was provided for the server before resolution.

func (*ServerAddr) TCPAddr 

func (addr *ServerAddr) TCPAddr() *net.TCPAddr

TCPAddr returns the resolved TCP address for the server.

type Session 

type Session struct {
	// contains filtered or unexported fields
}

Session represents a communication session with the database.

All Session methods are concurrency-safe and may be called from multiple goroutines. In all session modes but Eventual, using the session from multiple goroutines will cause them to share the same underlying socket. See the documentation on Session.SetMode for more details.

func Dial 

func Dial(url string) (*Session, error)

Dial establishes a new session to the cluster identified by the given seed server(s). The session will enable communication with all of the servers in the cluster, so the seed servers are used only to find out about the cluster topology.

Dial will timeout after 10 seconds if a server isn't reached. The returned session will timeout operations after one minute by default if servers aren't available. To customize the timeout, see DialWithTimeout, SetSyncTimeout, and SetSocketTimeout.

This method is generally called just once for a given cluster. Further sessions to the same cluster are then established using the New or Copy methods on the obtained session. This will make them share the underlying cluster, and manage the pool of connections appropriately.

Once the session is not useful anymore, Close must be called to release the resources appropriately.

The seed servers must be provided in the following format: 

[mongodb://][user:pass@]host1[:port1][,host2[:port2],...][/database][?options]

For example, it may be as simple as: 

localhost

Or more involved like: 

mongodb://myuser:mypass@localhost:40001,otherhost:40001/mydb

If the port number is not provided for a server, it defaults to 27017.

The username and password provided in the URL will be used to authenticate into the database named after the slash at the end of the host names, or into the "admin" database if none is provided. The authentication information will persist in sessions obtained through the New method as well.

The following connection options are supported after the question mark: 

connect=direct

    Disables the automatic replica set server discovery logic, and
    forces the use of servers provided only (even if secondaries).
    Note that to talk to a secondary the consistency requirements
    must be relaxed to Monotonic or Eventual via SetMode.

authSource=<db>

    Informs the database used to establish credentials and privileges
    with a MongoDB server. Defaults to the database name provided via
    the URL path, and "admin" if that's unset.

authMechanism=<mechanism>

   Defines the protocol for credential negotiation. Defaults to "MONGODB-CR",
   which is the default username/password challenge-response mechanism.

gssapiServiceName=<name>

   Defines the service name to use when authenticating with the GSSAPI
   mechanism. Defaults to "mongodb".

maxPoolSize=<limit>

   Defines the per-server socket pool limit. Defaults to 4096.
   See Session.SetPoolLimit for details.

Relevant documentation: 

http://docs.mongodb.org/manual/reference/connection-string/

func DialWithInfo 

func DialWithInfo(info *DialInfo) (*Session, error)

DialWithInfo establishes a new session to the cluster identified by info.

func DialWithTimeout 

func DialWithTimeout(url string, timeout time.Duration) (*Session, error)

DialWithTimeout works like Dial, but uses timeout as the amount of time to wait for a server to respond when first connecting and also on follow up operations in the session. If timeout is zero, the call may block forever waiting for a connection to be made.

See SetSyncTimeout for customizing the timeout for the session.

func (*Session) BuildInfo 

func (s *Session) BuildInfo() (info BuildInfo, err error)

BuildInfo retrieves the version and other details about the running MongoDB server.

func (*Session) Clone 

func (s *Session) Clone() *Session

Clone works just like Copy, but also reuses the same socket as the original session, in case it had already reserved one due to its consistency guarantees. This behavior ensures that writes performed in the old session are necessarily observed when using the new session, as long as it was a strong or monotonic session. That said, it also means that long operations may cause other goroutines using the original session to wait.

func (*Session) Close 

func (s *Session) Close()

Close terminates the session. It's a runtime error to use a session after it has been closed.

func (*Session) Copy 

func (s *Session) Copy() *Session

Copy works just like New, but preserves the exact authentication information from the original session.

func (*Session) DB 

func (s *Session) DB(name string) *Database

DB returns a value representing the named database. If name is empty, the database name provided in the dialed URL is used instead. If that is also empty, "test" is used as a fallback in a way equivalent to the mongo shell.

Creating this value is a very lightweight operation, and involves no network communication.

func (*Session) DatabaseNames 

func (s *Session) DatabaseNames() (names []string, err error)

DatabaseNames returns the names of non-empty databases present in the cluster.

func (*Session) EnsureSafe 

func (s *Session) EnsureSafe(safe *Safe)

EnsureSafe compares the provided safety parameters with the ones currently in use by the session and picks the most conservative choice for each setting.

That is:

  • safe.WMode is always used if set.
  • safe.W is used if larger than the current W and WMode is empty.
  • safe.FSync is always used if true.
  • safe.J is used if FSync is false.
  • safe.WTimeout is used if set and smaller than the current WTimeout.

For example, the following statement will ensure the session is at least checking for errors, without enforcing further constraints. If a more conservative SetSafe or EnsureSafe call was previously done, the following call will be ignored. 

session.EnsureSafe(&mgo.Safe{})

See also the SetSafe method for details on what each option means.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/getLastError+Command
http://www.mongodb.org/display/DOCS/Verifying+Propagation+of+Writes+with+getLastError
http://www.mongodb.org/display/DOCS/Data+Center+Awareness

func (*Session) FindRef 

func (s *Session) FindRef(ref *DBRef) *Query

FindRef returns a query that looks for the document in the provided reference. For a DBRef to be resolved correctly at the session level it must necessarily have the optional DB field defined.

See also the DBRef type and the FindRef method on Database.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Database+References

func (*Session) Fsync 

func (s *Session) Fsync(async bool) error

Fsync flushes in-memory writes to disk on the server the session is established with. If async is true, the call returns immediately, otherwise it returns after the flush has been made.

func (*Session) FsyncLock 

func (s *Session) FsyncLock() error

FsyncLock locks all writes in the specific server the session is established with and returns. Any writes attempted to the server after it is successfully locked will block until FsyncUnlock is called for the same server.

This method works on secondaries as well, preventing the oplog from being flushed while the server is locked, but since only the server connected to is locked, for locking specific secondaries it may be necessary to establish a connection directly to the secondary (see Dial's connect=direct option).

As an important caveat, note that once a write is attempted and blocks, follow up reads will block as well due to the way the lock is internally implemented in the server. More details at: 

https://jira.mongodb.org/browse/SERVER-4243

FsyncLock is often used for performing consistent backups of the database files on disk.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/fsync+Command
http://www.mongodb.org/display/DOCS/Backups

func (*Session) FsyncUnlock 

func (s *Session) FsyncUnlock() error

FsyncUnlock releases the server for writes. See FsyncLock for details.

func (*Session) LiveServers 

func (s *Session) LiveServers() (addrs []string)

LiveServers returns a list of server addresses which are currently known to be alive.

func (*Session) Login 

func (s *Session) Login(cred *Credential) error

Login authenticates with MongoDB using the provided credential. The authentication is valid for the whole session and will stay valid until Logout is explicitly called for the same database, or the session is closed.

func (*Session) LogoutAll 

func (s *Session) LogoutAll()

LogoutAll removes all established authentication credentials for the session.

func (*Session) Mode 

func (s *Session) Mode() Mode

Mode returns the current consistency mode for the session.

func (*Session) New 

func (s *Session) New() *Session

New creates a new session with the same parameters as the original session, including consistency, batch size, prefetching, safety mode, etc. The returned session will use sockets from the pool, so there's a chance that writes just performed in another session may not yet be visible.

Login information from the original session will not be copied over into the new session unless it was provided through the initial URL for the Dial function.

See the Copy and Clone methods.

func (*Session) Ping 

func (s *Session) Ping() error

Ping runs a trivial ping command just to get in touch with the server.

func (*Session) Refresh 

func (s *Session) Refresh()

Refresh puts back any reserved sockets in use and restarts the consistency guarantees according to the current consistency setting for the session.

func (*Session) ResetIndexCache 

func (s *Session) ResetIndexCache()

ResetIndexCache() clears the cache of previously ensured indexes. Following requests to EnsureIndex will contact the server.

func (*Session) Run 

func (s *Session) Run(cmd interface{}, result interface{}) error

Run issues the provided command on the "admin" database and and unmarshals its result in the respective argument. The cmd argument may be either a string with the command name itself, in which case an empty document of the form bson.M{cmd: 1} will be used, or it may be a full command document.

Note that MongoDB considers the first marshalled key as the command name, so when providing a command with options, it's important to use an ordering-preserving document, such as a struct value or an instance of bson.D. For instance: 

db.Run(bson.D{{"create", "mycollection"}, {"size", 1024}})

For commands on arbitrary databases, see the Run method in the Database type.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/Commands
http://www.mongodb.org/display/DOCS/List+of+Database+CommandSkips

func (*Session) Safe 

func (s *Session) Safe() (safe *Safe)

Safe returns the current safety mode for the session.

func (*Session) SelectServers 

func (s *Session) SelectServers(tags ...bson.D)

SelectServers restricts communication to servers configured with the given tags. For example, the following statement restricts servers used for reading operations to those with both tag "disk" set to "ssd" and tag "rack" set to 1: 

session.SelectServers(bson.D{{"disk", "ssd"}, {"rack", 1}})

Multiple sets of tags may be provided, in which case the used server must match all tags within any one set.

If a connection was previously assigned to the session due to the current session mode (see Session.SetMode), the tag selection will only be enforced after the session is refreshed.

Relevant documentation: 

http://docs.mongodb.org/manual/tutorial/configure-replica-set-tag-sets

func (*Session) SetBatch 

func (s *Session) SetBatch(n int)

SetBatch sets the default batch size used when fetching documents from the database. It's possible to change this setting on a per-query basis as well, using the Query.Batch method.

The default batch size is defined by the database itself. As of this writing, MongoDB will use an initial size of min(100 docs, 4MB) on the first batch, and 4MB on remaining ones.

func (*Session) SetBypassValidation 

func (s *Session) SetBypassValidation(bypass bool)

SetBypassValidation sets whether the server should bypass the registered validation expressions executed when documents are inserted or modified, in the interest of preserving properties for documents in the collection being modfified. The default is to not bypass, and thus to perform the validation expressions registered for modified collections.

Document validation was introuced in MongoDB 3.2.

Relevant documentation: 

https://docs.mongodb.org/manual/release-notes/3.2/#bypass-validation

func (*Session) SetCursorTimeout 

func (s *Session) SetCursorTimeout(d time.Duration)

SetCursorTimeout changes the standard timeout period that the server enforces on created cursors. The only supported value right now is 0, which disables the timeout. The standard server timeout is 10 minutes.

func (*Session) SetMode 

func (s *Session) SetMode(consistency Mode, refresh bool)

SetMode changes the consistency mode for the session.

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.

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).

In practice, the Monotonic mode is obtained by performing initial reads on a unique connection to an arbitrary secondary, if one is available, and once the first write happens, the session connection is switched over to the primary server. This manages to distribute some of the reading load with secondaries, while maintaining some useful guarantees.

In the Eventual consistency mode reads will be made to any secondary in the cluster, if one is available, and sequential reads will not necessarily be made with the same connection. This means that data may be observed out of order. Writes will of course be issued to the primary, but independent writes in the same Eventual session may also be made with independent connections, so there are also no guarantees in terms of write ordering (no read-your-writes guarantees either).

The Eventual mode is the fastest and most resource-friendly, but is also the one offering the least guarantees about ordering of the data read and written.

If refresh is true, in addition to ensuring the session is in the given consistency mode, the consistency guarantees will also be reset (e.g. a Monotonic session will be allowed to read from secondaries again). This is equivalent to calling the Refresh function.

Shifting between Monotonic and Strong modes will keep a previously reserved connection for the session unless refresh is true or the connection is unsuitable (to a secondary server in a Strong session).

func (*Session) SetPoolLimit 

func (s *Session) SetPoolLimit(limit int)

SetPoolLimit sets the maximum number of sockets in use in a single server before this session will block waiting for a socket to be available. The default limit is 4096.

This limit must be set to cover more than any expected workload of the application. It is a bad practice and an unsupported use case to use the database driver to define the concurrency limit of an application. Prevent such concurrency "at the door" instead, by properly restricting the amount of used resources and number of goroutines before they are created.

func (*Session) SetPrefetch 

func (s *Session) SetPrefetch(p float64)

SetPrefetch sets the default point at which the next batch of results will be requested. When there are p*batch_size remaining documents cached in an Iter, the next batch will be requested in background. For instance, when using this: 

session.SetBatch(200)
session.SetPrefetch(0.25)

and there are only 50 documents cached in the Iter to be processed, the next batch of 200 will be requested. It's possible to change this setting on a per-query basis as well, using the Prefetch method of Query.

The default prefetch value is 0.25.

func (*Session) SetSafe 

func (s *Session) SetSafe(safe *Safe)

SetSafe changes the session safety mode.

If the safe parameter is nil, the session is put in unsafe mode, and writes become fire-and-forget, without error checking. The unsafe mode is faster since operations won't hold on waiting for a confirmation.

If the safe parameter is not nil, any changing query (insert, update, ...) will be followed by a getLastError command with the specified parameters, to ensure the request was correctly processed.

The safe.W parameter determines how many servers should confirm a write before the operation is considered successful. If set to 0 or 1, the command will return as soon as the primary is done with the request. If safe.WTimeout is greater than zero, it determines how many milliseconds to wait for the safe.W servers to respond before returning an error.

Starting with MongoDB 2.0.0 the safe.WMode parameter can be used instead of W to request for richer semantics. If set to "majority" the server will wait for a majority of members from the replica set to respond before returning. Custom modes may also be defined within the server to create very detailed placement schemas. See the data awareness documentation in the links below for more details (note that MongoDB internally reuses the "w" field name for WMode).

If safe.J is true, servers will block until write operations have been committed to the journal. Cannot be used in combination with FSync. Prior to MongoDB 2.6 this option was ignored if the server was running without journaling. Starting with MongoDB 2.6 write operations will fail with an exception if this option is used when the server is running without journaling.

If safe.FSync is true and the server is running without journaling, blocks until the server has synced all data files to disk. If the server is running with journaling, this acts the same as the J option, blocking until write operations have been committed to the journal. Cannot be used in combination with J.

Since MongoDB 2.0.0, the safe.J option can also be used instead of FSync to force the server to wait for a group commit in case journaling is enabled. The option has no effect if the server has journaling disabled.

For example, the following statement will make the session check for errors, without imposing further constraints: 

session.SetSafe(&mgo.Safe{})

The following statement will force the server to wait for a majority of members of a replica set to return (MongoDB 2.0+ only): 

session.SetSafe(&mgo.Safe{WMode: "majority"})

The following statement, on the other hand, ensures that at least two servers have flushed the change to disk before confirming the success of operations: 

session.EnsureSafe(&mgo.Safe{W: 2, FSync: true})

The following statement, on the other hand, disables the verification of errors entirely: 

session.SetSafe(nil)

See also the EnsureSafe method.

Relevant documentation: 

http://www.mongodb.org/display/DOCS/getLastError+Command
http://www.mongodb.org/display/DOCS/Verifying+Propagation+of+Writes+with+getLastError
http://www.mongodb.org/display/DOCS/Data+Center+Awareness

func (*Session) SetSocketTimeout 

func (s *Session) SetSocketTimeout(d time.Duration)

SetSocketTimeout sets the amount of time to wait for a non-responding socket to the database before it is forcefully closed.

func (*Session) SetSyncTimeout 

func (s *Session) SetSyncTimeout(d time.Duration)

SetSyncTimeout sets the amount of time an operation with this session will wait before returning an error in case a connection to a usable server can't be established. Set it to zero to wait forever. The default value is 7 seconds.

type Stats 

type Stats struct {
	Clusters     int
	MasterConns  int
	SlaveConns   int
	SentOps      int
	ReceivedOps  int
	ReceivedDocs int
	SocketsAlive int
	SocketsInUse int
	SocketRefs   int
}

func GetStats 

func GetStats() (snapshot Stats)

type User 

type User struct {
	// Username is how the user identifies itself to the system.
	Username string `bson:"user"`

	// Password is the plaintext password for the user. If set,
	// the UpsertUser method will hash it into PasswordHash and
	// unset it before the user is added to the database.
	Password string `bson:",omitempty"`

	// PasswordHash is the MD5 hash of Username+":mongo:"+Password.
	PasswordHash string `bson:"pwd,omitempty"`

	// CustomData holds arbitrary data admins decide to associate
	// with this user, such as the full name or employee id.
	CustomData interface{} `bson:"customData,omitempty"`

	// Roles indicates the set of roles the user will be provided.
	// See the Role constants.
	Roles []Role `bson:"roles"`

	// OtherDBRoles allows assigning roles in other databases from
	// user documents inserted in the admin database. This field
	// only works in the admin database.
	OtherDBRoles map[string][]Role `bson:"otherDBRoles,omitempty"`

	// UserSource indicates where to look for this user's credentials.
	// It may be set to a database name, or to "$external" for
	// consulting an external resource such as Kerberos. UserSource
	// must not be set if Password or PasswordHash are present.
	//
	// WARNING: This setting was only ever supported in MongoDB 2.4,
	// and is now obsolete.
	UserSource string `bson:"userSource,omitempty"`
}

User represents a MongoDB user.

Relevant documentation: 

http://docs.mongodb.org/manual/reference/privilege-documents/
http://docs.mongodb.org/manual/reference/user-privileges/

Source Files

View all Source files

Directories

Path Synopsis
Package bson is an implementation of the BSON specification for Go:
 Package bson is an implementation of the BSON specification for Go:
internal
sasl
scram
Pacakage scram implements a SCRAM-{SHA-1,etc} client per RFC5802.
 Pacakage scram implements a SCRAM-{SHA-1,etc} client per RFC5802.
WARNING: This package was replaced by mgo.v2/dbtest.
 WARNING: This package was replaced by mgo.v2/dbtest.
The txn package implements support for multi-document transactions.
 The txn package implements support for multi-document transactions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.