README
¶
MongoDB Go Driver
The MongoDB supported driver for Go.
- Requirements
- Installation
- Usage
- Bugs/Feature Reporting
- Testing / Development
- Continuous Integration
- License
Requirements
- Go 1.10 or higher. We aim to support the latest supported versions of go.
- MongoDB 3.2 and higher.
Installation
The recommended way to get started using the MongoDB Go driver is by using dep to install the dependency in your project.
dep ensure -add github.com/mongodb/mongo-go-driver/mongo
Usage
To get started with the driver, import the mongo package, create a mongo.Client:
import "github.com/mongodb/mongo-go-driver/mongo"
client, err := mongo.NewClient("mongodb://localhost:27017")
And connect it to your running MongoDB server:
ctx, _ := context.WithTimeout(context.Background(), 10*time.Second)
err = client.Connect(ctx)
To do this in a single step, you can use the Connect function:
ctx, _ := context.WithTimeout(context.Background(), 10*time.Second)
client, err := mongo.Connect(ctx, "mongodb://localhost:27017")
Calling Connect does not block for server discovery. If you wish to know if a MongoDB server has been found and connected to,
use the Ping method:
ctx, _ = context.WithTimeout(context.Background(), 2*time.Second)
err = client.Ping(ctx, readpref.Primary())
To insert a document into a collection, first retrieve a Database and then Collection instance from the Client:
collection := client.Database("testing").Collection("numbers")
The Collection instance can then be used to insert documents:
ctx, _ = context.WithTimeout(context.Background(), 5*time.Second)
res, err := collection.InsertOne(ctx, bson.M{"name": "pi", "value": 3.14159})
id := res.InsertedID
Several query methods return a cursor, which can be used like this:
ctx, _ = context.WithTimeout(context.Background(), 30*time.Second)
cur, err := collection.Find(ctx, nil)
if err != nil { log.Fatal(err) }
defer cur.Close(ctx)
for cur.Next(ctx) {
var result bson.M
err := cur.Decode(&result)
if err != nil { log.Fatal(err) }
// do something with result....
}
if err := cur.Err(); err != nil {
log.Fatal(err)
}
For methods that return a single item, a SingleResult instance is returned:
var result struct {
Value float64
}
filter := bson.M{"name": "pi"}
ctx, _ = context.WithTimeout(context.Background(), 5*time.Second)
err = collection.FindOne(ctx, filter).Decode(&result)
if err != nil {
log.Fatal(err)
}
// Do something with result...
Additional examples and documentation can be found under the examples directory and on the MongoDB Documentation website.
Bugs / Feature Reporting
New Features and bugs can be reported on jira: https://jira.mongodb.org/browse/GODRIVER
Testing / Development
To run driver tests, make sure a MongoDB server instance is running at localhost:27017. Using make, you can run make (on windows, run nmake).
This will run coverage, run go-lint, run go-vet, and build the examples.
The MongoDB Go Driver is not feature complete, so any help is appreciated. Check out the project page for tickets that need completing. See our contribution guidelines for details.
Continuous Integration
Commits to master are run automatically on evergreen.
License
The MongoDB Go Driver is licensed under the Apache License.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bson is a library for reading, writing, and manipulating BSON.
|
Package bson is a library for reading, writing, and manipulating BSON. |
|
bsoncodec
Package bsoncodec provides a system for encoding values to BSON representations and decoding values from BSON representations.
|
Package bsoncodec provides a system for encoding values to BSON representations and decoding values from BSON representations. |
|
bsonrw
Package bsonrw contains abstractions for reading and writing BSON and BSON like types from sources.
|
Package bsonrw contains abstractions for reading and writing BSON and BSON like types from sources. |
|
bsontype
Package bsontype is a utility package that contains types for each BSON type and the a stringifier for the Type to enable easier debugging when working with BSON.
|
Package bsontype is a utility package that contains types for each BSON type and the a stringifier for the Type to enable easier debugging when working with BSON. |
|
primitive
Package primitive contains types similar to Go primitives for BSON types can do not have direct Go primitive representations.
|
Package primitive contains types similar to Go primitives for BSON types can do not have direct Go primitive representations. |
|
cmd
|
|
|
examples
|
|
|
Package mongo provides a MongoDB Driver API for Go.
|
Package mongo provides a MongoDB Driver API for Go. |
|
x
|
|
|
bsonx/bsoncore
Package bsoncore contains functions that can be used to encode and decode BSON elements and values to or from a slice of bytes.
|
Package bsoncore contains functions that can be used to encode and decode BSON elements and values to or from a slice of bytes. |
|
mongo/driver/auth
Package auth is not for public use.
|
Package auth is not for public use. |
|
mongo/driver/topology
Package topology contains types that handles the discovery, monitoring, and selection of servers.
|
Package topology contains types that handles the discovery, monitoring, and selection of servers. |
|
network
Package network contains a MongoDB networking library.
|
Package network contains a MongoDB networking library. |
|
network/command
Package command contains abstractions for operations that can be performed against a MongoDB deployment.
|
Package command contains abstractions for operations that can be performed against a MongoDB deployment. |
|
network/connection
Package connection contains the types for building and pooling connections that can speak the MongoDB Wire Protocol.
|
Package connection contains the types for building and pooling connections that can speak the MongoDB Wire Protocol. |
|
network/integration/internal/israce
Package israce reports if the Go race detector is enabled.
|
Package israce reports if the Go race detector is enabled. |
|
network/result
Package result contains the results from various operations.
|
Package result contains the results from various operations. |
|
network/wiremessage
Package wiremessage contains types for speaking the MongoDB Wire Protocol.
|
Package wiremessage contains types for speaking the MongoDB Wire Protocol. |