Skip to content
The Go driver for MongoDB
Go Perl C Python Makefile Shell C++
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.evergreen Upgrade Evergreen config to Windows 2017 (#274) Jan 14, 2020
benchmark Update import path to go.mongodb.org/mongo-driver Feb 22, 2019
bson GODRIVER-1460 document mgocompat (#279) Jan 22, 2020
cmd Update templates for maintainability May 31, 2019
data GODRIVER-1427 Resync sessions spec tests (#278) Jan 14, 2020
etc Remove usage of the TOPOLOGY environment variable in tests. (#195) Oct 10, 2019
event GODRIVER-628 connections survive primary stepdown Aug 12, 2019
examples/documentation_examples Remove usage of the TOPOLOGY environment variable in tests. (#195) Oct 10, 2019
internal Support zstd compression (#168) Oct 7, 2019
mongo Fix typo in SetWriteConcern client option documentation (#283) Jan 23, 2020
tag Update import path to go.mongodb.org/mongo-driver Feb 22, 2019
vendor GODRIVER-1455 switch zstd implementation to pure go (#268) Jan 6, 2020
version Update version to 1.3.0+prerelease (#253) Dec 10, 2019
x GODRIVER-1435 Add tlsCertificateFile and tlsPrivateKeyFile URI options ( Jan 14, 2020
.errcheck-excludes Use testing library for sessions tests. Sep 12, 2019
.gitignore Implement the client-side encryption specification. Aug 22, 2019
.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 GODRIVER-1455 switch zstd implementation to pure go (#268) Jan 6, 2020
Gopkg.toml GODRIVER-1455 switch zstd implementation to pure go (#268) Jan 6, 2020
LICENSE Create LICENSE May 26, 2017
Makefile Implement the client-side encryption specification. Aug 22, 2019
README.md Remove version number from README instructions (#220) Nov 11, 2019
THIRD-PARTY-NOTICES Update templates for maintainability May 31, 2019

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 "go.mongodb.org/mongo-driver/mongo"

Usage

To get started with the driver, import the mongo package, create a mongo.Client:

import (
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
)

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

The driver tests can be run against several database configurations. The most simple configuration is a standalone mongod with no auth, no ssl, and no compression. To run these basic driver tests, make sure a standalone MongoDB server instance is running at localhost:27017. To run the tests, you can run make (on Windows, run nmake). This will run coverage, run go-lint, run go-vet, and build the examples.

Testing Different Topologies

To test a replica set or sharded cluster, set MONGODB_URI="<connection-string>" for the make command. For example, for a local replica set named rs1 comprised of three nodes on ports 27017, 27018, and 27019:

MONGODB_URI="mongodb://localhost:27017,localhost:27018,localhost:27018/?replicaSet=rs1" make

Testing Auth and SSL

To test authentication and SSL, first set up a MongoDB cluster with auth and SSL configured. Testing authentication requires a user with the root role on the admin database. The Go Driver repository comes with example certificates in the data/certificates directory. These certs can be used for testing. Here is an example command that would run a mongod with SSL correctly configured for tests:

mongod \
--auth \
--sslMode requireSSL \
--sslPEMKeyFile $(pwd)/data/certificates/server.pem \
--sslCAFile $(pwd)/data/certificates/ca.pem \
--sslWeakCertificateValidation

To run the tests with make, set MONGO_GO_DRIVER_CA_FILE to the location of the CA file used by the database, set MONGODB_URI to the connection string of the server, set AUTH=auth, and set SSL=ssl. For example:

AUTH=auth SSL=ssl MONGO_GO_DRIVER_CA_FILE=$(pwd)/data/certificates/ca.pem  MONGODB_URI="mongodb://user:password@localhost:27017/?authSource=admin" make

Notes:

  • The --sslWeakCertificateValidation flag is required on the server for the test suite to work correctly.
  • The test suite requires the auth database to be set with ?authSource=admin, not /admin.

Testing Compression

The MongoDB Go Driver supports wire protocol compression using Snappy, zLib, or zstd. To run tests with wire protocol compression, set MONGO_GO_DRIVER_COMPRESSOR to snappy, zlib, or zstd. For example:

MONGO_GO_DRIVER_COMPRESSOR=snappy make

Ensure the --networkMessageCompressors flag on mongod or mongos includes zlib if testing zLib compression.


Feedback

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.

You can’t perform that action at this time.