The Go driver for MongoDB
Branch: master
Clone or download
iwysiu GODRIVER-194 add ChangeStream examples for docs
Change-Id: Ifd84577c877ef2738f555eb8eadc4cb192fda42c
Latest commit bda3cf7 Feb 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.evergreen Implement legacy OP_QUERY, OP_GET_MORE, and OP_KILL_CURSORS Dec 10, 2018
benchmark Update options and remove exposed x in mongo Feb 19, 2019
bson Merge branch 'pr/133' Feb 13, 2019
cmd/godriver-benchmark Add missing copyright notices to all .go files Nov 5, 2018
data GODRIVER-524 implement SDAM error handling Feb 20, 2019
etc Update README.md Dec 6, 2018
event Remove exposure of bsonx package in stable API Dec 20, 2018
examples/documentation_examples GODRIVER-194 add ChangeStream examples for docs Feb 21, 2019
internal Fix aggregate maxTimeMS integration test. Feb 7, 2019
mongo GODRIVER-840 fix mongo.Client() example in doc.go Feb 21, 2019
tag Restructure repository Nov 19, 2018
vendor Enable dep support Dec 4, 2018
version Update version to v1.0.0-rc1+prerelease Feb 1, 2019
x GODRIVER-803 add AuthenticateArbiter client option to allow authentic… Feb 21, 2019
.errcheck-excludes Fix cursor types and implement BatchCursor Jan 31, 2019
.gitignore GODRIVER-115: driver benchmarks and bson benchmarks Jun 15, 2018
.gitmodules GODRIVER-33 Implement Extended JSON Dec 7, 2017
.lint-whitelist Update Makefile to run examples and fix bugs in examples Feb 12, 2019
CONTRIBUTING.md Update README.md and CONTRIBUTING.md Feb 12, 2018
Gopkg.lock Enable dep support Dec 4, 2018
Gopkg.toml Enable dep support Dec 4, 2018
LICENSE Create LICENSE May 26, 2017
Makefile Update Makefile to run examples and fix bugs in examples Feb 12, 2019
README.md update readme to reflect latest breaking changes to init client conne… Feb 20, 2019
THIRD-PARTY-NOTICES Vendor and remove from internal JSON packages Jul 1, 2018

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 2.6 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(options.Client().ApplyURI("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, options.Client().ApplyURI("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, bson.D{})
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.


Thanks and Acknowledgement

@ashleymcnamara - Mongo Gopher Artwork


License

The MongoDB Go Driver is licensed under the Apache License.