Skip to content
The Go driver for MongoDB
Branch: master
Clone or download
Pull request Compare This branch is 256 commits behind mongodb:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.evergreen
benchmark
bson
cmd/godriver-benchmark
data
etc
event
examples/documentation_examples
internal
mongo
tag
vendor
version
x
.errcheck-excludes
.gitignore
.gitmodules
.lint-whitelist
CONTRIBUTING.md
Gopkg.lock
Gopkg.toml
LICENSE
Makefile
README.md
THIRD-PARTY-NOTICES

README.md

GoDoc GoDoc

MongoDB Go Driver

The MongoDB supported driver for Go.



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.

You can’t perform that action at this time.